The send_file callable service sends a file, with optional header and trailer data, as a byte stream on a socket connection. The service also provides options to close the socket connection after the data has been sent, and to prepare the socket for reuse after it has been closed.
Operation | Environment |
---|---|
Authorization: | Supervisor state or problem state, any PSW key |
Dispatchable unit mode: | Task |
Cross memory mode: | PASN = HASN |
AMODE (BPX1SF): | 31-bit |
AMODE (BPX4SF): | 64-bit |
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. |
|
AMODE 64 callers use BPX4SF with the same parameters. All addresses in the Sfpl structure are doublewords.
The name of a fullword that contains the length of the Sfpl structure that is being passed in the Sfpl parameter. To determine the value of Sfpl_length, use the BPXYSFPL macro(BPXYSFPL — Map the send_file parameter list).
The name of the Sfpl structure that is to be used to control this I/O operation. See the usage notes for details on setting the fields of this structure.
The Sfpl is mapped by the BPXYSFPL macro (BPXYSFPL — Map the send_file parameter list).
The name of a fullword in which the send_file service stores the return code. The send_file 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 send_file service can return one of the following values in the Return_code parameter:
Return_code | Explanation |
---|---|
EAGAIN | A descriptor is marked nonblocking, and no data could be sent without blocking. |
EBADF | A descriptor that was not valid was supplied; the file was not open for reading; or the socket was not open for writing. Consult Reason_code to determine the exact reason the error occurred. The following reason codes can accompany the return code: JRFileDesNotInUse, JRFileNotOpen, JRRFileWrOnly, JRWFileRdOnly. |
ECONNRESET | The connection was reset by a peer.Consult Reason_code to determine the exact reason the error occurred. The following reason code can accompany the return code: JRSockNotCon. |
ECONNABORTED | A connection has been dropped. |
EFAULT | An address that was passed could not be referenced in the key of the caller. |
EIO | An I/O error occurred. |
ENOBUFS | The service was unable to obtain a buffer. Consult Reason_code to determine the exact reason the error occurred. The following reason code can accompany the return code: JROutofSocketCells. |
ENOMEM | The service was unable to obtain memory to complete the operation. |
EINTR | A signal interrupted the send_file service before any data was written. Consult Reason_code to determine the exact reason the error occurred. The following reason code can accompany the return code: JRSockRdwrSignal. |
EINVAL | Data that was not valid was sent to the request. Consult Reason_code to determine the exact reason the error occurred. The following reason code can accompany the return code: JRSocketCallParmError. |
ENOTCONN | The socket was not connected. Consult Reason_code to determine the exact reason the error occurred. The following reason code can accompany the return code: JRSocketNotCon. |
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. Consult Reason_code to determine the exact reason the error occurred. The following reason code can accompany the return code: JRSocketClosed. |
EWOULDBLOCK | A descriptor is marked nonblocking and no data could be sent, or the SO_SNDTIMEO timeout value was reached before space became available. |
The name of a fullword in which the send_file service stores the reason code. The send_file 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.
If this field is -1, the entire file, from File_offset, is sent. The system updates the field with the number of file bytes that were sent (File_size-File_offset).
If this field is 0, no file data is sent, and File_desc is ignored.
If File_desc is not a regular file, it may be necessary to supply a specific value for File_bytes, unless a normal "end of file" indication is expected from File_desc during this operation, or you simply want the operation to run forever, transferring bytes as they arrive.
This option is intended for sockets, and for the subsequent use of the descriptor on an accept_and_recv() call. To reuse the socket descriptor, the Socket_desc value, as updated by the system in the Sfpl after the call to send_file(), is specified as the Accepted_socket parameter on the accept_and_recv() call.
Between the send_file() and the accept_and_recv() calls, a reused socket may only be used on accept_and_recv() or close(). The socket descriptor should be closed if it is not to be used again.
If reuse is not supported, the system closes Socket_desc, and replaces its value in the Sfpl with -1. This ensures that the output value of Socket_desc is always appropriate as an input value for the Accepted_socket parameter of an accept_and_recv() call.
The send_file service is designed to work with the accept_and_recv service to provide an efficient file transfer capability for a connection-oriented server with short connection times and high connection rates.
These functions are designed for a server process/thread model that is different from the traditional one in which a parent thread accepts connections in a loop and spins off child processes or threads to issue the receive and do work. In this new server model, the parent is eliminated. Multiple worker processes or threads are initially created, and each worker process or thread independently executes the accept_and_recv() and send_file() functions in a loop.
The performance benefits of accept_and_recv() and send_file() over the separate operations that they combine include fewer buffer copies, recycled sockets, and optimal thread scheduling.
In cases in which the socket does not support reuse, the system sets Socket_desc to -1 after the send_file(), so that the value is suitable for the next accept_and_recv() call.
None.
For an example using this callable service, see BPX1SF (send_file) example.