 |
HP OpenVMS System Services Reference Manual
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
Refer to the HP OpenVMS System Manager's Manual for more information.
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.
|
|
