send (BPX1SND, BPX4SND) — Send data on a socket
Function
The send callable service sends data on a socket.
Requirements
Operation | Environment |
---|---|
Authorization: | Supervisor state or problem state, any PSW key |
Dispatchable unit mode: | Task or SRB |
Cross memory mode: | PASN = HASN |
AMODE (BPX1SND): | 31-bit task or SRB mode |
AMODE (BPX4SND): | 64-bit task mode only |
ASC mode: | Primary mode |
Interrupt status: | Enabled for interrupts |
Locks: | Unlocked |
Control parameters: | All parameters must be addressable by the caller and in the primary address space. |
Format
|
AMODE 64 callers use BPX4SND with the same parameters.
Parameters
- Socket_descriptor
- Supplied parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword that contains the socket file descriptor for which the send is to be done.
- Buffer_length
- Supplied and returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a field that contains the length of Buffer.
- Buffer
- Supplied parameter
- Type:
- Character
- Length:
- Length specified by Buffer_length
The name of a field that contains the data that is to be transmitted.
- Buffer_alet
- Supplied parameter
- Type:
- Integer
- Length:
- Fullword
The name of a field that contains the ALET for Buffer.
You should specify a Buffer_alet of 0 for the normal case of a buffer in the user's address space (current primary address space). If a value other than 0 is specified for the Buffer_alet, the value must represent a valid entry in the dispatchable unit access list (DUAL).
- Flags
- Supplied parameter
- Type:
- Structure
- Length:
- Fullword
The name of a field that contains information about how the data is to be sent. See BPXYMSGF — Map the message flags for more information about the format of this field.
- Return_value
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which the send service returns one of the following:- The number of bytes sent from the buffer, if the request is successful. A value of 0 indicates that the connection is closed.
- -1, if the request is not successful.
- Return_code
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which the send service stores the return code. The send 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 send service can return one of the following values in the Return_code parameter:Return_code Explanation EBADF Socket_descriptor does not refer to a valid descriptor. The following reason codes can accompany the return code: JRFileDesNotInUse, JRFileNotOpen. ECONNRESET Connection reset by peer. EINTR A signal interrupted the send before any data was written. The following reason code can accompany the return code: JRSockRdwrSignal. EIO There has been a network or transport failure. The following reason code can accompany the return code: JRPrevSockError. 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. ENOBUFS A buffer could not be obtained. The following reason code can accompany the return code: JROutofSocketCells. ENOTCONN The socket is 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 to a socket that is shut down or closed. The following reason code can accompany the return code: JRSocketClosed. This error also generates a SIGPIPE signal. EWOULDBLOCK - The socket is marked nonblocking and no space is available for data to be written, or the SO_SNDTIMEO timeout value was reached before space became available.
- The socket is marked blocking. The call is blocked, without sending any data, for that time period which was specified in the SO_SNDTIMEO option.
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 send service stores the reason code. The send 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
- The socket must be connected.
- If there is not enough room to write the data to the output buffer, the service either blocks waiting for room, or returns an EWOULDBLOCK (depending on whether the socket is marked as blocking or nonblocking, and whether SO_SNDTIMEO timeout value was reached before space became available).
- See Callable services available to SRB mode routines for more information about programming considerations for SRB mode.
Characteristics and restrictions
There are no restrictions on the use of the send service.
Examples
For an example using this callable service, see BPX1SND (send) example.