RECV

The RECV call, like READ, receives data on a socket with descriptor S. RECV applies only to connected sockets. If a datagram packet is too long to fit in the supplied buffers, datagram sockets discard extra bytes.

For additional control of the incoming data, RECV can:

Peek at the incoming message without having it removed from the buffer
Read out-of-band data

For stream sockets, data is processed as streams of information with no boundaries separating the data. For example, if programs A and B are connected with a stream socket and program A sends 1000 bytes, each call to this function can return any number of bytes, up to the entire 1000 bytes. The number of bytes returned will be contained in RETCODE. Therefore, programs using stream sockets should place RECV in a loop that repeats until all data has been received.

If data is not available for the socket, and the socket is in blocking mode, RECV 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.

For raw sockets, RECV adds a 20-byte header.

Note: See EZACIC05 for a subroutine that will translate ASCII input data to EBCDIC.

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.

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.

Figure 1 shows an example of RECV call instructions.

Figure 1. RECV call instruction example

    WORKING-STORAGE SECTION.
        01  SOC-FUNCTION    PIC X(16)  VALUE IS 'RECV'.
        01  S               PIC 9(4) BINARY.
        01  FLAGS           PIC 9(8) BINARY.
            88  NO-FLAG                VALUE IS 0.
            88  OOB                    VALUE IS 1.
            88  PEEK                   VALUE IS 2.
        01  NBYTE           PIC 9(8) BINARY.
        01  BUF             PIC X(length of buffer).
        01  ERRNO           PIC 9(8) BINARY.
        01  RETCODE         PIC S9(8) BINARY.
 
    PROCEDURE DIVISION.
         CALL 'EZASOKET' USING SOC-FUNCTION S FLAGS NBYTE BUF
                         ERRNO RETCODE.

For equivalent PL/I and assembler language declarations, see Converting parameter descriptions.