Verbs and Built-in Functions › &APPC RECEIVE_AND_WAIT

&APPC RECEIVE_AND_WAIT

This option of the &APPC verb is used to receive any data sent by the conversation partner, or await its arrival if none is currently available. The short form is &APPC RECEIVE.

RECEIVE_AND_WAIT indicates a synchronous conversation receive request. If data is available, it is returned in the variables indicated. If no data is immediately available, the procedure is suspended until data arrives, or some error condition arises, at which time the request completes. A process can identify a class of conversation that satisfies a receive request. Only one event will satisfy the receive; any other events remain pending.

This verb has the following format:

&APPC{ RECEIVE_AND_WAIT | RECEIVE }
     [ ID={ ANY | CLIENTS | SERVERS | id } ] 
     [ WAIT=nn ]
     [ MDO=mdoname [ MAP=mapname ] |
       VARS=var | VARS=(var1, var2, ..., varn ) |
       VARS=prefix* [ RANGE=(start,end) ] ]

Operands:

ID={ ANY | CLIENTS | SERVERS | id }

If ID=ANY, no state changes occur. Any conversation, either client or server, that is in receive state satisfies the request.

If ID=CLIENTS, no state changes occur. Any client conversation that is in receive state satisfies the request. If operating in automatic connection accept mode, a new conversation can provide the data that satisfies such a receive.

If ID=SERVERS, no state changes occur. Any server conversation that is in the receive state satisfies the request.

If ID=id (or allowed to default to the current conversation), then this conversation must be in receive state, or it is automatically placed in receive state, if possible, before the request is accepted.

WAIT=nnn

Specifies the time, in seconds (for example, WAIT=10), or seconds and hundredths (for example, WAIT=1.25), for which the procedure is prepared to wait for a receive to be satisfied.

If not successful before this interval expires, the receive request is canceled with an unsuccessful return code (that is, &RETCODE is set to 4, and &ZFDBK is set to 4).

MDO=mdoname [ MAP=mapname ] | VARS=var |
VARS=( var1,var2,...,varn ) | VARS=prefix* [ RANGE=(start,end) ]

One of the options must be specified. The operand specifies how the incoming data is formatted.

If MDO= is used, the data is formatted into an MDO with the name mdoname. If the incoming data is mapped (that is, a map name is sent with the data), and MAP= is not specified, then the received map name is used to connect to Mapping Services Mapping Support. If the incoming data is not mapped, then it is the responsibility of the requester to connect to Mapping Services Mapping Support, if necessary, using the MAP operand.

The VARS= operand is used to provide the list of NCL variables that contains the data received on the conversation (the usual NCL VARS definitions apply). If the incoming data is not mapped, or the map name is other than $NCL, then the data stream received is segmented into the variables nominated. If the data is mapped and the map name is $NCL, then each variable is reconstructed as it was on the send request in the conversation partner. Unused variables are set to null.

Examples: &APPC RECEIVE_AND_WAIT

&APPC RECEIVE_AND_WAIT VARS=DATA

&APPC RECEIVE_AND_WAIT ID=CLIENTS VARS=DATA

Return Codes:

The return codes are as follows:

0

Request successful

4

Request unsuccessful

8

Remote program error

12

State check

16

Request or conversation error

&ZFDBK is also set, plus all APPC system variables.

State Transition:

The RECEIVE_AND_WAIT request is issued from either send or receive state, and the conversation enters or remains in receive state while the WHAT_RECEIVED indicator (&ZAPPCWR) contains DATA (that is, DATA_COMPLETE, DATA_TRUNCATED, or DATA_ INCOMPLETE).

If the WHAT_RECEIVED indicator contains SEND (where the remote conversation partner has issued PREPARE_TO_RECEIVE) the local state changes to send.

If the WHAT_RECEIVED indicator contains CONFIRM, CONFIRM_SEND, or CONFIRM_DEALLOCATE, then the local procedure should issue the CONFIRMED request following which the state changes to receive, send, or deallocate respectively.

Notes:

• When RECEIVE_AND_WAIT is issued from send state, an implied PREPARE_TO_RECEIVE TYPE=FLUSH is issued. This is the most efficient way of changing the direction of conversation flow.
• Following the interval expiry for a RECEIVE_AND_WAIT request that specified a WAIT interval, the &RETCODE is set to 4, and &ZFDBK to 0 when no data is available to satisfy the request.
• If the remote conversation partner deallocates the conversation normally, &RETCODE is set to 4 and &ZFDBK to 4.
• Server conversations are those that have been initiated locally (by issuing &APPC ALLOCATE, &APPC ATTACH, or &APPC CONNECT) while client conversations are those that have been initiated remotely. The system variable &ZAPPCCSI indicates whether a conversation is a CLIENT or SERVER conversation.
• When using the CLIENT, SERVER, or ANY operands, the process must be in automatic ACCEPT connect mode, otherwise the request is rejected with a state check. The verbs &APPC REGISTER, &APPC DEREGISTER, and &APPC SET_SERVER_MODE is used to alter the connect mode of the process.

Relationship to LU6.2 Verb Set:

&APPC RECEIVE_AND_WAIT is equivalent to the LU6.2 verb MC_RECEIVE_AND_WAIT.

More information:

&APPC REGISTER

&APPC DEREGISTER

&APPC SET_SERVER_MODE

&APPC Return Code Information

&RETCODE and &ZFDBK