Verbs and Built-in Functions › &APPC DEALLOCATE

&APPC DEALLOCATE

&APPC DEALLOCATE requests conversation termination and deallocation of its resources.

&APPC DEALLOCATE is used when an NCL procedure detects an error situation. The process can abnormally terminate the conversation with the remote application. In this case, it can provide a text string to be included in the Error Log GDS variable.

This verb has the following format:

&APPC  DEALLOCATE
     [ TYPE={ SYNC | FLUSH | CONFIRM | ABEND | LOCAL } ]
     [ ID=id ]
     [ LOG=msg ]

Operands:

TYPE={ SYNC | FLUSH | CONFIRM | ABEND | LOCAL }

Specifies the deallocate option as follows:

• TYPE=SYNC is issued from send state only, and is the default. If the conversation sync level is CONFIRM it is equivalent to the DEALLOCATE TYPE=CONFIRM option, otherwise a DEALLOCATE TYPE=FLUSH is assumed.
• TYPE=FLUSH is issued from send state only, and results in all data being flushed, forcing its transmission to the conversation partner before unconditional deallocation occurs (see Notes for this option).
• TYPE=CONFIRM is issued from send state only, and results in all data being flushed and a confirmation being requested before deallocation occurs (see Notes for this option).
• TYPE=ABEND is issued from the send, defer, receive, or any of the confirm states to abnormally terminate the conversation.
• TYPE=LOCAL is issued from the deallocate state only to terminate the conversation and free any locally held resources after a remote deallocation has occurred.

ID=id

Specifies the conversation identifier (as first returned by the system variable &ZAPPCID after successful allocation) that references a particular conversation. If this parameter is omitted, the current (last referenced, or only) conversation is assumed.

LOG=msg

Allowed for TYPE=ABEND only. It must be the last operand specified for the verb. All data following the LOG= operand is placed unchanged into the message area of the Error Log GDS variable sent to the remote application with the abnormal termination indication.

If the remote application is an NCL procedure, it can access this text, after receiving an error return code in the &ZAPPCELM system variable.

Examples: &APPC DEALLOCATE

&APPC DEALLOCATE TYPE=FLUSH

&APPC DEALLOCATE TYPE=LOCAL

&APPC DEALLOCATE TYPE=ABEND LOG=&ERRMSG

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 DEALLOCATE request is issued in certain states according to the TYPE option used. Following successful completion, the conversation enters reset state, that is, it becomes inoperable.

Notes:

• A DEALLOCATE TYPE=LOCAL request is the only conversation action permissible once the deallocate state is entered. This state follows receipt of a DEALLOCATE TYPE=FLUSH or TYPE=ABEND from the remote conversation partner.
• Normal deallocation (that is, of TYPE=SYNC, FLUSH or CONFIRM) can fail if an error is received from the remote program before the deallocation is processed.
• A DEALLOCATE TYPE=FLUSH (or TYPE=SYNC where the conversation was allocated with SYNC_LEVEL=NONE), is not subject to any confirmation from the remote partner. Hence, as it is issued from send state, if no intervening error conditions have arisen it is always successful.
• When a DEALLOCATE TYPE=CONFIRM (or TYPE=SYNC where the conversation was allocated with SYNC_LEVEL=CONFIRM) is issued, the deallocation is subject to a confirmation from the remote partner. Once confirmation is received locally (that is, the remote program issues CONFIRMED), the deallocation completes successfully. However, if the remote program instead issues a SEND_ERROR the conversation is not terminated and locally enters receive state.
• If a DEALLOCATE ABEND is issued, or a procedure terminates before the conversation has been allocated to a session, no data will flow.

Relationship to LU6.2 Verb Set:

&APPC DEALLOCATE is equivalent to the LU6.2 verb MC_DEALLOCATE.

More information:

&APPC Return Code Information

&RETCODE and &ZFDBK