srx_np (BPX1SRX, BPX4SRX) — Send or receive CSM buffers on a socket

Function

The srx_np callable service sends or receives data on a socket using CSM (Communications Storage Manager) buffers.

Requirements

Parameters

Socket_descriptor

Supplied parameter

Type:

Integer

Length:

Fullword

The name of a fullword that contains the socket file descriptor for which the srx_np service is requested.

Direction

Supplied parameter

Type:

Integer

Length:

Fullword

The name of a fullword that contains a value that indicates the operation requested:

• MSGX_SEND or 0, for a send operation
• MSGX_RECV or 1, for a receive operation

Msghdrx_length

Supplied parameter

Type:

Integer

Length:

Fullword

The name of a field that contains the length of the Msghdrx parameter.

Before the data structures are built for the first time, you can use a value of 0 in this field to determine whether the operation is supported on a given socket. If the operation is supported, a Return_value of 0 is returned. If the operation is not supported, a Return_value of -1 with a Return_code of ENOSYS is returned.

Msghdrx

Supplied and returned parameter

Type:

Structure

Length:

Length of MSGX from BPXYMSGX

The name of the MSGX structure that contains the information for this operation. See the usage notes and the BPXYMSGX macro (BPXYMSGX — Map the message header) for more information about the MSGX structure.

Return_value

Returned parameter

Type:

Integer

Length:

Fullword

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

• The number of bytes that were sent or received from the buffers, if the request is successful.
• -1, if the request is not successful.

Return_code

Returned parameter

Type:

Integer

Length:

Fullword

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

Return_code	Explanation
ENOSYS	This function is not supported on the specified socket.
EAFNOSUPPORT	The address family that was specified in the message header is not the same as the address family that owns the socket.
EBADF	An incorrect file descriptor was specified. 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.
EINTR	A signal interrupted the srx_np service before any data was written. The following reason code can accompany the return code: JRSockRdwrSignal.
EINVAL	An input parameter was incorrect. The following reason codes can accompany the return code: JRInvalidMsgh, JRSocketCallParmError, and JRSockNoName.
EMSGSIZE	The message is too large to be sent all at once, as the socket requires. The following reason code can accompany the return code: JRSockBufMax.
EFAULT	An address that was passed pointed to storage that could not be accessed.
ENOTCONN	The socket was not connected. The following reason code can accompany the return code: JRSocketNotCon.
ENOTSOCK	Socket_descriptor does not refer to a valid socket descriptor. The following reason code can accompany the return code: JRMustBeSocket.
EPIPE	An attempt was made to send a message to a socket that is shut down or closed. This error also generates a SIGPIPE signal. The following reason code can accompany the return code: JRSocketClosed.
EWOULDBLOCK	For a receive operation, the socket is marked nonblocking and there is no data available to be read, or the SO_RCVTIMEO timeout value was reached before data was available. The following reason codes can accompany the return code: JRWouldBlock, JrTimeOut.

Reason_code

Returned parameter

Type:

Integer

Length:

Fullword

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

Usage notes

1. The Communications Storage Manager (CSM) provides a facility that allows programs to avoid data moves on a communications session by transferring buffer ownership instead of copying the buffer contents.

   The srx_np service provides a way to send these buffers on a socket session. It is assumed that the application has its own interactions with CSM that allow it to obtain and free these buffers independently from the srx_np service. CSM is restricted to authorized programs, and the buffers are in key 6 storage. The srx_np service, however, may be invoked from problem state or authorized programs. All parameters are in local application storage and the caller's key.

   For more information about CSM, see z/OS Communications Server: CSM Guide.

2. The general flow for using this service is as follows:
   When sending:

   1. The application obtains CSM buffers and fills them with the data to be sent. The collection of one or more CSM data buffers is described with an IOVX array that may be built in application storage or in another CSM buffer. This whole structure and operational characteristics are specified in a Msghdrx structure, which is passed to the srx_np callable service.
   2. The request is passed on to the transport, such as TCP/IP, for the specified socket. If the socket transport does not support CSM buffers, the call fails with ENOSYS. A specific socket can be tested for support before the buffers are built, by specifying 0 for Msghdrx_length. If CSM buffers are not supported, the data will have to be sent with standard services, such as send (BPX1SND, BPX4SND) or writev (BPX1WRV, BPX4WRV). CSM buffers could be used on the standard services, but they would be treated as application buffers, and the application would retain ownership and be responsible for freeing the buffers.
   3. The socket transport transfers ownership of the CSM data buffers, not the IOVX, to itself and passes them along to the communications adapter. Ownership of the IOVX buffer, if it is a CSM buffer, remains with the application.
   4. The communications adapter transfers buffer ownership to itself and transmits the data.
   5. When the I/O is complete, the adapter issues CSM deallocates for the buffers.
   6. CSM puts the buffers back into its global free pool.
   7. When control returns to the application after the srx_np call, it no longer owns the buffers and must not reference them again.
   When receiving:

   1. Inbound data is received into CSM buffers obtained by the communications adapter.
   2. These buffers are passed up to the socket transport, who assumes ownership.
   3. The application calls srx_np to receive. A Msghdrx structure is passed that may contain some control information, but that does not specify any buffers or an IOVX array.
   4. The socket transport builds an IOVX array to describe the inbound data buffers that have been accumulated. This array is itself in a CSM buffer.

      If data has not arrived yet, the request is suspended or failed with EWOULDBLOCK, as for any other socket receive type of operation.

      When data is to be returned to the application, the transport assigns ownership of the CSM buffers to the application, and the application's Msghdrx structure is filled in with a description of the IOVX array buffer.

   5. When control returns to the application after the srx_np call, it has ownership of the CSM buffers and may process the data that has been received.
   6. When the application has finished with the buffers and the IOVX array, it issues CSM deallocates for them.
   7. CSM puts the buffers back into its global free pool.
3. For a receive operation, Msghdrx contains the following fields:

   Field	Description
   MsgxNamePtr	A pointer to a sockaddr buffer in which the system returns the source address of the data that is received. This field is optional. If it is not used, MsgxNamePtr or MsgxnameLen should be zero.
   MsgxNameLen	The length of the sockaddr buffer that is pointed to by MsgxNamePtr.
   MsgxIovx	An IVTBUFL structure in which the system describes the CSM buffer containing the IOVX array being returned for this request. This CSM buffer is obtained by the system and freed by the calling application. The IOVX array contains IVTBUFL structures, each of which describes a CSM data buffer that contains the data received by this request. The CSM data buffers that are used by this service are obtained by the system and freed by the caller.
   MsgxMsgFlags	MSG_* flags for this operation. Refer to BPXYMSGF — Map the message flags.
   MsgxFlags	Control flags: MSGX_CECSA, indicating that the CSM buffers should be obtained from ECSA MSGX_CDSPACE, indicating that the CSM buffers should be obtained from one of the CSM data spaces If neither flag is specified, the application can handle CSM buffers in either ECSA or a data space.
   MsgxDataLen	The maximum or minimum amount of data that is to be received: When MSG_WAITALL is off, MsgxDataLen specifies the maximum amount of data that the caller wants to receive. When MSG_WAITALL is on, MsgxDataLen specifies the minimum amount of data that the caller wants to receive. You can use this value to control the amount of data that is received, in the same way that you use the Buffer_length parameter of the recv service. If this field is 0, the receive operation completes as soon as the first block of data is available, and whatever data is available is returned. If the receive operation cannot be completed immediately, the application blocks or receives an EWOULDBLOCK error, depending on its blocking state.
   MsgxTcb	The TCB address of a task with which the CSM storage is to be associated. By default the storage is associated with the calling task. This field is optional, and should be 0 if not specified.

4. For a send operation, Msghdrx contains the following fields:

   Field	Description
   MsgxNamePtr	A pointer to a sockaddr buffer that contains the destination address for the send operation. This field is optional. If it is not used, MsgxNamePtr or MsgxNameLen should be 0.
   MsgxNameLen	The length of the sockaddr buffer that is pointed to by MsgxNamePtr.
   MsgxIovx	An IVTBUFL structure that describes the buffer containing the IOVX array. This buffer may be a CSM buffer, or it may be in the caller's storage. Ownership of a CSM buffer used for the IOVX array remains with the application. The IOVX array contains IVTBUFL structures, each of which describes a CSM data buffer that contains the data to be sent. The CSM data buffers that are used by this service are obtained by the caller and freed by the system.
   MsgxMsgFlags	MSG_* flags for this operation. Refer to BPXYMSGF — Map the message flags.
   MsgxIVTBUFLOffset	The returned offset of the IOVX array entry for the first CSM data buffer that the application still owns. After a successful send, this value is equal to the length of the IOVX array. If this value is zero, no buffers were taken.
   MsgxErrIovx	The offset of the IOVX array entry that is in error. This field and MsgxErrData are returned only when there is an error that is specifically related to one of the IOVX entries or their associated buffers. Refer to the Return_code and Reason_code for details on the error.
   MsgxErrData	The amount of data that has been sent successfully from the buffer that is indicated by MsgxErrIovx.

   MsgxErrIovx and MsgxErrData should only be examined when the request completes with a Return_value of -1, or when the amount of data sent is less than the amount of data that was requested to be sent.

5. A C header, BPXYSRXH, is available which contains a C structure for the Msghdrx and a prototype for srx_np. With this header and the IVTBUFL C header, you can send and receive CSM buffers from C programs.

   Note, however, that this program would simply be making C calls to the srx_np callable service, and not making normal C functional references. In particular, the return value and errno value would be returned in explicit calling parameters, rather than in the standard C method.

6. The socket may be connected or unconnected.
7. Consult the documentation for the TCP/IP stack that is being used for support for this function.
8. Some common INET considerations:

   When the socket is associated to a specific transport, the requests are accepted or rejected based on that transport's support for CSM buffers. A socket becomes associated with a specific transport by being a connected stream socket, bound to a specific IP address, or through setibmopt(IBM_IMAGE) or ioctl(SIOCSETRTTD).

   When the application's socket is associated with more than one transport, every associated transport must support CSM buffers for a receive operation to be accepted. For a send operation, the transport chosen by the system for the destination IP address must support CSM buffers.

Usage notes

1. See Callable services available to SRB mode routines for more information about programming considerations for SRB mode.

Related services

recvmsg (BPX2RMS, BPX4RMS) — Receive messages on a socket and store them in message buffers

Characteristics and restrictions

There are no restrictions on the use of the srx_np service.