 |
OpenVMS System Services Reference Manual
$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:
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:
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.
|
|
