The READ macro reads data on a socket and stores it in
a buffer. The READ macro applies only to connected sockets.
For datagram sockets, the READ call returns the entire
datagram that was sent. If a datagram packet is too long to fit in
the supplied buffer, datagram sockets discard extra bytes.
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=READ--,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-+ +-,ECB--=--+-address--+-----+
'-(reg)----' | +-*indaddr-+ |
| '-(reg)----' |
'-,REQAREA--=--+-address--+-'
+-*indaddr-+
'-(reg)----'
>--+-------------------------+--+------------------------+-----><
'-,ERROR--=--+-address--+-' '-,TASK--=--+-address--+-'
+-*indaddr-+ +-*indaddr-+
'-(reg)----' '-(reg)----'
- Keyword
- Description
- S
- Input parameter. A value or the address of a halfword binary number
specifying the socket that is going to read the data.
- NBYTE
- Input parameter. A fullword binary number set to the size of BUF. READ does not return 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 or 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, ERRNO contains a valid error
number. Otherwise, ignore the ERRNO field.
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.
- ECB or REQAREA
- Input parameter. This parameter is required if you are
using APITYPE=3. It points to a 104-byte field containing the following
information:
- 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.
READ returns up to the number of bytes specified by NBYTE. If less than the number of bytes requested is
available, the READ macro returns the number currently available.
If data is not available for the socket and the socket
is in blocking mode, the READ macro blocks the caller until data arrives.
If data is not available and the socket is in nonblocking mode, READ
returns a -1 and sets ERRNO to 35 (EWOULDBLOCK). See IOCTL or FCNTL for a description of how to set the nonblocking mode.