send_file (BPX1SF, BPX4SF) — Send a file on a socket

Function

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 is sent, and to prepare the socket for reuse after it is closed.

Requirements

Parameters

Sfpl_length

Supplied parameter

Type:

Integer

Length:

Fullword

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).

Sfpl

Supplied and returned parameter

Type:

Structure

Length:

Specified by the Sfpl_length parameter

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).

Return_value

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the send_file service returns the following return codes:

• 0, if the request is successful.
• -1, if the request is not successful.
• 1, if the request was interrupted by a signal, or if a nonblocking descriptor would have blocked while sending the data. The Sfpl structure is updated by the system to account for the data that was sent. You can continue the operation from the point at which it was interrupted by reissuing the send_file request with the same Sfpl structure.

Return_code

Returned parameter

Type:

Integer

Length:

Fullword

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 that the error occurred. The following reason code can accompany the return code: JRSockNotCon.
ECONNABORTED	A connection was 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 that 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 that 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 that 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 that 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.

Reason_code

Returned parameter

Type:

Integer

Length:

Fullword

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.

Usage notes

1. Sfpl Structure (send_file parameter list)
   The send_file operation is controlled by the values that are set into this structure. Refer to the BPXYSFPL macro for the exact field names (BPXYSFPL — Map the send_file parameter list).

   Note:

   1. The entire Sfpl structure should be zeroed out before its first use, to ensure that undefined options, reserved space, and fields that might be used are initialized properly.
   2. All doubleword fields are treated as signed 63–bit arithmetic values. For operations that are known to be under 4 gigabytes in size, you can refer to the lower words of these fields (named in the BPXYSFPL macro) as unsigned 32–bit arithmetic values.

   Field

   Description

   Socket_desc

   The descriptor on which to send the data.

   File_desc

   The descriptor from which to read the data that is sent.

   File_offset

   A doubleword field that contains the byte offset in the file from which to start sending.

   File_bytes

   A doubleword field that contains the number of bytes to be sent, starting from the File_offset.

   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.

   File_size

   A doubleword field that is updated by the system after the operation with the file's size.

   Header_len

   The length of the header data.

   Header_ptr

   The address of the header data that is to be sent in front of the file data.

   Header_alet

   The ALET of the header data.

   Trailer_len

   The length of the trailer data.

   Trailer_ptr

   The address of the trailer data that is to be sent after the file data.

   Trailer_alet

   The ALET of the trailer data.

   Bytes_sent

   A doubleword field that is filled in by the system with the total number of bytes that are sent on this call. If the file must be sent with multiple calls because of signal interruptions, this field contains the value for the last call only; it is not a running total.

   Options

   A field that contains the following bit flags, which have the specified meaning when the bit is on:

   • SF_CLOSE — Close the Socket_desc after the data has been sent. If the operation completes successfully and Socket_desc is closed, the system updates Socket_desc in the Sfpl with -1.
   • SF_REUSE — Prepare the Socket_desc to be reused after the data has been successfully sent.

     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 SF_REUSE option is not supported.

2. The send_file() function attempts to send the header data, followed by the file data from File_desc, followed by the trailer data, over socket_desc.
3. As data is sent, the system updates the Sfpl structure to account for the data that has been sent. This facilitates continuation after a signal interruption, but it also means that the Sfpl must be almost completely reset to start another new operation.
4. If File_offset>File_size, or File_bytes>(File_size-File_offset), the operation fails with an EINVAL error.
5. The SF_CLOSE and SF_REUSE flags are only effective when the operation completes successfully.
6. The send_file service is not strictly limited to sending a file on a socket. Any two stream-oriented descriptors may be used, although some of the parameters may have to be interpreted differently. When File_desc is a pipe, for example, the File_size and Offset parameters are meaningless.
7. The file cursor for the File_desc that is specified is updated with the results of the send_file operation. This does not affect other send_file() calls, but it does affect later read() and write() operations that use this File_desc.
8. Application Usage

   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.

   Socket descriptors can be recycled in the following way:

   1. On the first call to accept_and_recv(), the application sets the Accepted_socket parameter to -1. This causes the system to assign a new descriptor to the accepted socket.
   2. On the following call to send_file(), the application requests SF_REUSE. The socket session is closed, but the socket descriptor remains available for reuse on the next accept_and_recv().
   3. All later calls to accept_and_recv() specify as their Accepted_socket the Socket_desc value that is left over from the previous call to send_file().

      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.

Related services

• accept_and_recv (BPX1ANR, BPX4ANR) — Accept a connection and receive the first block of data
• send (BPX1SND, BPX4SND) — Send data on a socket
• read (BPX1RED, BPX4RED) — Read from a file or socket

Characteristics and restrictions

None.