Document revision date: 30 March 2001

## OpenVMS System Services Reference Manual

Previous | Contents | Index

## $ICC_RECEIVE

> Receives a single message over a connection.

> On Alpha 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)
> mechanism: | 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)
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)
access: | longword (unsigned) (VAX)
mechanism: | read only
mechanism: | by 64-bit value (Alpha)

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)
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 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, 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 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)
> mechanism: | 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 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)
> mechanism: | 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)
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.

#### reply_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)

The 32-bit or 64-bit address (on Alpha 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.

## $ICC_REPLYW

> The Intra-Cluster Communications Reply and Wait service transmits a single message over a connection in response to a $ICC_TRANSCEIVE[W] request.

> The $ICC_REPLYW service completes synchronously; that is, it returns to the caller when the underlying transport layer has released use of the reply buffer.

> For asynchronous completion, use the $ICC_REPLY service; $ICC_REPLY returns to the caller as soon as the transmission request has been queued to the transport layer, without waiting for notification that the transport layer has released control of the data buffer.

> On Alpha, this service accepts 64-bit addresses.

### Format

> SYS$ICC_REPLYW conn_handle, ios_icc, [astadr], [astprm], reply_buf, reply_len

### C Prototype:

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

## $ICC_TRANSCEIVE

> Sends a single message over a connection and then waits for a reply.

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

### Format

> SYS$ICC_TRANSCEIVE

> conn_handle ,ios_icc ,[astadr] ,[astprm] ,send_buf ,send_len

### C Prototype:

> sys$icc_transceive (unsigned int conn_handle, struct _ios_icc *ios_icc, void (*astadr)(__unknown_params), __int64 astprm, char *send_buf, unsigned int send_len);

### Arguments

> #### conn_handle

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

> The handle of the fully established (open) connection.

> #### ios_icc

> OpenVMS usage: | io_status_block
> type: | five longwords (unsigned)
> access: | modify
> 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$_EXQUOTA, SS$_INSFMEM, SS$_BUFOVFL, 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)
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.

#### send_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)

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

#### send_len

OpenVMS usage: | buffer size
type: | longword (unsigned)
access: | read only
mechanism: | by value

The length (in bytes) of the data to be sent over the connection. This value specifies the length of the buffer send_buf.

IOS_ICC Arguments:

#### returned_data_len (output)

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

This parameter is passed through the ios_icc. The $ICC_TRANSCEIVE service writes the actual length (in bytes) of the reply data received into offset ios_icc$l_txrcv_len of the ios_icc. This value represents how much data in reply_buf was returned by the target application.

#### reply_buf (input)

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

This parameter is passed through the ios_icc. The 32-bit or 64-bit address (on Alpha systems) or the 32-bit address (on VAX systems) of the buffer available to receive the incoming reply message is placed in offset ios_icc$a_reply_buffer of the ios_icc.

#### reply_buf_len (input)

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

This parameter is passed through the ios_icc. The length (in bytes) of the buffer to receive the reply message. This value specifies the length of the buffer reply_buf. This value is placed in offset ios_icc$l_txreply_len of the ios_icc.

### Description

> This service sends a single message over a connection and then waits for a reply. When completion is signaled by calling the AST (if supplied), the data has been delivered to the application at the other end of the connection and that application has delivered a reply, now present in the reply buffer. The user can reuse the send and reply buffers after completion.

> Previous | Next | Contents | Index

> | privacy and legal statement |
> 4527PRO_062.HTML