RECVFROM call

The RECVFROM call receives data on a socket with descriptor S and stores it in a buffer. The RECVFROM call applies to both connected and unconnected sockets. The IPv4 or IPv6 socket address is returned in the NAME structure. If a datagram packet is too long to fit in the supplied buffers, datagram sockets discard extra bytes.

For datagram protocols, the RECVFROM call returns the source address associated with each incoming datagram. For connection-oriented protocols like TCP, the GETPEERNAME call returns the address associated with the other end of the connection.

On return, NBYTE contains the number of data bytes received.

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 are contained in RETCODE. Therefore, programs using stream sockets should place RECVFROM in a loop that repeats until all data has been received.

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

If data is not available for the socket, and the socket is in blocking mode, RECVFROM blocks the caller until data arrives. If data is not available and the socket is in nonblocking mode, RECVFROM returns a -1 and sets ERRNO to 35 (EWOULDBLOCK). See FCNTL call or IOCTL call for a description of how to set nonblocking mode.

Note: See EZACIC05 program for a subroutine that translates ASCII input data to EBCDIC.

The following requirements apply to this call:

Requirement	Description
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

Figure 1 shows an example of RECVFROM call instructions.

Figure 1. RECVFROM call instruction example

    WORKING-STORAGE SECTION.
        01  SOC-FUNCTION    PIC X(16)  VALUE IS 'RECVFROM'.
        01  S               PIC 9(4) BINARY.
        01  FLAGS           PIC 9(8) BINARY.
        01  NO-FLAG         PIC 9(8) BINARY  VALUE IS 0.
        01  OOB             PIC 9(8) BINARY  VALUE IS 1.
        01  PEEK            PIC 9(8) BINARY  VALUE IS 2.
        01  NBYTE           PIC 9(8) BINARY.
        01  BUF             PIC X(length of buffer).
    *                                                                 
    * IPv4 Socket Address Structure.                                  
    *                                                                 
        01  NAME.
            03  FAMILY      PIC 9(4) BINARY.
            03  PORT        PIC 9(4) BINARY.
            03  IP-ADDRESS  PIC 9(8) BINARY.
            03  RESERVED    PIC X(8).
    *                                                                 
    * IPv6 Socket Address Structure.                                  
    *                                                                 
        01  NAME.                                                    
            03  FAMILY      PIC 9(4) BINARY.                         
            03  PORT        PIC 9(4) BINARY.                         
            03  FLOW-INFO   PIC 9(8) BINARY.                         
            03  IP-ADDRESS.                                          
                05  FILLER  PIC 9(16) BINARY.                        
                05  FILLER  PIC 9(16) BINARY.                        
            03  SCOPE-ID    PIC 9(8) BINARY.                         

        01  ERRNO           PIC 9(8) BINARY.
        01  RETCODE         PIC S9(8) BINARY.
 
    PROCEDURE DIVISION.
         CALL 'EZASOKET' USING SOC-FUNCTION S FLAGS
                         NBYTE BUF NAME ERRNO RETCODE.

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