accept_and_recv (BPX1ANR, BPX4ANR) — Accept a connection and receive the first block of data

Function

The accept_and_recv callable service accepts the next connection on a socket and receives the first block of data. The new socket's descriptor, the peer's remote address, and the caller's local address are also returned. The service does not return until some data has arrived.

Requirements

Parameters

Socket_desc

Supplied parameter

Type:

Integer

Length:

Fullword

The name of a fullword that contains the socket descriptor for which the accept_and_recv() is to be done. This is the server's "listen socket."

Accepted_socket

Supplied and returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword that contains one of the following on input:

• -1, indicating that the system is to assign a new descriptor to the accepted connection. The new descriptor is returned in this parameter. Note that a valid accepted socket descriptor is returned for partial success cases.
• If supported by the system, the value of a reusable socket descriptor with which the accepted connection is to be associated. Socket descriptors are reused after they have been used on a send_file that specified SF_REUSE. Reusable socket descriptors are created initially through an accept or an accept_and_recv. (See send_file (BPX1SF, BPX4SF) — Send a file on a socket.)

Remote_addr_len

Supplied and returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword (doubleword) that contains the length of Remote_addr. This field is updated with the length of the socket address that is returned in Remote_addr. If you do not want the Remote_addr, specify 0 for Remote_addr_len.

Remote_addr

Supplied and returned parameter

Type:

Structure

Length:

Remote_addr_len

The name of an area that contains the sockaddr structure that is returned for the client that is connecting.

Local_addr_len

Supplied and returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword (doubleword) that contains the length of Local_addr. This field is updated with the length of the socket address that is returned in Local_addr. If you do not want the Local_addr, specify 0 for Local_addr_len.

Local_addr

Supplied and returned parameter

Type:

Structure

Length:

Local_addr_len

The name of an area that contains the sockaddr structure that is returned for the server's port on which the connection arrives.

Buffer_len

Supplied parameter

Type:

Integer

Length:

Fullword

The name of a fullword that contains the length of Buffer. If this value is zero, no receive is done, and the accept_and_recv request completes when a connection is available.

Buffer

Returned parameter

Type:

Area

Length:

Buffer_len

The name of an area that contains the received data.

Buffer_alet

Supplied parameter

Type:

Integer

Length:

Fullword

The name of a field that contains the alet of the buffer. For buffers in the caller's primary address space, this value should be 0.

Return_value

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the accept_and_recv service returns one of the following:

• The number of bytes (zero or greater) that are received into the buffer, if the request is successful. Zero bytes can occur if the client closed the socket without sending any data, if a value of zero was specified for Buffer_len, or if no data was received within the active timeout interval. See Usage notes for more information.
• -1 with a Return_code of EINTRNODATA, if the request was interrupted by a signal in the time between the arrival of the connection and the arrival of the first data. The connection is established, and Accepted_socket returns the new socket descriptor.
• -1 with a Return_Code of EWOULDBLOCK, if the request was interrupted because the SO_RCVTIMEO value expired before data was received. The connection is established, and Accepted_socket returns the new socket descriptor.
• -1 with any other Return_Code, if the request is not successful.

Return_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the accept_and_recv service stores the return code. The accept_and_recv service returns Return_code only if Return_value is -1. For a complete list of possible return code values, see z/OS UNIX System Services Messages and Codes. The accept_and_recv service can return one of the following values in the Return_code parameter:

Return_code	Explanation
EBADF	A file descriptor that was not valid was supplied. The following reason codes can accompany the return code: JRFileDesNotInUse, JRFileNotOpen.
ECONNRESET	The connection was reset by a peer. The following reason code can accompany the return code: JRSockNotCon.
ECONNABORTED	The connection has been dropped.
EFAULT	An address that was passed cannot be accessed in the key of the caller.
EINTR	A signal interrupted the accept_and_recv service before a connection had arrived. The following reason code can accompany the return code: JRSignalReceived.
EINTRNODATA	A signal interrupted the accept_and_recv service after a connection had been established but before any data had arrived. This is a partial success, and the session has been established. A new socket descriptor is returned in Accepted_socket.
EIO	An I/O error occurred on one of the descriptors.
EINVAL	The socket is not accepting connections.
EISCONN	Accepted_socket is either bound or already connected.
EMFILE	OPEN_MAX descriptors are currently open in the calling process.
ENOBUFS	The service could not obtain a buffer. The following reason code can accompany the return code: JROutofSocketCells.
ENOMEM	The service could not obtain memory to complete the operation.
ENOREUSE	Socket descriptor reuse is not supported.
ENOSR	Insufficient STREAMS resources were available for the operation to complete.
ENOTSOCK	Socket_desc does not refer to a valid socket descriptor.The following reason code can accompany the return code: JRMustBeSocket.
EOPNOTSUPP	The socket type of the specified socket does not accept connections; or O_NONBLOCK is set for this socket. Nonblocking mode is not supported for this function.
EWOULDBLOCK	A new connection has been established, but the SO_RCVTIMEO timeout value was reached before data was available. This is a partial success, and the session has been established. A new socket descriptor is returned in Accepted_socket.

Reason_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the accept_and_recv service stores the reason code. The accept_and_recv service returns Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value. See z/OS UNIX System Services Messages and Codes for the reason codes.

Usage notes

1. Nonblocking mode is not supported for this function. If O_NONBLOCK is set on the Socket_desc parameter, the function fails with an EOPNOTSUPP error.
2. If accept (BPX1ACP, BPX4ACP) and accept_and_recv (BPX1ANR, BPX4ANR) calls are both used on the same socket, it cannot be predicted which calls will be satisfied and in which order. Note also that a mixture of accept and accept_and_recv is discouraged as it may result in a reduced performance benefit that is achieved using accept_and_recv exclusively.
3. SO_SNDTIMEOUT and SO_RCVTIMEOUT values are propagated from the server to the new, accepted connections.
4. If SO_RCVTIMEOUT is specified on the server socket, the timeout for new connections is started when the connection is first established, rather than when the BPX1ANR service is issued. When the RCV_TIMEOUT occurs the service completes with a Return_code of -1 and Reason_Code of EWOULDBLOCK. A new or reused socket descriptor is returned in Accepted_Socket.
5. If SO_RCVTIMEOUT is not specified on the server socket, an internal timer is started when the new connection is first established. If data from the client is not received within the internal timeout interval, the BPX1ANR completes successfully with a Return_Value of zero. A new or reused socket descriptor is returned in Accepted_Socket.
6. The accept_and_recv function is designed to work with the send_file function to provide an efficient file transfer capability for a connection-oriented server with short connection times and high connection rates.
7. See Callable services available to SRB mode routines for more information about programming considerations for SRB mode.

Related services

• accept (BPX1ACP, BPX4ACP) — Accept a connection request from a client socket
• recv (BPX1RCV, BPX4RCV) — Receive data on a socket and store it in a buffer

Characteristics and restrictions

None.