[MC_]DEALLOCATE

The DEALLOCATE verb deallocates a conversation between two transaction programs. Before deallocating the conversation, this verb performs the equivalent of one of the following verbs:
  • The FLUSH verb, which sends the contents of the local LU's send buffer to the partner LU (and transaction processor).
  • The CONFIRM verb, which sends the contents of the local LU's send buffer and a confirmation request to the partner transaction programs.
After this verb has successfully executed, the conversation ID is no longer valid.
For half-duplex conversation:
  • Deallocates the specified conversation from the transaction program, it can include the function of the FLUSH or CONFIRM verb.
For full-duplex conversation
  • DEALLOCATE with TYPE(FLUSH) closes the local program's send queue. Both the local and remote programs must close their send queues independently therefore, two DEALLOCATE TYPE(FLUSH) verbs are required to end the conversation. Notification that the partner has closed its send queue is given to the receive queue in the form of a DEALLOCATE_NORMAL return code.
  • DEALLOCATE with TYPE(ABEND) is an abrupt termination that will close both sides of the conversation simultaneously. This notification is returned to the remote program's send queue as an ERROR_INDICATION return code, and to remote program's receive queue as a DEALLOCATE_ABEND return code.

VCB Structure

typedef struct deallocate
{
 unsigned short    opcode;              /* verb operation code     */
 unsigned char     opext;               /* verb extension code     */
 unsigned char     format;              /* format                  */
 unsigned short    primary_rc;          /* primary return code     */
 unsigned long     secondary_rc;        /* secondary return code   */
 unsigned char     tp_id[8];            /* TP identifier           */
 unsigned long     conv_id;             /* conversation identifier */
#ifdef WINAPPC_FORMAT_1
 unsigned char     expd_data_rcvd;      /* expedited data received */
 unsigned char     reserv3;             /* reserved                */
#endif
 unsigned char     dealloc_type;        /* deallocate type         */
 unsigned short    log_dlen;            /* log data length         */
 unsigned char    *log_dptr;            /* pointer to log data     */
} DEALLOCATE;
typedef struct mc_deallocate
{
 unsigned short    opcode;               /* verb operation code     */
 unsigned char     opext;                /* verb extension code     */
 unsigned char     format;               /* format                  */
 unsigned short    primary_rc;           /* primary return code     */
 unsigned long     secondary_rc;         /* secondary return code   */
 unsigned char     tp_id[8];             /* TP identifier           */
 unsigned long     conv_id;              /* conversation identifier */
#ifdef WINAPPC_FORMAT_1
 unsigned char     expd_data_rcvd;       /* expedited data received */
 unsigned char     reserv3;              /* reserved                */
#endif

 unsigned char     dealloc_type;         /* deallocate type         */
 unsigned char     reserv4[2];           /* reserved                */
 unsigned char     reserv5[4];           /* reserved                */
} MC_DEALLOCATE;

Supplied Parameters

The transaction programs supplies the following parameters to Personal Communications:
opcode
AP_B_DEALLOCATE
Displays a basic verb icon.
AP_M_DEALLOCATE
Displays a mapped verb icon.
opext
AP_BASIC_CONVERSATION or AP_MAPPED_CONVERSATION. For nonblocking operation, this flag can be ORed together with AP_NON_BLOCKING.
On full-duplex conversations, this flag must be ORed together with AP_FULL_DUPLEX_CONVERSATION.
Displays a basic verb icon.
format
Identifies the format of the VCB. Set this field to one to specify the version of the VCB listed above.
tp_id
Identifier for the local transaction program. The value of this parameter was returned by the TP_STARTED verb in the invoking transaction processor or by RECEIVE_ALLOCATE in the invoked transaction program.
conv_id
Conversation identifier. The value of this parameter was returned by the ALLOCATE verb in the invoking transaction program or by RECEIVE_ALLOCATE in the invoked transaction program.
dealloc_type
Specifies how to perform the deallocation.
AP_ABEND
Displays a mapped verb icon.
AP_ABEND_PROG
Displays a basic verb icon.
  • AP_ABEND_SVC
  • AP_ABEND_TIMER
  • AP_FLUSH
  • AP_SYNC_LEVEL
  • The following values apply to basic only.
    Displays a basic verb icon.
  • AP_TP_NOT_AVAIL_NO_RETRY
  • AP_TP_NOT_AVAIL_RETRY
  • AP_TPN_NOT_RECOGNIZED
  • AP_PIP_DATA_NOT_ALLOWED
  • AP_PIP_DATA_INCORRECT
  • AP_RESOURCE_FAILURE_NO_RETRY
  • AP_CONV_TYPE_MISMATCH
  • AP_SYNC_LVL_NOT_SUPPORTED
  • AP_SECURITY_PARAMS_INVALID
log_dlen
Displays a basic verb icon.

 

Number of bytes of data to be sent to the error log file.

Range: 0–32767

The application can append data to the end of the VCB, in which case this field will be greater than zero and log_dptr must be set to NULL. (A length of zero indicates that there is no error log data.)

log_dptr
Displays a basic verb icon.

 

Address of data buffer containing error information. The application can append data to the end of the VCB, in which case log_dptr must be set to NULL.

This data is sent to the local error log and to the partner LU. The transaction processor must format the error data as a General Data Stream (GDS) error log variable. For further information, refer to IBM® Systems Network Architecture: LU 6.2 Reference: Peer Protocols.

Returned Parameters

If the verb executes successfully, Personal Communications returns the following parameter:
primary_rc
AP_OK
expd_data_rcvd
Expedited-data-received indicator. This indication continues to be set to AP_YES until a RECEIVE_EXPEDITED_DATA is issued.

This field requires the format 1 version of the VCB. See Full-Duplex VCBs for more details on accessing format 1 VCBs.

AP_YES
AP_NO

If the verb does not execute because of a parameter error, Personal Communications returns the following parameters:
primary_rc
AP_PARAMETER_CHECK
secondary_rc
  • AP_BAD_CONV_ID
  • AP_BAD_TP_ID
  • AP_DEALLOC_BAD_TYPE
  • AP_DEALLOC_LOG_LL_WRONG
    Displays a basic verb icon.
If the verb does not execute because of a parameter error, Personal Communications returns the following parameters (for mapped only):
Displays a mapped verb icon.
primary_rc
AP_OPERATION_INCOMPLETE
opext
AP_OPERATION_INCOMPLETE_FLAG
If the conversation is in the wrong state when the transaction processor issues this verb, Personal Communications returns the following parameters:
primary_rc
AP_STATE_CHECK
secondary_rc
  • AP_DEALLOC_CONFIRM_BAD_STATE
  • AP_DEALLOC_FLUSH_BAD_STATE
  • AP_DEALLOC_NOT_LL_BDY
    Displays a basic verb icon.
The conditions generating the following possible primary return codes (primary_rc) and indented secondary return codes (secondary_rc) are described in APPC Common Return Codes.

AP_ALLOCATION_ERROR

  • AP_SECURITY_NOT_VALID
  • AP_TRANS_PGM_NOT_AVAIL_RETRY
  • AP_TRANS_PGM_NOT_AVAIL_NO_RTRY
  • AP_TP_NAME_NOT_RECOGNIZED
  • AP_PIP_NOT_ALLOWED
  • AP_PIP_NOT_SPECIFIED_CORRECTLY
  • AP_CONVERSATION_TYPE_MISMATCH
  • AP_SYNC_LEVEL_NOT_SUPPORTED
  • AP_CONV_FAILURE_NO_RETRY
  • AP_CONV_FAILURE_RETRY
  • AP_DEALLOC_ABEND
    Displays a mapped verb icon.
  • AP_DEALLOC_ABEND_PROG
    Displays a basic verb icon.
  • AP_DEALLOC_ABEND_SVC
    Displays a basic verb icon.
  • AP_DEALLOC_ABEND_TIMER

  • AP_PROG_ERROR_PURGING
  • AP_SVC_ERROR_PURGING
    Displays a basic verb icon.

AP_TP_BUSY
AP_CONVERSATION_TYPE_MIXED
AP_DUPLEX_TYPE_MIXED
AP_UNEXPECTED_SYSTEM_ERROR
AP_CANCELLED
AP_ERROR_INDICATION

  • AP_ALLOCATION_ERROR_PENDING
  • AP_DEALLOC_ABEND_PROG_PENDING
  • AP_DEALLOC_ABEND_SVC_PENDING
  • AP_DEALLOC_ABEND_TIMER_PENDING
  • AP_UNKNOWN_ERROR_TYPE_PENDING
Note:
For performance reasons, the SNA API client can return a successful return code on the [MC_]SEND_DATA verb without forwarding it to the server. When a subsequent [MC_]DEALLOCATE verb is issued, the [MC_]SEND_DATA is forwarded to the server for processing. If there is a [MC_]SEND_DATA error return code, it is returned on the [MC_]DEALLOCATE verb. See [MC_]SEND_DATA for a list of error return codes.