The RECVFROM macro receives data for a socket and stores
it in a buffer. RECVFROM returns the length of the incoming message
or data stream.
If data is not available for the socket designated by
descriptor S, and socket S is in blocking mode, the RECVFROM call
blocks the caller until data arrives.
If data is not available and socket S is in nonblocking
mode, RECVFROM returns a -1 and sets ERRNO to 35 (EWOULDBLOCK). Because RECVFROM returns the socket address
in the NAME structure, it applies to any
datagram socket, whether connected or unconnected. See FCNTL or IOCTL for a description of how to set nonblocking mode. If a datagram
packet is too long to fit in the supplied buffer, datagram sockets
discard extra bytes.
For stream sockets, the data is processed as streams of
information with no boundaries separating data. For example, if applications
A and B are connected with a stream socket and Application A sends
1000 bytes, each call to this function can return 1 byte, or 10 bytes,
or the entire 1000 bytes. Applications using stream sockets should
place RECVFROM in a loop that repeats until all of the data has been
received.
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=RECVFROM--,S--=--+-number---+------------------->
+-address--+
+-*indaddr-+
'-(reg)----'
>--,NBYTE--=--+-number---+--,BUF--=--+-address--+--------------->
+-address--+ +-*indaddr-+
+-*indaddr-+ '-(reg)----'
'-(reg)----'
>--,NAME--=--+-address--+--+------------------------+----------->
+-*indaddr-+ '-,ALET--=--+-address--+-'
'-(reg)----' +-*indaddr-+
'-(reg)----'
>--,ERRNO--=--+-address--+--,RETCODE--=--+-address--+----------->
+-*indaddr-+ +-*indaddr-+
'-(reg)----' '-(reg)----'
>--+------------------------------+----------------------------->
'-,FLAGS--=--+-'MSG_OOB'-----+-'
+-'MSG_PEEK'----+
+-'MSG_WAITALL'-+
+-address-------+
+-*indaddr------+
'-(reg)---------'
>--+---------------------------+--+-------------------------+--->
+-,ECB--=--+-address--+-----+ '-,ERROR--=--+-address--+-'
| +-*indaddr-+ | +-*indaddr-+
| '-(reg)----' | '-(reg)----'
'-,REQAREA--=--+-address--+-'
+-*indaddr-+
'-(reg)----'
>--+------------------------+----------------------------------><
'-,TASK--=--+-address--+-'
+-*indaddr-+
'-(reg)----'
- Keyword
- Description
- S
- Input parameter. A value or the
address of a halfword binary number specifying the socket to receive
the data.
- NBYTE
- Input parameter. A value or the
address of a fullword binary number specifying the length of the input
buffer. NBYTE must first be initialized
to the size of the buffer associated with NAME. On return the NBYTE contains the number
of bytes of data received.
- 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.
- NAME
-
Initially, the IPv4 or IPv6 application provides
a pointer to a structure that will contain the peer socket name on
completion of the call. If the NAME parameter
value is nonzero, the IPv4 or IPv6 source address of the message is specified with the address of who sent the datagram.
Include the SYS1.MACLIB(BPXYSOCK) macro to get the assembler mappings
for the socket address structure. The socket address structure mappings
begin at the SOCKADDR label. The AF_INET socket address structure
fields start at the SOCK_SIN label. The AF_INET6 socket address structure
fields start at the SOCK_SIN6 label.
The IPv4 socket address
structure contains the following fields:
- Field
- Description
- FAMILY
- Output parameter. A halfword binary number specifying the IPv4
addressing family. The value for the IPv4 socket descriptor (S parameter)
is a decimal 2, indicating AF_INET.
- PORT
- Output parameter. A halfword binary number specifying the port
number of the sending socket.
- IPv4-ADDRESS
- Output parameter. A fullword binary number specifying the 32-bit
IPv4 Internet address of the sending socket.
- RESERVED
- Output parameter. An 8-byte reserved field. This field is required,
but is not used.
The IPv6 socket structure contains the following
fields:
- Field
- Description
- NAMELEN
- Output parameter. A 1-byte binary field specifying the length
of this IPv6 socket address structure. Any value specified by the
use of this field is ignored when processed as input and the field
is set to 0 when processed as output.
- FAMILY
- Output parameter. A 1-byte binary field specifying the IPv6 addressing
family. The value for IPv6 socket descriptor (S parameter) is a decimal
19, indicating AF_INET6.
- PORT
- Output parameter. A halfword binary number specifying the port
number of the sending socket.
- FLOW-INFO
- Output parameter. A fullword binary field specifying the traffic
class and flow label. This value of this field is undefined.
- IPv6-ADDRESS
- Output parameter. A 16-byte binary field that is set to the 128-bit
IPv6 Internet address, in network byte order, of the sending socket.
- SCOPE-ID
- A fullword binary field which identifies a set of interfaces as
appropriate for the scope of the address carried in the IPv6-ADDRESS field. For a link scope IPv6-ADDRESS, SCOPE-ID contains the link index
for the IPv6-ADDRESS. For all other address
scopes, SCOPE-ID is undefined.
- ALET
- Optional input parameter. A fullword
binary field containing the ALET of 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 only be specified 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, this field
contains an error number. 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 transferred by
the RECVFROM call.
- -1
- Check ERRNO for an error code.
- FLAGS
- Input parameter. FLAGS can be a literal value or a fullword binary field.
Literal Value |
Binary Value |
Description |
---|
'MSG_OOB' |
X'00000001' |
Receive out-of-band data (stream
sockets only). Out-of-band data can be read if the SO_OOBINLINE option
is set for the socket regardless of whether the MSG_OOB flag is set. |
'MSG_PEEK' |
X'00000002' |
Peek at the data, but do not destroy
the data. If the peek flag is set, the next receive operation reads
the same data. |
'MSG_WAITALL' |
X'00000040' |
Requests that the function block until the full
amount of requested data can be returned (stream sockets only). The
function might return a smaller amount of data if the connection is
terminated, if an error is pending, or if the SO_RCVTIMEO field is
set and the timer expired for the socket. |
- ECB or REQAREA
- Input parameter. This parameter is required if you are
using APITYPE=3. It points to a 104-byte field containing:
- 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.