HP 3000 Manuals HP 3000 Manuals
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 Programming 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
( flagsbit 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 acknowledgement (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, "Facility
Field").
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, and the programmatic examples in Chapter 4.
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 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.
TCP
The urgent data bit indicates that urgent data has been received. Table
3-9 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 IPCRecvcall 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 IPCRECVsupports
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 IPCRECVcall 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 IPCRECVsupports
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 IPCCONNECTcall. This determines what the
maximum value the dlen parameter can be for any IPCRECVcall. 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.