Purpose
This macroinstruction is used to
deallocate a conversation that has had no activity for a specified
amount of time.
Usage
QUALIFY=ABNDTIME is used when the
LU detects that it has not received information from one of its transaction
programs within a specific amount of time. For example, an application
program would use this macroinstruction if one of the conversations
is in a state that allows receiving and has not received any data
in an excessive amount of time. The application program must determine
how long to wait before issuing this macroinstruction.
If the
conversation is in a state that allows sending, the function of the
APPCCMD CONTROL=SEND, QUALIFY=FLUSH macroinstruction is executed prior
to abnormally deallocating the conversation.
APPCCMD CONTROL=DEALLOC,
QUALIFY=ABNDTIME can be issued against a conversation for which there
is already an APPCCMD outstanding. These commands cancel the previous
macroinstruction, allowing the application program to recover from
a hung transaction. However, there are cases where it is not allowed
when a prior macroinstruction is outstanding. See Usage for a list of macroinstructions
that cannot be canceled.
QUALIFY=ABNDTIME corresponds to the
DEALLOCATE TYPE=ABEND_TIMER verb in the LU 6.2 architecture.
Refer
to z/OS Communications Server: SNA Programmer's
LU 6.2 Guide for a description of abnormally terminating
a conversation.
Context
On half-duplex conversations, this
macroinstruction can be issued from the following conversation states:
- PENDING_ALLOCATE
- SEND
- RECEIVE
- RECEIVE_CONFIRM
- RECEIVE_CONFIRM_SEND
- RECEIVE_CONFIRM_DEALLOCATE
- PEND_SEND
- PEND_END_CONV_LOG
- PENDING_RECEIVE_LOG
On full-duplex conversations, this macroinstruction can
be issued from the following conversation states:
- PENDING_ALLOCATE
- SEND/RECEIVE
- SEND_ONLY
- RECEIVE_ONLY
- PENDING_SEND/RECEIVE_LOG
- PENDING_RECEIVE-ONLY_LOG
- PENDING_RESET_LOG
This macroinstruction is not allowed for conversations
pending deallocation for persistent LU-LU sessions.
Syntax
(1)
>>-+---------+--APPCCMD-- --CONTROL--=--DEALLOC--,--QUALIFY--=--ABNDTIME------>
'-name-- -'
(2)
>--,--RPL--=--+-rpl_address_field----------+-------------------->
'-(--rpl_address_register--)-'
>--+-----------------------------------------------------------+-->
| (3) |
'-,--AAREA--=--+-rpl_extension_address_field----------+-----'
'-(--rpl_extension_address_register--)-'
>--+-----------------------------------------------+------------>
| (3) |
'-,--ACB--=--+-acb_address_field----------+-----'
'-(--acb_address_register--)-'
>--+-------------------------------------------------------------------+-->
| (3) |
'-,--AREA--=--+-optional_log_data_area_address_field----------+-----'
'-(--optional_log_data_area_address_register--)-'
>--+---------------------------+-------------------------------->
| (3) |
'-,--BRANCH--=--+-NO--+-----'
'-YES-'
>--+---------------------------------------------------------+-->
| (1) |
'-,--CONVID--=--+-32-bit_resource_id_field----------+-----'
'-(--32-bit_resource_id_register--)-'
>--+-------------------------------------------------------------+-->
| (4) (3) |
+-,--ECB--=--+-INTERNAL-------------------+-------------------+
| +-ecb_address_field----------+ |
| '-(--ecb_address_register--)-' |
| (5) (3) |
'-,--EXIT--=--+-exit_routine_address_field----------+---------'
'-(--exit_routine_address_register--)-'
>--+-----------------------------------------------------+------>
| .-,----------------------------. |
| V (6) (3) | |
'-,--OPTCD--=--(--------+-+-ASY-----+----------+-+--)-'
| | (3) | |
| '-SYN-----' |
| (3) (7) |
'-+-KEEPSRB----------+-'
| (3) (8) |
'-NKEEPSRB---------'
>--+---------------------------------------------------------------+-><
| (3) |
'-,--RECLEN--=--+-optional_log_data_length----------------+-----'
'-(--optional_log_data_length_register--)-'
Notes:
- Operand value might be placed in its RPL extension
field either by specification on an ISTRPL6 macroinstruction operand
or by explicitly setting the field using the ISTRPL6X DSECT.
- See Coding default values for
information on coding operands on the RPL or APPCCMD macroinstruction.
- Operand value might be placed in its RPL field
either by specification on an RPL macroinstruction operand or by explicitly
setting the field using the IFGRPL DSECT.
- ECB is meaningful only for asynchronous operations.
- EXIT is meaningful only for asynchronous operations.
- You can code more than one suboperand on OPTCD,
but no more than one from each group.
- KEEPSRB is meaningful only for synchronous operations.
- NKEEPSRB is meaningful only for synchronous operations.
Input parameters
The following information
shows descriptions of the input parameters:
- AAREA=rpl_extension_address_field
- AAREA=(rpl_extension_address_register)
- Specifies
the address of the LU 6.2 RPL extension that will be associated with
this APPCCMD macroinstruction. This field is labeled RPLAAREA in the
RPL.
- ACB=acb_address_field
- ACB=(acb_address_register)
- Specifies the address of an access method
control block that identifies the application program that is issuing
the APPCCMD macroinstruction. VTAM® associates
conversations with application programs using the conversation ID
(CONVID). The application program associates conversations with transaction
programs. Application programs cannot issue APPCCMD macroinstructions
in address spaces other than the ACB address space. This field is
labeled RPLDACB in the RPL.
- AREA=optional_log_data_area_address_field
- AREA=(optional_log_data_area_address_register)
- Specifies the
address of a data area containing a formatted error log GDS variable
to be sent to the partner application program. The application program
is responsible for placing the error log data into the local system
log. If the application program chooses to supply an error log GDS
variable, it has to supply the entire GDS variable on the APPCCMD
macroinstruction. VTAM inspects
the 2-byte logical-record length (LL) field of the GDS variable to
determine if the amount of data supplied is equal to the length specified
in the LL field. (Refer to z/OS Communications Server: SNA Programmer's
LU 6.2 Guide for a description of the error log GDS variable.)
This field is labeled RPLAREA in the RPL.
- BRANCH
- Specifies whether authorized
path processing is to be used for application programs running in
supervisor state under a TCB. Application programs running in TCB-mode
supervisor state can use BRANCH=YES to obtain authorized path services.
The indicator resides within the RPLEXTDS field of the RPL.
- BRANCH=NO
- Authorized path processing is not to be used. For application
programs running in problem state (non-supervisor state) under a TCB,
BRANCH=NO is the only option.
- BRANCH=YES
- Authorized path processing is to be used. For application programs
running under an SRB rather than under a TCB, the macroinstruction
is processed in this manner automatically, regardless of the actual
setting of the BRANCH field.
- CONVID=32-bit_resource_id_field
- CONVID=(32-bit_resource_id_register)
- Specifies the resource
ID of the conversation. This field is labeled RPL6CNVD in the RPL
extension.
- ECB
- Valid only
if OPTCD=ASY. Specifies how the application program requests to be
informed of the completion of the APPCCMD macroinstruction. You cannot
specify both ECB and EXIT on a single APPCCMD macroinstruction. The
indicator resides within the RPLOPT1 field of the RPL.
- ECB=INTERNAL
- Specifies that VTAM is
to post an internal ECB when the APPPCCMD macroinstruction completes.
- ECB=ecb_address_field
- ECB=(ecb_address_register)
- Specifies that VTAM is
to post an event control block (ECB) when an asynchronous APPCCMD
completes. Event_control_block_address is
the location of the ECB to be posted. The ECB can be any fullword
of storage aligned on a fullword boundary.
- EXIT=exit_routine_address_field
- EXIT=(exit_routine_address_register)
- Valid only if OPTCD=ASY. It
indicates the address of a routine to be scheduled when the APPCCMD
completes. You cannot specify both ECB and EXIT on a single APPCCMD
macroinstruction. The indicator resides within the RPLEXTDS field
of the RPL.
- OPTCD
- Specifies the following processing
options that can be selected for the macroinstruction request:
- OPTCD=SYN
- Specifies that control is to be returned synchronously to the
application program when the function of the APPCCMD has completed.
The indicator resides within the RPLOPT1 field of the RPL.
- OPTCD=ASY
- Specifies that control is to be returned to the application program
immediately and that the application program is to be informed later
of the completion of the macroinstruction by the posting of an ECB
or the scheduling of an exit. The indicator resides within the RPLOPT1
field of the RPL.
- OPTCD=KEEPSRB
- Specifies that for a synchronous request issued in SRB mode, VTAM returns to the application
under the same SRB in which VTAM was
invoked. The indicator resides within the RPLOPT11 field of the RPL.
- OPTCD=NKEEPSRB
- Specifies that for a synchronous request issued in SRB mode, VTAM does not return to the application
under the same SRB in which VTAM was
invoked. The indicator resides within the RPLOPT11 field of the RPL.
- RECLEN=optional_log_data_length
- RECLEN=(optional_log_data_length_register)
- Specifies the
length of the data area indicated by the AREA field. This field is
labeled RPLRLEN in the RPL. A value of 0 in the RECLEN field indicates
that the application program has chosen not to provide optional error
log data to VTAM. If the application
program specifies RECLEN=0, VTAM indicates
in the FMH-7 it creates as a result of this APPCCMD that no error
log data follows the FMH-7, and the AREA field in the RPL is ignored.
- RPL=rpl_address_field
- RPL=(rpl_address_register)
- Specifies the
address of the request parameter list that contains information to
be used during the processing of the APPCCMD macroinstruction.
RPL and RPL extension fields modified by macroinstruction
The
following information shows descriptions of the RPL and RPL extension
fields:
- CONSTATE
- The field in
the RPL6 extension that indicates the state of the conversation. This
field is labeled RPL6AVFA in the RPL extension.
For half-duplex
conversations, this field can have the following values:
- X'01'
- SEND
- X'02'
- RECEIVE
- X'03'
- RECEIVE_CONFIRM
- X'04'
- RECEIVE_CONFIRM_SEND
- X'05'
- RECEIVE_CONFIRM_DEALLOCATE
- X'07'
- PENDING_END_CONVERSATION_LOG
- X'08'
- END_CONVERSATION
- X'09'
- PENDING_SEND
- X'0A'
- PENDING_RECEIVE_LOG
For full-duplex conversations, this field
can have the following values:
- X'80'
- FDX_RESET
- X'81'
- SEND/RECEIVE
- X'82'
- SEND_ONLY
- X'83'
- RECEIVE_ONLY
- X'84'
- PENDING_SEND/RECEIVE_LOG
- X'85'
- PENDING_RECEIVE-ONLY_LOG
- X'86'
- PENDING_RESET_LOG
- EXPDLEN
- The field in
the RPL6 that shows the length of the expedited data waiting to be
received. This field has meaning only when EXPDRCV=YES. This field
is labeled RPL6EXDL in the RPL extension.
- EXPDRCV
- The field in
the RPL6 that indicates whether expedited data is waiting to be received.
This field is labeled RPL6EXDR in the RPL extension.
- FDB2
- The field in
the RPL in which a global VTAM secondary
return code is returned to the application program. It is labeled
RPLFDB2 in the RPL.
- FMH5LEN
- The field in
the RPL extension that returns the length of the FMH-5 waiting to
be received by the application program. If multiple FMH-5s are waiting
to be received, FMH5LEN specifies the length of the longest FMH-5
to be received by the application program. This field has meaning
only when FMH5RCV=YES. This field is labeled RPL6MH5L in the RPL extension.
- FMH5RCV
- The field in
the RPL extension that returns an indication of whether an FMH-5 has
been received. The indication is either YES or NO (RPL6RMH5 set on
or off). This field is labeled RPL6RMH5 in the RPL extension.
- YES (B'1')
- One or more FMH-5s have been received from partner application
programs. The FMH5RCV field continues to be set to YES as long as
an FMH-5 is waiting to be received by the application program. The
application program must issue APPCCMD CONTROL=RCVFMH5 in order to
receive an FMH-5.
- NO (B'0')
- No FMH-5s are waiting to be received by the application program.
- RCPRI
- The field in
the RPL extension in which an APPCCMD-specific primary return code
is returned to the application program. This field has meaning only
when RTNCD=X'00' and FDB2=X'0B'. This field is labeled
RPL6RCPR in the RPL extension.
- RCSEC
- The field in
the RPL extension in which an APPCCMD-specific secondary return code
is returned to the application program. This field has meaning only
when RTNCD=X'00' and FDB2=X'0B'. This field is labeled
RPL6RCSC in the RPL extension. The combination of the RCPRI and RCSEC
fields indicates the result of the macroinstruction processing.
- RTNCD
- The field in
the RPL in which a global VTAM primary
return code is returned to the application program. This field is
labeled RPLRTNCD in the RPL.
- STSHBF
- The field in
the RPL extension that returns the address of the current buffer.
It is used with STSHDS to give the current position (address and displacement)
in the application-supplied data buffer or buffer list (the area pointed
to by the AREA field of the RPL) when a temporary storage shortage
occurs while data is being sent. All data prior to this buffer has
been sent. This field is labeled RPL6STBF in the RPL extension.
- STSHDS
- The field in
the RPL extension that returns the displacement into the current buffer.
It is used with STSHBF to give the current position (address and displacement)
in the application-supplied data buffer or buffer list (the area pointed
to by the AREA field of the RPL) when a temporary storage shortage
occurs while data is being sent. All data prior to this buffer has
been sent. This field is labeled RPL6STDS in the RPL extension.
Refer
to z/OS Communications Server: SNA Programmer's
LU 6.2 Guide for more information.
- USERFLD
- Specifies 4
bytes of user data that the application program requests be associated
with a conversation. Whenever an APPCCMD completes, VTAM places in the USERFLD field of the RPL
extension the 4 bytes that were supplied on the APPCCMD CONTROL=ALLOC
macroinstruction (if the conversation was initiated by the local application
program) or the APPCCMD CONTROL=RCVFMH5 macroinstruction (if the conversation
was initiated by a remote application program). This field is labeled
RPL6USR in the RPL extension.
Refer to z/OS Communications Server: SNA Programmer's
LU 6.2 Guide for more information.
State changes
These changes are applicable
when RCPRI indicates OK.
For half-duplex conversations, the
conversation state is END_CONV after successful processing.
For
full-duplex conversations, the conversation state is FDX_RESET after
successful processing.
See Return codes for
state changes associated with other return codes.
Return codes
The following (RCPRI, RCSEC)
combinations can be returned to the application program when it issues
this APPCCMD macroinstruction. See Return codes for
a description of these return codes.
| RCPRI |
RCSEC |
Meaning |
|---|
| X'0000' |
X'0000' |
OK (DEALLOCATION IS COMPLETE) |
| X'002C' |
X'0002' |
PARAMETER_ERROR—INVALID_CONVERSATION_ID |
| X'002C' |
X'000B' |
PARAMETER_ERROR—INCOMPLETE_GDS_VARIABLE_ SUPPLIED |
| X'002C' |
X'000C' |
PARAMETER_ERROR—ZERO_EXIT_FIELD |
| X'002C' |
X'000D' |
PARAMETER_ERROR—ZERO_ECB_FIELD |
| X'002C' |
X'000E' |
PARAMETER_ERROR—REQUEST_INVALID_FOR_ ADDRESS_SPACE |
| X'002C' |
X'000F' |
PARAMETER_ERROR—CONTROL_BLOCK_INVALID |
| X'002C' |
X'0010' |
PARAMETER_ERROR—INVALID_DATA_ ADDRESS_OR_LENGTH |
| X'002C' |
X'0011' |
PARAMETER_ERROR—PREVIOUS_MACROINSTRUCTION_ OUTSTANDING |
| X'002C' |
X'001F' |
PARAMETER_ERROR—APPCCMD_ISSUED_FOR_ NON-APPC |
| X'002C' |
X'0021' |
PARAMETER_ERROR—ABNORMAL_DEALLOCATE_ REJECTED_RETRY |
| X'002C' |
X'0032' |
PARAMETER_ERROR— UNEXPECTED_VECTOR_PROVIDED_ON_APPCCMD |
| X'0050' |
X'0000' |
STATE_ERROR |
| X'0070' |
X'0000' |
TEMPORARY_STORAGE_SHORTAGE_OR_RESOURCE_ SHORTAGE |
| X'0078' |
X'0000' |
VTAM_INACTIVE_FOR_YOUR_ACB |
| X'007C' |
X'0000' |
REQUEST_ABORTED |
| X'0088' |
X'0000' |
CANCELLED_BY_REJECT_OR_DEALLOC_ABEND |
| X'0090' |
X'0000' |
APPLICATION_NOT_APPC_CAPABLE |
| X'0098' |
X'0000' |
STORAGE_SHORTAGE_WHILE_SENDING_DATA |
| X'00A8' |
X'0000' |
ENVIRONMENT_ERROR_OS_LEVEL_DOES_NOT_SUPPORT_ REQUESTED_FUNCTION |
| X'00A8' |
X'0001' |
ENVIRONMENT_ERROR—SUSPEND_FAILURE |
| X'00A8' |
X'0002' |
ENVIRONMENT_ERROR—RESUME_FAILURE |
z/OS Communications Server: SNA Programmer's LU 6.2 Reference
Copyright IBM Corporation 1990, 2014