HP OpenVMS System Services Reference Manual
Previous Contents Index

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.

Format 


DataEventRtn  message_size ,conn_handle ,user_context

C Prototype 


void DataEventRtn  (unsigned int message_size, unsigned int conn_handle, 
                    unsigned int user_context);

Arguments 


message_size
Type:       longword (unsigned) 
Access:     read only 
Mechanism:  by value

This field will contain the number of bytes in the pending data event. 


conn_handle
Type:       longword (unsigned) 
Access:     read only 
Mechanism:  by value

The handle of the connection associated with the event. This value should be used as the conn_handle argument to $ICC_RECEIVE. 


user_context
Type:       longword (unsigned) (VAX); quadword (Alpha and I64) 
Access:     read only 
Mechanism:  by value

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.

3. Completion ASTs

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.

Required Access or Privileges

For more information, see the HP OpenVMS System Manager's Manual.

Required Quota

BYTCNT, BYTLM

Related Services

$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

Condition Values Returned

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.

$ICC_RECEIVE

Receives a single message over a connection.

On Alpha and I64 systems, this service accepts 64-bit addresses.

Format

SYS$ICC_RECEIVE conn_handle ,ios_icc ,[astadr] ,[astprm] ,recv_buf ,recv_buf_len

C Prototype

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);

Arguments

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 I64); by 32-bit reference (VAX)

I/O status block:

Completion codes:

SS$_NORMAL, SS$_EXQUOTA, SS$_INSFMEM, SS$_LINKDISCON, SS$_BUFOVL, SS$_ACCVIO

astadr


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

The AST routine to be executed when the operation completes.

astprm


OpenVMS usage: user_arg
type: quadword (unsigned) (Alpha and I64); longword (unsigned) (VAX)
access: read only
mechanism: by 64-bit value (Alpha and I64); by 32-bit value (VAX)

The parameter to be passed to the AST routine.

recv_buf


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

The 32-bit or 64-bit address (on Alpha and I64 systems) or the 32-bit address (on VAX systems) of the buffer to receive the incoming data. The length of this buffer is specified by the argument recv_buf_len.

recv_buf_len


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

The length (in bytes) of the buffer available to hold the incoming data. This value specifies the length of the buffer recv_buf.

IOS_ICC Arguments:

recvlen (output)


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

This parameter is returned in the ios_icc. $ICC_RECEIVE writes the actual length of the incoming data message received from the target application (in bytes) into offset ios_icc$l_rcv_len of the ios_icc.

request_handle (output)


OpenVMS usage: request_id
type: longword (unsigned)
access: write only
mechanism: by value

This parameter is returned in the ios_icc. $ICC_RECEIVE writes the Request/Response handle into offset ios_icc$l_req_handle of the ios_icc. The request_handle argument is nonzero if the application is expected to reply to this message.

reply_len (output)


OpenVMS usage: longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by value

This parameter is returned in the ios_icc. The $ICC_RECEIVE service writes the maximum length (in bytes) of the expected Reply message into offset ios_icc$l_reply_len of the ios_icc, if request_handle is nonzero.

Description

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.

Required Access or Privileges

None.

Required Quota

BYTLM

Related Services

$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

Condition Values Returned

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.

$ICC_RECEIVEW

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 I64 systems, this service accepts 64-bit addresses.

Format

SYS$ICC_RECEIVEW conn_handle ,ios_icc ,[astadr] ,[astprm] ,recv_buf ,recv_buf_len

C Prototype

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);

$ICC_REJECT

Refuses a connection request.

On Alpha and I64 systems, this service accepts 64-bit addresses.

Format

SYS$ICC_REJECT conn_handle, [reject_buf], [reject_buf_len], [reason]

C Prototype

int sys$icc_reject (unsigned int conn_handle, char * reject_buf, unsigned int reject_buf_len, unsigned int reason);

Arguments

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 I64); by 32-bit reference (VAX)

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

Description

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.

Required Access or Privileges

None.

Required Quota

None.

Related Services

$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

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 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.

$ICC_REPLY

Sends a single message over a connection. This service is used in response to the reception of a Request Handle in a previous $ICC_RECEIVE system service.

On Alpha and I64 systems, this service accepts 64-bit addresses.

Format

SYS$ICC_REPLY conn_handle ,ios_icc ,[astadr] ,[astprm] ,reply_buf ,reply_len

C Prototype

sys$icc_reply (unsigned int conn_handle, struct _ios_icc *ios_icc, void (*astadr)(__unknown_params), __int64 astprm, char *reply_buf, unsigned int reply_len);

Arguments

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: quadword (unsigned)
access: modify
mechanism: by 32-bit or 64-bit reference (Alpha and I64); by 32-bit reference (VAX)

I/O status block:

Completion status values:

SS$_NORMAL, SS$_EXQUOTA, SS$_INSFMEM, SS$_LINKABORT, SS$_LINKDISCON

astadr


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

The AST routine to be executed when the operation completes.

astprm


OpenVMS usage: user_arg
type: quadword (unsigned) (Alpha and I64); longword (unsigned) (VAX)
access: read only
mechanism: by 64-bit value (Alpha and I64); by 32-bit value (VAX)

The parameter to be passed to the AST routine.

reply_buf


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

The 32-bit or 64-bit address (on Alpha and I64 systems) or the 32-bit address (on VAX systems) of the buffer containing the reply data to be sent. The length of this buffer is specified by the argument reply_len.

reply_len


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

The length (in bytes) of the reply data to be sent over the connection. This value specifies the length of the buffer reply_buf. ICC segments larger buffers internally.

The maximum Reply length is the smaller of the Reply buffer size supplied in the $ICC_RECEIVE call, or 1MB.

IOS_ICC Argument:

request_handle (input)


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

This parameter is passed through the ios_icc. The Request/Response handle from the received Transceive request is placed at offset ios_icc$l_replyto_handle of the ios_icc.

Description

This service is almost identical to the $ICC_TRANSMIT system service in that it sends a single message over a connection. The only difference is that it is used in response to the reception of a Request Handle in a previous Receive Data system service.

When completion is signaled by calling the AST (if supplied), the data has been delivered to the communications system, but not necessarily to the application at the other end of the connection. The user can reuse the buffer after completion has been signaled.

Alternatively, if the synchronous completion option was requested at connection time, the service may return the optional success status, SS$_SYNCH. When SS$_SYNCH is returned, completion has occurred, and no AST will be delivered.

Required Access or Privileges

None.

Required Quota

BYTLM (for Reply buffer)

Related Services

$ICC_ACCEPT, $ICC_CLOSE_ASSOC, $ICC_CONNECT, $ICC_CONNECTW, $ICC_DISCONNECT, $ICC_DISCONNECTW, $ICC_OPEN_ASSOC, $ICC_RECEIVE, $ICC_RECEIVEW, $ICC_REJECT, $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$_EXBYTLM Insufficient byte count quota.
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 An Incoming disconnect event is already in progress.
SS$_NOSUCHID The request_handle is invalid.
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.

Previous Next Contents Index