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 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, RECVFROM returns the source address associated with each incoming datagram. For connection-oriented protocols like TCP, GETPEERNAME returns the address associated with the other end of the connection.
If NAME is nonzero, the call returns the address of the sender. The NBYTE parameter should be set to the size of the buffer.
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 will be 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.
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 RECVFROM call instructions.
WORKING-STORAGE SECTION.
01 SOC-FUNCTION PIC X(16) VALUE IS 'RECVFROM'.
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).
* 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 FLOWINFO PIC 9(8) BINARY.
03 IP-ADDRESS.
10 FILLER PIC 9(16) BINARY.
10 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.