| Previous | Contents | Index |
This routine will be called in the mode of the caller. (No mechanism is provided for the routine to be called at a different mode).
| OpenVMS usage: | longword_unsigned |
| type: | longword (unsigned) |
| access: | read only |
| mechanism: | by value |
Default = 5 (Pass 0 to get the default)
| OpenVMS usage: | longword_unsigned |
| type: | longword (unsigned) |
| access: | read only |
| mechanism: | by value |
The default protection scheme for this association is as follows:
0 - access for everyone (default)
1 - stops WORLD access
2 - stops both WORLD and GROUP access
Advanced access control is provided by ICC Security objects. For information about ICC system management and security, see the HP OpenVMS System Manager's Manual.
This service declares an application association with ICC. Servers must make this call to declare or register their name and to indicate their readiness to receive incoming connections. Although a client is permitted to call this routine, it is unnecessary for simple applications. A client application that wishes to be notified of disconnection events or Receive Data events must call the $ICC_OPEN_ASSOC service.A client can open a connection without specifying an open association; this automatically creates a default association name of ICC$PID_nnnnnnnn (where nnnnnnnn is a character representation of the Process ID).
NETMBX privilege is required to open any association.
The association name space is a controlled resource. For information about managing this resource, see the HP OpenVMS System Manager's Manual.
An attempt to open an association with a name not authorized as described in the HP OpenVMS System Manager's Manual will fail with the error SS$_NOPRIV returned to the caller. In addition to making entries in the system's local association name space, a call to $ICC_OPEN_ASSOC may also make an entry in a simple clusterwide registry of active associations.
An association may only be accessed from the mode in which it was opened. Inner modes are prevented from using the default association.
An application can open any number of associations subject to available process BYTLM quota. Currently, there is a systemwide limit of 512 open associations. There is no limit imposed clusterwide.
Description of User-Supplied Routines (ASTs)
When opening an association, the user may optionally supply a connect/disconnect AST and/or a Data Event AST. These routines will be used for all connections established over the specified association. In addition, for any of the asynchronous services (those provided with both an immediate return and a "W" form), a completion AST may be supplied by the user. This section describes these ASTs.
The user chooses the name of this routine and supplies the procedure name as an argument to the Open Association service. Seven arguments will be passed to the user.
The first argument notifies the user whether this is an incoming new connection or a disconnection of an existing connection. The second identifies the connection. The third and fourth provide access to incoming connect or disconnect data (if any) sent by the cooperating application. The fifth argument provides the number of bytes available for any optional Accept or Reject data (in the case of a connect request) or the disconnect reason supplied by the cooperating application (if any).
For connect events, the sixth and seventh arguments are the EPID and user name of the process requesting the connect, respectively.
The user has the choice of using and declaring a common routine or separate routines as specified when calling $OPEN_ASSOCIATION.
ConnDiscRtn event_type ,conn_handle ,data_len ,data_bfr ,P5 ,P6 ,P7
void ConDiscRtn (unsigned int event_type, unsigned int conn_handle, unsigned int data_len, char *data_bfr, unsigned int P5, unsigned int P6, char *P7);
event_type Type: longword (unsigned) Access: read only Mechanism: by valueThis field will contain a code describing the type of event. The possible event codes are defined in ICCDEF:
ICC$C_EV_CONNECT - Connection event ICC$C_EV_DISCONNECT - Disconnection event
conn_handle Type: longword (unsigned) Access: read only Mechanism: by valueThe handle of the connection associated with the event.
data_len Type: longword (unsigned) Access: read only Mechanism: by valueThe length (in bytes) of the incoming data. This value specifies the length of the buffer data_bfr, and will be between 0 and 1000, with zero indicating no data.
data_bfr Type: character-coded text string Access: read only Mechanism: by 32-bit or 64-bit value (Alpha and Integrity servers)The 32-bit address of the P1-space buffer containing the data, or zero if no data is available. The length of this buffer is specified by the argument data_len.
Upon return from the AST, the address of the data is no longer valid. An application wishing to reference the Connection or Disconnection data after Return must copy the data from the supplied buffer to storage owned by the application.
P5 Type: longword (unsigned) Access: read only Mechanism: by valueThe usage of this argument is dependent on the specified event type code (event_type).
For connect events (event_type=ICC$C_EV_CONNECT), this argument contains the length (in bytes) of the buffer available for a reply.
For disconnect events (event_type=ICC$C_EV_DISCONNECT), this argument contains the user-defined disconnect reason/status from the remote partner.
P6 Type: quadword (Alpha and Integrity servers Access: read only Mechanism: by valueThe usage of this argument is dependent on the specified event type code (event_type).
For connect events (event_type=ICC$C_EV_CONNECT), this argument contains the EPID of the process requesting the connection, passed by value.
For disconnect events (event_type=ICC$C_EV_DISCONNECT), this argument contains the user-defined user_context supplied when the connection was opened. For a client, the user_context is that supplied to the $ICC_CONNECT call. For a server, it is the value supplied to $ICC_ACCEPT.
P7 Type: character-coded text string Access: read only Mechanism: by referenceFor connect events: Username, passed by reference (to P1 space buffer) as a 12-character, space-filled string.
The application must copy this information to local storage before exiting from the connect routine.
For disconnect events, this argument is zero (0).
This routine, if supplied by the user when opening the association, allows the user to be notified of any pending data events over any connections subsequently opened over that association.
If the user has supplied this routine, the Receive service must only be called in response to incoming data events signaled by this routine, and must be called with a buffer large enough to handle the message size specified.
Use of this routine obligates the user to allocate buffers up to the size requested by the cooperating application. The only recovery provided at this time if a sufficiently large buffer cannot be allocated is to disconnect the connection. Failure to issue a receive call or disconnect may stall all further communication on this connection.
DataEventRtn message_size ,conn_handle ,user_context
void DataEventRtn (unsigned int message_size, unsigned int conn_handle, unsigned int user_context);
message_size Type: longword (unsigned) Access: read only Mechanism: by valueThis field will contain the number of bytes in the pending data event.
conn_handle Type: longword (unsigned) Access: read only Mechanism: by valueThe handle of the connection associated with the event. This value should be used as the conn_handle argument to $ICC_RECEIVE.
user_context Type: quadword (Alpha and Integrity servers Access: read only Mechanism: by valueThe user-defined user_context supplied when the connection was opened. For a client, the user context is that supplied to the $ICC_CONNECT call. For a server, it is the value supplied to $ICC_ACCEPT.
Completion ASTs may be supplied to the $ICC_CONNECT[W], $ICC_DISCONNECT[W], $ICC_TRANSMIT[W], $ICC_RECEIVE[W], $ICC_TRANSCEIVE[W], and $ICC_REPLY[W] services. In all cases, they are called at the completion of the requested operation, with the single argument, the AST parameter supplied when the original service was called, passed by value.
Completion ASTs are not called if the service returns an error prior to initiating the operation. $ICC_CONNECT and $ICC_ACCEPT accept the flag ICC$V_SYNCH_MODE which indicates that the routines $ICC_TRANSMIT[W], $ICC_RECEIVE[W], and $ICC_REPLY[W] are permitted to return the status SS$_SYNCH, which will indicate that completion has already occurred and the AST will not be called.
For more information, see the HP OpenVMS System Manager's Manual.
BYTCNT, BYTLM
$ICC_ACCEPT, $ICC_CLOSE_ASSOC, $ICC_CONNECT, $ICC_CONNECTW, $ICC_DISCONNECT, $ICC_DISCONNECTW, $ICC_RECEIVE, $ICC_RECEIVEW, $ICC_REJECT, $ICC_REPLY, $ICC_REPLYW, $ICC_TRANSCEIVE, $ICC_TRANSCEIVEW, $ICC_TRANSMIT, $ICC_TRANSMITW
SS$_NORMAL Normal completion. SS$_ACCVIO Access violation on parameter. SS$_BADPARAM Bad parameter value specified. SS$_DUPLNAM Specified association name is already registered (already exists), or default association is already open. SS$_EXQUOTA One or more process quotas has been exceeded (probably BYTCNT/BYTLM). SS$_INSFARG Too few arguments supplied. SS$_INSFMEM Not enough system resources or process virtual memory available. SS$_IVMODE Attempt to open default association from other than user mode. SS$_NOLINKS Too many associations open for this process. SS$_NONETMBX Request requires NETMBX privilege. SS$_NOPRIV No privilege for association name access or logical name table access if using the Registry. SS$_SSFAIL Transport association name table is full, systemwide. SS$_TOO_MANY_ARGS Too many arguments were specified.
Any failures from the system services: $ENQ, $DEQ, $CRELNM, $TRNLNM.
Receives a single message over a connection.On Alpha and Integrity server systems, this service accepts 64-bit addresses.
SYS$ICC_RECEIVE conn_handle ,ios_icc ,[astadr] ,[astprm] ,recv_buf ,recv_buf_len
sys$icc_receive (unsigned int conn_handle, struct _ios_icc *ios_icc, void (*astadr)(__unknown_params), __int64 astprm, char *recv_buf, unsigned int recv_buf_len);
conn_handle
OpenVMS usage: connection_id type: longword (unsigned) access: read only mechanism: by value
The handle of the fully established connection.ios_icc
OpenVMS usage: io_status_block type: four longwords (unsigned) access: write only mechanism: by 32-bit or 64-bit reference (Alpha and Integrity servers)
I/O status block:
Completion codes:
SS$_NORMAL, SS$_EXQUOTA, SS$_INSFMEM, SS$_LINKDISCON, SS$_BUFOVL, SS$_ACCVIO
| OpenVMS usage: | ast_procedure |
| type: | procedure_entry_mask |
| access: | call without stack unwinding |
| mechanism: | by 32-bit or 64-bit linkage reference (Alpha and Integrity servers) |
| OpenVMS usage: | user_arg |
| type: | quadword (unsigned) (Alpha and Integrity servers) |
| access: | read only |
| mechanism: | by 64-bit value (Alpha and Integrity servers) |
| OpenVMS usage: | byte_stream |
| type: | character-coded text string |
| access: | read only |
| mechanism: | by 32-bit or 64-bit reference (Alpha and Integrity servers) |
| OpenVMS usage: | buffer_length |
| type: | longword (unsigned) |
| access: | read only |
| mechanism: | by value |
IOS_ICC Arguments:
| OpenVMS usage: | longword unsigned |
| type: | longword (unsigned) |
| access: | write only |
| mechanism: | by value |
| OpenVMS usage: | request_id |
| type: | longword (unsigned) |
| access: | write only |
| mechanism: | by value |
| OpenVMS usage: | longword_unsigned |
| type: | longword (unsigned) |
| access: | write only |
| mechanism: | by value |
This service receives a single message over a connection. If a Request ID is returned at completion, the partner has used a Transceive system service and requires data to be returned with a Reply service.For efficiency reasons, the number of parameters on this routine has been limited to six parameters. Three additional values are returned by the ios_icc data structure.
None.
BYTLM
$ICC_ACCEPT, $ICC_CLOSE_ASSOC, $ICC_CONNECT, $ICC_CONNECTW, $ICC_DISCONNECT, $ICC_DISCONNECTW, $ICC_OPEN_ASSOC, $ICC_RECEIVEW, $ICC_REJECT, $ICC_REPLY, $ICC_REPLYW, $ICC_TRANSCEIVE, $ICC_TRANSCEIVEW, $ICC_TRANSMIT, $ICC_TRANSMITW
SS$_NORMAL Normal completion. SS$_ACCVIO Access violation on parameter. SS$_EXBYTLM Insufficient byte count quota. SS$_EXQUOTA One or more process quotas has been exceeded. SS$_INSFARG Too few arguments supplied. SS$_IVCHAN Unknown connection specified or invalid connection handle. SS$_IVMODE Attempted to use a connection from a more privileged access mode than the mode in which it was opened. SS$_LINKDISCON The connection has been disconnected. SS$_SYNCH If synchronous mode was requested at connection time, this return value indicates that completion has already occurred and the AST routine, if specified, will not be called. SS$_TOO_MANY_ARGS Too many arguments specified. SS$_WRONGSTATE Connection is in the wrong state for the request.
The Intra-Cluster Communications Receive and Wait service queues a receive request to the specified connection.The $ICC_RECEIVEW service completes synchronously; that is, it returns to the caller with data.
For asynchronous completion, use the $ICC_RECEIVE service; $ICC_RECEIVE returns to the caller as soon as the receive request is queued, without waiting for data on the connection.
On Alpha and Integrity server systems, this service accepts 64-bit addresses.
SYS$ICC_RECEIVEW conn_handle ,ios_icc ,[astadr] ,[astprm] ,recv_buf ,recv_buf_len
sys$icc_receivew (unsigned int conn_handle, struct _ios_icc *ios_icc, void (*astadr)(__unknown_params), __int64 astprm, char *recv_buf, unsigned int recv_buf_len);
Refuses a connection request.On Alpha and Integrity server systems, this service accepts 64-bit addresses.
SYS$ICC_REJECT conn_handle, [reject_buf], [reject_buf_len], [reason]
int sys$icc_reject (unsigned int conn_handle, char * reject_buf, unsigned int reject_buf_len, unsigned int reason);
conn_handle
OpenVMS usage: connection_id type: longword (unsigned) access: read only mechanism: by value
The handle of the requested connection.reject_buf
OpenVMS usage: byte_stream type: character-coded text string access: read only mechanism: by 32-bit or 64-bit reference (Alpha and Integrity servers)
A buffer of up to 1000 bytes of reject data to be sent to the source of the connection at the completion of the rejection process.reject_buf_len
OpenVMS usage: buffer_length type: longword (unsigned) access: read only mechanism: by value
The number of bytes in reject_buf to be sent.reason
OpenVMS usage: cond_code type: longword (unsigned) access: read only mechanism: by value
User-specified reject reason code to be supplied to the remote application.Default = SS$_REJECT
This service is used by a server to refuse an incoming connection request. The $ICC_REJECT service may only be called after receiving a connection request AST. After the completion of the service, the client is notified that the connection was not opened.None.
None.
$ICC_ACCEPT, $ICC_CLOSE_ASSOC, $ICC_CONNECT, $ICC_CONNECTW, $ICC_DISCONNECT, $ICC_DISCONNECTW, $ICC_OPEN_ASSOC, $ICC_RECEIVE, $ICC_RECEIVEW, $ICC_REPLY, $ICC_REPLYW, $ICC_TRANSCEIVE, $ICC_TRANSCEIVEW, $ICC_TRANSMIT, $ICC_TRANSMITW
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 rejected. SS$_INSFARG Too few arguments supplied. SS$_IVCHAN Connection not found or Invalid connection handle. SS$_LINKDISCON The transport layer has initiated disconnect before the Reject could be sent to the requester. SS$_TOO_MANY_ARGS Too many arguments specified. SS$_WRONGSTATE Connection is already open and cannot be rejected. To close the connection, call $ICC_DISCONNECT.
| Previous | Next | Contents | Index |