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.
Authorization: | Supervisor state or problem state, any PSW key. |
Dispatchable unit mode: | Task. |
Cross memory mode: | PASN = HASN. |
Amode: | 31-bit or 24-bit. Note: See "Addressability
mode (Amode) considerations" under CALL instruction API environmental restrictions and programming requirements.
|
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)----'
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.
See Socket call error return codes for information about ERRNO return codes.
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.