Verbs and Built-in Functions › &SOCKET RECEIVE

&SOCKET RECEIVE

Receives data from a TCP socket specified by the socket ID.

&SOCKET RECEIVE

        ID=socket_id
      { MDO=mdo_name |
        VARS={ name | (name,name,... name) [SEGMENT] } |
        { ARGS | VARS=prefix* } [ RANGE=(start,end) ] [SEGMENT] }
      [ LENGTH=0..4 ]
      [ WAIT=time ]
      [ TYPE={ SYNC | ASYNC } ]

RECEIVE is used to receive data on a nominated TCP socket. The socket must have been connected to a foreign host by using &SOCKET CONNECT, or &SOCKET ACCEPT.

Operands:

ID=socklet_id

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

MDO=mdo_name

Specifies the name of the Mapped Data Object (MDO) into which data will be received.

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

Specifies the names of the variables to be the target of the RECEIVE operation. If insufficient variables are provided, some data will not be available to the procedure. Excess variables are set to a null value.

SEGMENT

Specifies that there is no delimiter character but that the parsed string will be placed into the receiving variables in segments that correspond to the length of the individual variables. The length defaults to the maximum variable length unless overridden by length specifications in a variable list.

ARGS | VARS=prefix*

Specifies that the receive operation modifies or creates variables in a numeric range (&1 through &n for ARGS, prefix1 through prefixn for VARS) depending on how many are needed to satisfy the operation.

RANGE=(start,end)

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

LENGTH=0..4

Specifies the length of the received data prefix that contains the data length. The LENGTH operand is useful when incoming messages are prefixed by the length of the rest of the message. The LENGTH value tells the &SOCKET verb the length of the prefix, not the length of the data.

The default value is 4. If a value other than 0 is used, the receive will complete only when all of the data specified by the data prefix length is received by the verb (see Notes).

WAIT=time

Specifies the period of time (in seconds) to wait for the receive to be completed. The default value is 0, meaning to wait until there is a successful receive.

TYPE={SYNC | ASYNC}

Indicates whether this is a synchronous (SYNC) or asynchronous (ASYNC) socket request.

If TYPE=ASYNC is specified, WAIT cannot be specified.

If TYPE=ASYNC is specified, the verb returns control immediately.

If data is immediately available, return code 0 is set, and VARS or MDO contain the data.

If no data is immediately available, return code 12 is set, and a notification message is queued to the dependent environment when data is available:

N00101 NOTIFY: TCP/IP EVENT: RECEIVE RESOURCE: RC=rc RSN=rsn ERR=errno VERRIN=vendor_info ID=socket_id

After receiving this message, the procedure performs another RECEIVE with the same parameters to obtain the data.

Examples: &SOCKET RECEIVE

&SOCKET RECEIVE LENGTH=2 ID=&NSOCKID VARS=R* WAIT=300

Return Codes:

0

Receive successful

4

Receive timed out

8

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

12

Wait for notification of data availability

When null data is received, the connection has been terminated.

Notes:

TCP protocol makes packets of the data in discriminately-it does not retain the boundaries between sends. This means that an application may do five 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 and 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 needs to ensure that it sends and receives lengths in the correct format.

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

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

More information:

&SOCKET SEND

&DECODE