OpenVMS System Services Reference Manual

Document revision date: 19 July 1999

OpenVMS System Services Reference Manual

Contents

Index

$HIBER

Allows a process to make itself inactive but to remain known to the system so that it can be interrupted; for example, to receive ASTs.

Format

SYS$HIBER

C Prototype

int sys$hiber (void);

Arguments

None.

Description

The Hibernate service allows a process to make itself inactive but to remain known to the system so that it can be interrupted; for example, to receive ASTs. A hibernate request is a wait-for-wake-event request. When you call the Wake Process from Hibernation ($WAKE) service or when the time specified with the Schedule Wakeup ($SCHDWK) service occurs, the process continues execution at the instruction following the Hibernate call.
In VAX MACRO, you can call the Hibernate service only by using the $name_S macro.
A hibernating process can be swapped out of the balance set if it is not locked into the balance set.
An AST can interrupt the wait state caused by $HIBER if the access mode at which the AST is to execute is equal to or more privileged than the access mode from which the hibernate request was issued and the process is enabled for ASTs at that access mode.
When the AST service routine completes execution, the system reexecutes the $HIBER service on behalf of the process. If a wakeup request has been issued for the process during the execution of the AST service routine (either by itself or another process), the process resumes execution. If a wakeup request has not been issued, it continues to hibernate.
If one or more wakeup requests are issued for the process while it is not hibernating, the next hibernate call returns immediately; that is, the process does not hibernate. No count of outstanding wakeup requests is maintained.
Although this service has no arguments, a Fortran function reference must use parentheses to indicate a null argument list, as in the following example:
ISTAT=SYS$HIBER()
Required Access or Privileges

None
Required Quota

None
Related Services

$CANEXH, $CREPRC, $DCLEXH, $DELPRC, $EXIT, $FORCEX, $GETJPI, $GETJPIW, $PROCESS_SCAN, $RESUME, $SETPRI, $SETPRN, $SETPRV, $SETRWM, $SUSPND, $WAKE

Condition Values Returned

SS$_NORMAL The service completed successfully.

$ICC_ACCEPT

Responds to an incoming connection request. This call is used to complete an ICC connection from the server side.
On Alpha systems, this service accepts 64-bit addresses.

Format

SYS$ICC_ACCEPT conn_handle ,[accept_buf] ,[accept_len] ,[user_context] ,[flags]

C Prototype:

int sys$icc_accept (unsigned int conn_handle, char * accept_buf, unsigned int accept_len, unsigned int user_context, unsigned int flags);

Arguments

conn_handle

OpenVMS usage: connection_id

type: longword (unsigned)

access: read only

mechanism: by value

The handle of the requested connection.
accept_buf

OpenVMS usage: byte_stream

type: character-coded text string

access: read only

mechanism: by 32-bit or 64-bit reference (Alpha)

mechanism: by 32-bit reference (VAX)

A buffer of up to 1000 bytes of accept data that is sent to the source of the connection at the completion of the connection process.
accept_len

OpenVMS usage: buffer_length

type: longword (unsigned)

access: read only

mechanism: by value

The actual number of bytes in accept_buf to be sent.
user_context

OpenVMS usage: user_arg

type: longword (unsigned) (VAX), quadword (Alpha)

access: read only

mechanism: by value

A user-specified value that is subsequently returned on any disconnect or data events on this connection.
flags

OpenVMS usage: mask_longword

type: longword (unsigned)

access: read only

mechanism: by value

ICC$M_SYNCH_MODE can be specified to indicate that the data transmission and reception routines $ICC_TRANSMIT, $ICC_RECEIVE, and $ICC_REPLY are allowed to return the status SS$_SYNCH in the case of synchronous completion, and that the AST will not be called.

Description

This service is used by a server to respond to an incoming connection request. The $ICC_ACCEPT service may only be called after receiving a connection request AST.
At the completion of the service, the connection is open and data can be exchanged. Once opened, there is no logical distinction between a connection opened by a client with the Connect service or a server with the Accept service.
A server can reject a Connection request by calling the $ICC_REJECT service.
Required Access or Privileges

None.
Required Quota

$ICC_ACCEPT changes the process BYTLM quota for the length of the accept_buf parameter, as well as a fixed value for each potential Receive buffer on the connection. The number of potential Receive buffers is specified by the MAXFLOWBUFCNT parameter in the $ICC_OPEN_ASSOC service.
Related Services

$ICC_CLOSE_ASSOC, $ICC_CONNECT, $ICC_CONNECTW, $ICC_DISCONNECT, $ICC_DISCONNECTW, $ICC_OPEN_ASSOC, $ICC_RECEIVE, $ICC_RECEIVEW, $ICC_REJECT, $ICC_REPLY, $ICC_REPLYW, $ICC_TRANSCEIVE, $ICC_TRANSCEIVEW, $ICC_TRANSMIT, $ICC_TRANSMITW

Condition Values Returned

SS$_NORMAL Normal completion.

SS$_ACCVIO Access violation on parameter.

SS$_BADPARAM Bad parameter value specified.

SS$_CLEARED Remote association closed the link before it was accepted.

SS$_EXQUOTA Exceeded BYTCNT/BYTLM.

SS$_INSFARG Too few arguments supplied.

SS$_INSFMEM Not enough system resources or process virtual memory available.

SS$_IVMODE Attempted to accept a connection from a more privileged access mode than the requested association.

SS$_IVCHAN Connection not found or Invalid connection handle.

SS$_LINKDISCON The connection is valid, but the physical link has started to disconnect.

SS$_TOO_MANY_ARGS Too many arguments specified.

SS$_WRONGSTATE Connection is in the wrong state for the request.

$ICC_CLOSE_ASSOC

Closes the application's association with ICC.

Format

SYS$ICC_CLOSE_ASSOC assoc_handle

C Prototype:

int sys$icc_close_assoc (unsigned int assoc_handle);

Arguments

assoc_handle

OpenVMS usage: association_id

type: longword (unsigned)

access: read only

mechanism: by value

The handle of the association to be closed.

Description

This service closes the application's association with ICC. If multiple associations are open, only the specified association is closed. When an association is closed, any active connections on that association are disconnected. If not explicitly closed by the application, associations opened in user mode will be closed at image exit; associations opened in inner modes will be closed at process termination.
All operations on an association must occur in the access mode at which the association was opened.
When an association is closed, the entry (if any) in the simple clusterwide association registry is removed.
Required Access or Privileges

None.
Required Quota

None.
Related Services

$ICC_ACCEPT, $ICC_CONNECT, $ICC_CONNECTW, $ICC_DISCONNECT, $ICC_DISCONNECTW, $ICC_OPEN_ASSOC, $ICC_RECEIVE, $ICC_RECEIVEW, $ICC_REJECT, $ICC_REPLY, $ICC_REPLYW, $ICC_TRANSCEIVE, $ICC_TRANSCEIVEW, $ICC_TRANSMIT, $ICC_TRANSMITW

Condition Values Returned

SS$_NORMAL Normal completion.

SS$_INSFARG The assoc_handle was not supplied.

SS$_IVCHAN Invalid association handle.

SS$_IVMODE Attempted to close an association from a more privileged access mode than the requested association.

SS$_TOO_MANY_ARGS Too many arguments specified.

$ICC_CONNECT

Establishes a connection to a remote application over an open association.
On Alpha systems, this service accepts 64-bit addresses.

Format

SYS$ICC_CONNECT ios_icc ,[astadr] ,[astprm] ,assoc_handle ,conn_handle ,remote_assoc ,[remote_node] ,[user_context] ,[conn_buf] ,[conn_buf_len] ,[return_buf] ,[return_buf_len] ,[retlen_addr] ,[flags]

C Prototype:

int sys$icc_connect (struct _ios_icc *ios_icc, void (*astadr)(__unknown_params), __int64 astprm, unsigned int assoc_handle, unsigned int *conn_handle, void *remote_assoc, void *remote_node, unsigned int user_context, char *conn_buf, unsigned int conn_buf_len, char *return_buf, unsigned int return_buf_len, unsigned int *retlen_addr, unsigned int flags);

Arguments

ios_icc

OpenVMS usage: io_status_block

type: quadword (unsigned)

access: write only

mechanism: by 32-bit or 64-bit reference (Alpha)

mechanism: by 32-bit reference (VAX)

I/O status block:
+2 0 ------------------------------------------------- | Undefined | Completion status | ------------------------------------------------- | ios_icc$l_remstat | ------------------------------------------------- +6 +4
Completion status values:
SS$_NORMAL, SS$_BUFFEROVF, SS$_EXQUOTA, SS$_INSFMEM, SS$_IVBUFLEN, SS$_LINKABORT, SS$_LINKDISCON, SS$_NOLOGNAM, SS$_NOSUCHID, SS$_NOSUCHNODE, SS$_PATHLOST, SS$_REJECT, SS$_SSFAIL, SS$_UNREACHABLE, SS$_WRONGSTATE
The second longword is undefined unless the completion code is SS$_REJECT. In this case, the application-defined rejection reason code is supplied by the server when $ICC_REJECT is called.
astadr

OpenVMS usage: ast_procedure

type: procedure_entry_mask

access: call without stack unwinding

mechanism: by 32-bit or 64-bit linkage reference (Alpha)

mechanism: by 32-bit reference (VAX)

The AST routine to be executed when the operation completes.
astprm

OpenVMS usage: user_arg

type: quadword (unsigned) (Alpha), longword (unsigned) (VAX)

access: read only

mechanism: by 64-bit value (Alpha)

mechanism: by 32-bit value (VAX)

The parameter to be passed to the AST routine.
assoc_handle

OpenVMS usage: association_id

type: longword (unsigned)

access: read only

mechanism: by value

The handle of the association on which the connection is to be opened. The constant ICC$C_DFLT_ASSOC_HANDLE, if used, indicates that the default association is to be used (and opened if necessary).
conn_handle

OpenVMS usage: longword_unsigned

type: longword (unsigned)

access: write only

mechanism: by 32-bit or 64-bit reference (Alpha)

mechanism: by 32-bit reference (VAX)

The 32-bit or 64-bit address (on Alpha systems) or the 32-bit address (on VAX systems) of a longword into which $ICC_CONNECT writes the connection handle of the created connection on a successful call.
remote_assoc

OpenVMS usage: char_string

type: character-coded text string

access: read only

mechanism: by 32-bit or 64-bit descriptor (Alpha)

mechanism: by 32-bit descriptor (VAX)

An ASCII character string (31 characters maximum) specifying the name of the target application to connect to. Association names are case-sensitive.
remote_node

OpenVMS usage: char_string

type: character-coded text string

access: read only

mechanism: by 32-bit or 64-bit descriptor (Alpha)

mechanism: by 32-bit descriptor (VAX)

The name of the node where the target association resides. A null or blank string can be used to indicate the local node. If omitted (by passing zero by value), the simple clusterwide association registry is to be used. Each node name is a one-to-six character SCS node name. A comma-delimited list of nodes may be specified, indicating that one is to be chosen at random.
user_context

OpenVMS usage: user_arg

type: longword (unsigned) (VAX), quadword (Alpha)

access: read only

mechanism: by value

A user-specified value to be subsequently returned on any disconnect or data events on this connection.
conn_buf

OpenVMS usage: byte_stream

type: character-coded text string

access: read only

mechanism: by 32-bit or 64-bit reference (Alpha)

mechanism: by 32-bit reference (VAX)

A buffer of up to 1000 bytes of connection data to be sent to the target of the connection during the connection process.
conn_buf_len

OpenVMS usage: buffer_length

type: longword (unsigned)

access: read only

mechanism: by value

The number of bytes in conn_buf to be sent.
return_buf

OpenVMS usage: byte_stream

type: character-coded text string

access: read only

mechanism: by 32-bit or 64-bit reference (Alpha)

mechanism: by 32-bit reference (VAX)

A buffer of up to 1000 bytes in length to receive any incoming connection accept or reject data returned.
return_buf_len

OpenVMS usage: buffer_length

type: longword (unsigned)

access: read only

mechanism: by value

The length of the supplied return_buf.
retlen_addr

OpenVMS usage: longword_unsigned

type: longword (unsigned)

access: write only

mechanism: by 32-bit or 64-bit reference (Alpha)

mechanism: by 32-bit reference (VAX)

The 32-bit or 64-bit address (on Alpha systems) or the 32-bit address (on VAX systems) of a longword into which $ICC_CONNECT writes the actual length (in bytes) of any user accept or reject data returned in the buffer return_buf.
flags

OpenVMS usage: mask_longword

type: longword (unsigned)

access: read only

mechanism: by value

ICC$M_SYNCH_MODE can be specified to indicate that the data transmission and reception routines $ICC_TRANSMIT, $ICC_RECEIVE, and $ICC_REPLY are allowed to return the status SS$_SYNCH in the case of synchronous completion, indicating that the AST will not be called.

Description

This service establishes a connection to a remote application over an open association. Connections must be opened in the same mode as their association. If the user provides the default association constant ICC$C_DFLT_ASSOC_HANDLE as its association handle, the default association will be used; it will be opened if it is not already open. Multiple connections are possible over a single association. When completion is signaled by the AST routine, the application must check the completion status field of the IOS_ICC to determine if the server has accepted or rejected the connection request. The number of connections is subject to process BYTLM quota.
At image exit, as a result of closing any open user mode associations, all user mode connections are disconnected. Inner mode connections are the responsibility of the inner mode code, but are disconnected at process termination when inner mode associations are closed. Connections are only visible to the mode in which they were opened.
A client opens connections with the $ICC_CONNECT service; a server opens connections with the $ICC_ACCEPT service.
Required Access or Privileges

SYSNAM, or access via ICC Security Object. Refer to the OpenVMS System Manager's Manual for more information.
Required Quota

$ICC_CONNECT changes the process BYTLM quota for the length of the conn_buf parameter, as well as a fixed value for each potential Receive buffer on the connection. The number of potential Receive buffers is specified by the MAXFLOWBUFCNT parameter in the $ICC_OPEN_ASSOC service.
If $ICC_OPEN_ASSOC is not called before $ICC_CONNECT, the default value of MAXFLOWBUFCNT is used (currently 5).
Related Services

$ICC_ACCEPT, $ICC_CLOSE_ASSOC, $ICC_CONNECTW, $ICC_DISCONNECT, $ICC_DISCONNECTW, $ICC_OPEN_ASSOC, $ICC_RECEIVE, $ICC_RECEIVEW, $ICC_REJECT, $ICC_REPLY, $ICC_REPLYW, $ICC_TRANSCEIVE, $ICC_TRANSCEIVEW, $ICC_TRANSMIT, $ICC_TRANSMITW

Condition Values Returned

SS$_NORMAL Normal completion.

SS$_ACCVIO Access violation on parameter.

SS$_BADPARAM Bad parameter value specified.

SS$_BUFFEROVF Overflow on inbound accept or reject data.

SS$_EXQUOTA Not enough AST quota (asynchronous request) or insufficient BYTLM/BYTCNT.

SS$_INSFARG Too few arguments were supplied, or required arguments not supplied.

SS$_INSFMEM Not enough system resources or process virtual memory available.

SS$_INSFP1POOL Not enough process P1 space available.

SS$_IVBUFLEN The length of the context data or the accept or reject data buffer is more than 1000 bytes.

SS$_IVCHAN Invalid association handle.

SS$_IVMODE Attempted to open a connection from a more privileged access mode than the requested association.

SS$_LINKABORT The communications link to the target node was lost.

SS$_LINKDISCON The communications link to the target node was lost.

SS$_NOLINKS Too many connections open.

SS$_NOLOGNAM The underlying layers failed to start properly during system initialization.

SS$_NOSUCHOBJECT The remote association name and/or node was not found.

SS$_NOSUCHNODE The target node is not known.

SS$_PATHLOST The communications link to the target node was lost.

SS$_REMRSRC Insufficient resources at remote node.

SS$_REJECT The remote association or node rejected the connection request.

SS$_TOO_MANY_ARGS Too many arguments specified.

SS$_UNREACHABLE Target node currently unreachable.

SS$_WRONGSTATE Connection is in the wrong state for the request.

Contents

Index

privacy and legal statement

4527PRO_057.HTML

OpenVMS usage:	connection_id
type:	longword (unsigned)
access:	read only
mechanism:	by value

OpenVMS usage:	byte_stream
type:	character-coded text string
access:	read only
mechanism:	by 32-bit or 64-bit reference (Alpha)
mechanism:	by 32-bit reference (VAX)

OpenVMS usage:	buffer_length
type:	longword (unsigned)
access:	read only
mechanism:	by value

OpenVMS usage:	user_arg
type:	longword (unsigned) (VAX), quadword (Alpha)
access:	read only
mechanism:	by value

OpenVMS usage:	mask_longword
type:	longword (unsigned)
access:	read only
mechanism:	by value

SS$_NORMAL	Normal completion.
SS$_ACCVIO	Access violation on parameter.
SS$_BADPARAM	Bad parameter value specified.
SS$_CLEARED	Remote association closed the link before it was accepted.
SS$_EXQUOTA	Exceeded BYTCNT/BYTLM.
SS$_INSFARG	Too few arguments supplied.
SS$_INSFMEM	Not enough system resources or process virtual memory available.
SS$_IVMODE	Attempted to accept a connection from a more privileged access mode than the requested association.
SS$_IVCHAN	Connection not found or Invalid connection handle.
SS$_LINKDISCON	The connection is valid, but the physical link has started to disconnect.
SS$_TOO_MANY_ARGS	Too many arguments specified.
SS$_WRONGSTATE	Connection is in the wrong state for the request.

OpenVMS usage:	association_id
type:	longword (unsigned)
access:	read only
mechanism:	by value

OpenVMS usage:	io_status_block
type:	quadword (unsigned)
access:	write only
mechanism:	by 32-bit or 64-bit reference (Alpha)
mechanism:	by 32-bit reference (VAX)

OpenVMS usage:	ast_procedure
type:	procedure_entry_mask
access:	call without stack unwinding
mechanism:	by 32-bit or 64-bit linkage reference (Alpha)
mechanism:	by 32-bit reference (VAX)

OpenVMS usage:	longword_unsigned
type:	longword (unsigned)
access:	write only
mechanism:	by 32-bit or 64-bit reference (Alpha)
mechanism:	by 32-bit reference (VAX)

OpenVMS usage:	char_string
type:	character-coded text string
access:	read only
mechanism:	by 32-bit or 64-bit descriptor (Alpha)
mechanism:	by 32-bit descriptor (VAX)