WRITE

Use the WRITE command to send an outgoing message on the connected socket. The WRITE command is similar to the SEND command, except that the WRITE command does not support the control flags that are available with the SEND command.

When the socket is a TCP socket, the following conditions apply:
  • If the socket is in blocking mode and the total amount of data to be sent cannot be processed by the stack when the command is issued, then the command blocks until the data can be sent.
  • If the socket is in nonblocking mode and the total amount of data to be written cannot be processed by the stack when the command is issued, then the command returns the number of bytes that were successfully written. If none of the data can be written, the command returns the value -1 and the 35 EWOULDBLOCK error code.
When the socket is a connected UDP socket, the WRITE command either is completed or fails. A connected UDP socket does not return the 35 EWOULDBLOCK error code.
Restriction: The WRITE command does not support send flags.
Guidelines: Place the WRITE command in a loop to ensure that all the data is written. For a TCP socket, a partial write operation might occur regardless of whether the socket is in blocking or nonblocking mode. A partial write operation occurs when the stack copies some but not all of the application data:
  • If a partial write operation occurs on a socket in blocking mode, the blocking socket is interrupted. The return value contains the number of bytes written, and the return code contains the reason for the interruption. In such cases, consider ending the connection.
  • If a partial write operation occurs on a socket in nonblocking mode, the return value indicates the number of bytes that were successfully sent. If this is less than the number of bytes specified on the WRITE command, repeat the WRITE operation until all data is written. The blocking condition might last for a long time, so consider other strategies to ensure that the application does not remain in a busy loop sending data.
Tips:
  • Use the SELECT command to determine whether a socket is ready to send additional data. To do so, test the socket for a WRITE event.
  • If the SO_ASCII socket option is enabled, then the data received is translated from EBCDIC to ASCII.

Format

Read syntax diagramSkip visual syntax diagramSOCKET("WRITE" ,socketid ,data )

Parameters

socketid
The socket descriptor
data
The string to be sent

Returned value

The command returns a string that contains the return code and the length of the data string, for example, 0 19. The return code can be 0, a REXX socket API error number, or the REXX TCP/IP error number that is set by the socket command. The return code 0 indicates that the requested socket command was completed successfully.

See Socket call error return codes for additional information about the numeric error codes that are returned by this command.

The following REXX TCP/IP error numbers can be returned:
  • 4 EINTR
  • 9 EBADF
  • 5 EIO
  • 22 EINVAL
  • 32 EPIPE
  • 35 EWOULDBLOCK
  • 38 ENOTSOCK
  • 40 EMSGSIZE
  • 45 EOPNOTSUPP
  • 54 ECONNRESET
  • 57 ENOTCONN
The following REXX socket API error numbers can be returned:
  • 2001 EINVALIDRXSOCKETCALL
  • 2005 ESUBTASKNOTACTIVE
  • 2009 ESOCKETNOTDEFINED

LE C/C++ equivalent

ssize_t send(int socket, const void *buffer, size_t length, int flags);

Code example

See the SEND command. Substitute the command WRITE for the command SEND.