Verbs and Built-in Functions › &SOCKET SEND

&SOCKET SEND

Sends data to a TCP socket.

&SOCKET SEND
        ID=socket_id
      { MDO=mdo_name | VARS=prefix* [ RANGE=(start,end) ] |
        VARS={ name | name,name,... name) } |
        ARGS [ RANGE=(start,end) ] | DATA=data }
      [ LENGTH=0..4 ]

SEND is used to send data to a TCP socket, identified by the ID parameter, that has been connected by &SOCKET CONNECT or &SOCKET ACCEPT.

Operands:

ID=socklet_id

(Mandatory) Specifies the identifier of the socket that is to be used for communication.

MDO=mdo_name

Indicates that the data to be sent is contained in the specified MDO.

VARS=prefix* [ RANGE=(start,end) ]

Supplies leading characters terminated by an asterisk to denote a numeric range of variables, which contain the data to be sent.

VARS={ name | (name,name,... name) }

Specifies the names of the variables containing the data to be sent.

ARGS [ RANGE=(start,end) ]

The RANGE operand is coded to designate a start number and an end number to delimit the number of variables sent. The start and end values must be in the range 0 to 32767 and the end value must be equal to or greater than the start value.

DATA=data

Specifies the data to be sent.

LENGTH=0..4

Specifies the length of the data prefix that contains the data length. The default value is 4 which means that there is a 4 byte prefix added to the data sent containing the length of the data itself. Specifying LENGTH=0 means that no prefix is added to the message. Setting the data prefix length allows a RECEIVE operation to get all of (and only) the data sent by the current execution of the SEND verb (see Notes).

Examples: &SOCKET SEND

&SOCKET SEND LENGTH=2 ID=&NSOCKID VARS=V1

Return Codes:

0

Send successful

8

Send failed; see &ZFDBK for reason code, &ZSOCERRN and &ZSOCVERR for further error information.

Notes:

TCP protocol makes packets of the data indiscriminately-it does not retain the boundaries between sends. This means that an application may do 5 sends and the application on the remote end may do 10 receives to get all of the data. There is no correlation between the number and size of sends at one end with the number and size of receives at the other end.

If you are communicating with another NCL process using &SOCKET, the LENGTH value should match on both the SEND and RECEIVE verbs at both ends of the connection.

The LENGTH value is in network byte order (that is, the most significant byte first). If you are communicating with a machine that uses a different byte order to the network (for example, Intel X86), the machine you are communicating with must send and receive lengths in the correct format.

If the LENGTH value specified in the SEND parameters does not match the incoming data, unexpected results might occur.

The &SOCKET SEND verb is executed only by the client/server applications using TCP sockets.

More information:

&SOCKET RECEIVE

&ENCODE