The RECV macro receives data on a socket and stores it
in a buffer. The RECV macro applies only to connected sockets. RECV
can read the next message, but leaves the data in a buffer, and can
read out-of-band data. RECV gives you the option of setting flags
with the
FLAGS parameter.
Note: Out-of-band
data (called urgent data in TCP) appears to the application like a
separate stream of data from the main data stream.
RECV returns the length of the incoming message or data.
If a datagram packet is too long to fit in the supplied buffer, datagram
sockets discard extra bytes.
For stream sockets, the data is processed like streams
of information with no boundaries separating data. For example, if
applications A and B are connected with a stream socket and Application
A sends 1000 bytes, each call to RECV can return 1 byte, or 10 bytes,
or the entire 1000 bytes. Therefore, applications using stream sockets
should place RECV in a loop that repeats the call until all data has
been received.
The following requirements apply to this call:
Authorization: |
Supervisor state or problem state, any PSW key. |
Dispatchable unit mode: |
Task. |
Cross memory mode: |
PASN = HASN. |
Amode: |
31-bit or 24-bit.
|
ASC mode: |
Primary address space control (ASC) mode. |
Interrupt status: |
Enabled for interrupts. |
Locks: |
Unlocked. |
Control parameters: |
All parameters must be addressable by the caller
and in the primary address space. |
>>-EZASMI--TYPE=RECV--,S--=--+-number---+----------------------->
+-address--+
+-*indaddr-+
'-(reg)----'
>--,NBYTE--=--+-number---+--,BUF--=--+-address--+--------------->
+-address--+ +-*indaddr-+
+-*indaddr-+ '-(reg)----'
'-(reg)----'
>--+------------------------+--,ERRNO--=--+-address--+---------->
'-,ALET--=--+-address--+-' +-*indaddr-+
+-*indaddr-+ '-(reg)----'
'-(reg)----'
>--,RETCODE--=--+-address--+------------------------------------>
+-*indaddr-+
'-(reg)----'
>--+------------------------------+----------------------------->
'-,FLAGS--=--+-'MSG_OOB'-----+-'
+-'MSG_PEEK'----+
+-'MSG_WAITALL'-+
+-address-------+
+-*indaddr------+
'-(reg)---------'
>--+---------------------------+--+-------------------------+--->
+-,ECB--=--+-address--+-----+ '-,ERROR--=--+-address--+-'
| +-*indaddr-+ | +-*indaddr-+
| '-(reg)----' | '-(reg)----'
'-,REQAREA--=--+-address--+-'
+-*indaddr-+
'-(reg)----'
>--+------------------------+----------------------------------><
'-,TASK--=--+-address--+-'
+-*indaddr-+
'-(reg)----'
- Keyword
- Description
- S
- Input parameter. A value or the address
of a halfword binary number specifying the socket descriptor.
- NBYTE
- Input parameter. A fullword binary
number set to the size of BUF. RECV does
not receive more than the number of bytes of data in NBYTE even if more data is available.
- BUF
- On input, a buffer to be filled by completion
of the call. The length of BUF must be at
least as long as the value of NBYTE.
- ALET
- Optional input parameter. A fullword
binary field containing the ALET of BUF. The default is 0 (primary address space).
If a nonzero ALET is specified, the ALET must represent a valid entry in the dispatchable unit access list
(DU-AL) for the task issuing this call. Note that ALETs can be specified only for synchronous socket calls (for example,
ECB/REQAREA cannot be specified). An exception to this is an ALET representing a SCOPE=COMMON data space.
- ERRNO
- Output parameter. A fullword binary
field. If RETCODE is negative, this field
contains an error number. See Socket call error return codes for information about ERRNO return codes.
- RETCODE
- A fullword binary field that returns
one of the following values:
- Value
- Description
- 0
- A 0 return code indicates that the connection is closed and no
data is available.
- >0
- A positive value indicates the number of bytes copied into the
buffer.
- -1
- Check ERRNO for an error code.
- FLAGS
- Input parameter. FLAGS can be a literal value or a fullword binary field.
Literal Value |
Binary Value |
Description |
---|
'MSG_OOB' |
X'00000001' |
Receive out-of-band data (stream
sockets only). Out-of-band data can be read if the SO_OOBINLINE option
is set for the socket regardless of whether the MSG_OOB flag is set. |
'MSG_PEEK' |
X'00000002' |
Peek at the data, but do not destroy
the data. If the peek flag is set, the next receive operation reads
the same data. |
'MSG_WAITALL' |
X'00000040' |
Requests that the function block until the full
amount of requested data can be returned (stream sockets only). The
function might return a smaller amount of data if the connection is
terminated, if an error is pending, or if the SO_RCVTIMEO field is
set and the timer expired for the socket. |
- ECB or REQAREA
- Input parameter. This parameter is required if you are
using APITYPE=3. It points to a 104-byte field containing:
- For ECB
- A 4-byte ECB posted by TCP/IP when the
macro completes.
- For REQAREA
- A 4-byte user token (set by you) that is presented to your exit
when the response to this function request is complete.
- For ECB/REQAREA
- The last 100 bytes is a storage field used by the interface to
save the state information.
Note: This storage must not be modified until the
macro function has completed and the ECB has been posted, or the asynchronous exit has been driven.
- ERROR
- Input parameter. The location in your program to receive
control when the application programming interface (API) processing
module cannot be loaded.
- TASK
- Input parameter. The location of the task storage area in your
program.
If data is not available for the socket and the socket
is in blocking mode, the RECV macro blocks the caller until data arrives.
If data is not available and the socket is in nonblocking mode, RECV
returns a -1 and sets ERRNO to 35 (EWOULDBLOCK). See FCNTL or IOCTL for a description of how to set nonblocking mode.