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