IPCRECV

Receives a response to a connection request, thereby completing a connection, or receives data on an existing connection.

Syntax

IPCRECV  (vcdesc[,data][,dlen][,flags][,opt][result]

Parameters

vcdesc (input

32-bit integer, by value. The VC socket descriptor, a number identifying the VC socket belonging to this process through which the data will be received.

data (output)

Record or byte array, by reference. A buffer to hold the received data or a list of data descriptors (maximum of two) indicating where the data are to be distributed. For programming in "C" language, see Appendix E “C Program Language Considerations”

dlen (input/output)

32-bit integer, by reference. Gives the maximum number of bytes you are willing to receive. For a response to a connection request, this value must be 0 (or the parameter may be omitted). For actual data on an established connection, the value must be between 1 and 30,000. The returned value indicates how many bytes were actually received.

In one IPCRECV call, you can receive all the accumulated data from one or more IPCSEND calls, but you may also receive only part of the data "sent" in an IPCSEND. In order to obtain the rest of the data, you can issue another IPCRECV call.

flags (input/output)

32 bits, by reference. A bit representation of various options. The following options are defined:

flags [16] — no output (input). If nowait I/O is used and this bit is set, the flags parameter will not be updated upon completion of this IPCRECV. This allows a calling procedure to have a local flags parameter and still complete before the IPCRECV completes. This flag has no effect if waited I/O is used.
flags [25] — discarded (output). (X.25 only.) This flag indicates that the call user data, or the facility field were present, but that some or all had to be discarded. This can occur if no call user data receive option was specified or if either field is too short to hold all of the data.
flags [26] — more data (output). This flag indicates that there may be more data to be received after completion of this IPCRECV.
For TCP, this bit will always be set when normal, non-urgent data has been received because TCP sends data in stream mode, with no end-of-data indication. However, if urgent data has been received, and no more is pending, this bit will be set to 0.
For X.25, the "more data" flag indicates that the data returned is not the complete message. This will only occur if the user request was for a smaller message than was sent. The amount of data specified in dlen has been moved into data. The following part of the message will be returned in the next call to IPCRECV, unless the destroy data flag (29) was set.
flags [29] — destroy data (input). If set, this flag causes delivered data that exceeds the amount allowed by the specified dlen or byte count (for vectored data) to be discarded. Use this flag to remove data that may have arrived at your node (and queued in the NetIPC buffer) that you do not want the process to receive.
Note that in TCP stream mode, there is no mechanism to verify that data left over has been discarded.
flags [30] — preview (input). This flag allows the calling process to preview the data - that is, to read the data without removing them from the queue of data to the receiving socket.
flags [31] — vectored (input). This flag indicates that the received data are to be distributed to the addresses (vectors) given in the data parameter.

opt (input)

Record or byte array, by reference. A list of options, with associated information. The following options are defined:

call user data receive (code 5, len=n; n bytes) (output). This option provides a buffer for the return of the call user data (CUD) field if you are using the fast select facility. If call user data is present, but this option is not supplied, then the discarded flag (flags bit 25) will be set. If the buffer supplied is not long enough to contain all the data, the data is truncated and the discarded flag is set. To ensure receiving all the CUD, this buffer should be at least 128 bytes long.
data offset (code=8, length=2; 2-byte integer) (input/output). This option is valid for non-vectored compatibility mode data only. This option specifies an offset in bytes from the data parameter's address. The received data are to be written into memory beginning at this location.
protocol flags (code=144, length=4; 4-byte buffer) (output). This option contains 32 bits of protocol-specific flags. The following flags are currently defined:
- end-to-end acknowledgment (bit 18, output). (X.25 only.) This flag indicates that the D bit is set in the X.25 packet associated with this call.
- qualifier bit (bit 19, output). (X.25 only.) This flag indicates that the Q bit is set in the X.25 packet associated with this call.
- urgent data (bit 27, output). (TCP only.) This flag indicates that urgent data has been received on an established connection.

Facility field (code=145, length=n, n bytes) (output). (X.25 only). This option provides a buffer for the return of the facility field. If the buffer is not long enough to contain all of the data, then the data is truncated and the discarded flag (bit 25) is set. This buffer should be at least 109 bytes long to ensure receipt of the facility field (for more information, see Chapter 1 “NetIPC Fundamentals”)




	NOTE: If using nowait I/O and `opt` array options that generate output, the array must remain intact until after `IOWAIT` completes. Otherwise, the array area will be overwritten or (if the area has been deleted from the stack) an error will occur.

result (output)

32-bit integer, by reference. The error code returned; zero if no error.




	NOTE: When nowait I/O is used, the `result` parameter is not updated upon completion of an intrinsic. Therefore, the value of `result` will indicate only whether the call was successfully initiated. To determine if the call completed successfully, you can use the `IPCCHECK` intrinsic after `IOWAIT` completes.

Description

The IPCRECV intrinsic serves two purposes: (1) to receive a response to a connection request, thereby completing a connection, and (2) to receive user data on an established connection.




	NOTE: In the first case the VC socket descriptor is the only required parameter; in the second, the VC socket descriptor, data, and data length parameters are required. The brackets in the syntax diagram represent the first case.

In receiving a response to a connection request, the IPCRECV intrinsic returns nothing in the data buffer. A result value of zero indicates a successful connection establishment. For X.25 only, the facility field and call user data field are returned in the option field. The result parameter will indicate an error if the destination rejected the request. In that case you must still call IPCSHUTDOWN with the returned VC socket descriptor value to shut down the connection.

Successful completion of an IPCRECV request on an established connection (result code zero) means that some amount of data was received: the amount requested or the amount transmitted, whichever is smaller. It does not mean that you received all the data you asked for.

Completion of IPCRECV (in wait mode) with a non-zero result can mean that a fatal error occurred. If nowait I/O is being used, IPCCHECK must be called to detect a fatal error reported for the specified VC descriptor after IOWAIT has been called and the receive completes.

Unless the intrinsic is called in nowait mode, the process is blocked until some data arrive or a timeout occurs. In nowait mode, the addresses of the data, flags and output opt options parameters are retained by NetIPC until needed. The input value of flags is retained and updated (with the "more data" flag off or on) when IOWAIT completes. The data parameter will then contain the data received. Only one nowait receive may be outstanding on a single connection.

The returned dlen parameter (or the IOWAIT tcount parameter in the case of a nowait request) shows how many bytes of data were actually received in the data parameter. This amount may be different from what you requested. If you did not receive all the data you want, you can obtain the additional data in a subsequent IPCRECV call. For more information, see the discussion of "Sending and Receiving Data Over a Connection" in Chapter 1 “NetIPC Fundamentals” and the programmatic examples in Chapter 4 “NetIPC Examples”

Condition codes returned by this intrinsic are:

CCE — Succeeded.
CCL — Failed.
CCG — Not returned by this intrinsic.

This intrinsic can be called in split stack mode.

Protocol-Specific Considerations

The following Table 3-7 “IPCRECV Protocol Specific Parameters” outlines parameters that are specific to the particular protocol you are accessing.

Table 3-7 IPCRECV Protocol Specific Parameters

Parameters		TCP	X.25
flags
	16	No output flag	n/a
	25	n/a	Discarded
	26	More data	More data
opt
	5	n/a	CUD field
	144	n/a	Bit 18: state of D bit in X.25 packets
			Bit 19: state of Q bit in X.25 packets
			Bit 27: urgent data
	145	n/a	Facility field

X.25 Considerations

In receiving a response to a connection request, the option field returns the facility field and the call user data (CUD) field. With fast select, up to 128 bytes of call user data may be returned in the call user data receive buffer (opt 5).

A single IPCRECV call returns data for one message only. If the "more data" flag is set, the complete message has not been received. The remaining part of the message can be received by subsequent calls to IPCRECV, unless the destroy flag (29) is set.

If the destroy flag is set, the remaining part of the message is destroyed. The end of message is indicated by the "more data" flag not being set.

If an interrupt packet is received in the middle of a data packet stream, IPCRECV returns no data. The result parameter indicates that an interrupt event has occurred. The interrupt user data field can be retrieved by calling IPCCONTROL, request 12 (reason for error or event). The next call to IPCRECV returns the whole data message.

If a reset packet is received in the middle of a data packet stream, all previously received packets are discarded. IPCRECV returns no data. The result parameter indicates a reset has occurred. Use the IPCCONTROL request 12 (reason for error or event) to retrieve the cause and diagnostic fields for the reset.

Common errors returned by IPCRECV in result are:

SOCKERR   0  Request complete successfully.
SOCKERR  59  Socket timeout.
SOCKERR  65  Connection aborted by local protocol module.
SOCKERR  67  Connection failure detected.
SOCKERR 107  Transport is going down.
SOCKERR 117  Attempt to establish connection failed.
SOCKERR 146  Reset event occurred on X.25 connection.
SOCKERR 156  Interrupt event occurred on X.25
             connection.
SOCKERR 158  Connection request rejected by remote.

A complete table of SOCKERRs is include in Appendix C “Error Messages”

TCP

The urgent data bit indicates that urgent data has been received. Table 3-8 “TCP Urgent and More Data Bit Combinations” demonstrates the meaning of urgent data and more data. Use these bits in combination to determine the status of data received.

Table 3-8 TCP Urgent and More Data Bit Combinations

Urgent	More Data	Meaning
0	0	Should never happen. (The receipt of normal data in stream mode causes more data to be set.)
0	1	Normal receive, no urgent data.
1	0	Urgent data received, no more urgent data.
1	1	Urgent data received and more is pending.

Cross-System Considerations for TCP

The following are cross-system programming considerations for this intrinsic:

HP 3000 to HP 1000:

Receive size (dlen parameter) — Range for the HP 3000 is 1 to 30,000 bytes. Range for the HP 1000 is 1 to 8,000 bytes. Although the ranges are different, cross-system communication is not affected. If you specify a send or receive size, be sure it is within the correct range for the respective system.

Data wait flag — The HP 1000 IPCRecv call supports a "DATA_WAIT" flag. This flag, when set, specifies that the call will not complete until the amount of data specified by the dlen parameter has been received. This flag is not available on the HP 3000, meaning that the call may complete before all the data is received. However, the HP 3000 IPCRECV supports other flags such as the "more data" and "destroy data" flags.

HP 3000 to HP 9000:

Receive size (dlen parameter) — Range for the HP 3000 is 1 to 30,000 bytes. Range for the HP 9000 is 1 to 32,767 bytes. Although the ranges are different, cross-system communication is not affected. If you specify a send or receive size, be sure it is within the correct range for the respective system.

Data wait flag — The HP 9000 IPCRECV call supports a "DATA_WAIT" flag. This flag, when set, specifies that the call will not complete until the amount of data specified by the dlen parameter has been received. This flag is not available on the HP 3000, meaning that the call may complete before all the data is received. However, the HP 3000 IPCRECV supports other flags such as the "more data" and "destroy data" flags.

HP 3000 to PC NetIPC:

Receive size (dlen parameter) — Range for the HP 3000 is 1 to 30,000 bytes. The PC send and receive size range is 1 to 65,535 bytes. Although the ranges are different, cross-system communication is not affected. If you specify a send or receive size, be sure it is within the correct range for the respective system.

On the PC, you can specify the maximum receive size of the data buffer through the got array in the IPCCONNECT call. This determines what the maximum value the dlen parameter can be for any IPCRECV call. PC NetIPC has no option array defined in IPCCONNECT. This does not affect cross-system communication. The maximum receive size of the data in the buffer on the HP 3000 will determine the receive size buffer on the PC.