Purpose
This macroinstruction deactivates
the session and any conversation matched to this session. The application
program specifies, through the deactivation type code, that either
a protocol violation has occurred or cleanup is necessary.
Usage
If the application program detects
a protocol violation committed by the partner LU or if the architected
processing indicates that a cleanup deactivation of the session should
occur, the application program issues APPCCMD CONTROL=REJECT, QUALIFY=SESSION
to terminate the session. This session can have an active conversation
associated with it. If so, the conversation fails with an indication
of an abnormal termination. The application must issue an APPCCMD
to receive the conversation failure notification and cause conversation
cleanup.
By using the deactivation type (DEACTYP) parameter,
the application program can indicate that VTAM® should send either an UNBIND PROTOCOL_VIOLATION
(X'FE') or an UNBIND CLEANUP (X'0F') to deactivate
the session. If the deactivation type parameter is omitted, or is
equal to a value other than X'0F' or X'FE', VTAM generates an UNBIND (X'0F').
The sense code parameter is ignored unless an UNBIND (X'FE')
is specified.
The application program must specify the session
that is to be deactivated. To do this, it uses the SESSID and SESSIDL
parameters to specify the session instance identifier. These parameters
were made available to the conversation at conversation allocation
from the APPCCMD CONTROL=RCVFMH5 macroinstruction and the APPCCMD
CONTROL=ALLOC macroinstruction.
VTAM posts
the application program with successful return codes if no session
is active with the specified session identifier and session identifier
length.
APPCCMD CONTROL=REJECT, QUALIFY=SESSION can be issued
without knowledge of any conversations associated with the specified
session through the SESSID parameter.
Context
This macroinstruction is not conversation-specific
and therefore is not conversation-state-driven.
Syntax
>>-+---------+--APPCCMD-- --CONTROL--=--REJECT--,--QUALIFY--=--SESSION-->
'-name-- -'
(1)
>--,--RPL--=--+-rpl_address_field----------+-------------------->
'-(--rpl_address_register--)-'
>--+-----------------------------------------------------------+-->
| (2) |
'-,--AAREA--=--+-rpl_extension_address_field----------+-----'
'-(--rpl_extension_address_register--)-'
>--+-----------------------------------------------+------------>
| (2) |
'-,--ACB--=--+-acb_address_field----------+-----'
'-(--acb_address_register--)-'
>--+---------------------------+-------------------------------->
| (2) |
'-,--BRANCH--=--+-NO--+-----'
'-YES-'
>--+--------------------------------------------------------------+-->
| (3) |
'-,--DEACTYP--=--+-8-bit_unbind_type_code----------------+-----'
'-(--8-bit_unbind_type_code_register--)-'
>--+-------------------------------------------------------------+-->
| (4) (2) |
+-,--ECB--=--+-INTERNAL-------------------+-------------------+
| +-ecb_address_field----------+ |
| '-(--ecb_address_register--)-' |
| (5) (2) |
'-,--EXIT--=--+-exit_routine_address_field----------+---------'
'-(--exit_routine_address_register--)-'
>--+-----------------------------------------------------+------>
| .-,----------------------------. |
| V (6) (2) | |
'-,--OPTCD--=--(--------+-+-ASY-----+----------+-+--)-'
| | (2) | |
| '-SYN-----' |
| (2) (7) |
'-+-KEEPSRB----------+-'
| (2) (8) |
'-NKEEPSRB---------'
>--+--------------------------------------------------------------+-->
| (3) |
'-,--SENSE--=--+-32-bit_unbind_sense_code----------------+-----'
'-(--32-bit_unbind_sense_code_register--)-'
>--+----------------------------------------------------------+-->
| (3) |
'-,--SESSID--=--+-session_instance_id_field----------+-----'
'-(--session_instance_id_register--)-'
>--+------------------------------------------------------------------+-><
| (3) |
'-,--SESSIDL--=--+-session_instance_id_length----------------+-----'
'-(--session_instance_id_length_register--)-'
Notes:
- 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.
- 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.
- 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.
- 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.
- DEACTYP=8-bit_unbind_type_code
- DEACTYP=(8-bit_unbind_type_code_register)
- The UNBIND
type code can be specified as cleanup (X'0F') or as protocol
violation (X'FE'). If DEACTYP specifies cleanup, the value
specified on the SENSE operand will be ignored. However, if DEACTYP
specifies protocol error, the UNBIND will flow with the sense code
specified by the SENSE operand. If the DEACTYP operand is omitted
or a value other than X'0F' or X'FE' is entered, VTAM will generate an UNBIND of X'0F'.
The application program can be posted with a return code of INVALID_DEACTIVATION_TYPE_CODE,
but the session may still have been deactivated successfully. This
field is labeled RPL6DETP 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.
- 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.
- SENSE=32-bit_unbind_sense_code
- SENSE=(32-bit_unbind_sense_code_register)
- Indicates
the reason for the APPCCMD CONTROL=REJECT macroinstruction. This field
specifies a 32-bit UNBIND (X'FE') sense code. VTAM generates an UNBIND (X'FE') carrying
the supplied sense code and ends the conversation. This field is labeled
RPL6SNSO in the RPL extension. (Refer to z/OS Communications Server: SNA Programmer's
LU 6.2 Guide for more information on sense codes.)
- SESSID=session_instance_id_field
- SESSID=(session_instance_id_register)
- Specifies the session
to be deactivated. The session instance identifier must refer to an
active session. (A session must be activated before it can be deactivated.)
The session instance identifier is passed to the application program
on a previous APPCCMD CONTROL=ALLOC or APPCCMD CONTROL=RCVFMH5 macroinstruction.
A session that is in pending activation state cannot be specified.
A conversation that is matched to this session fails with a session
outage notification. This field is labeled RPL6SSID in the RPL extension.
- SESSIDL=session_instance_id_length
- SESSIDL=(session_instance_id_length_register)
- Specifies
the length of the session instance ID. The value specified must be
greater than 0 and less than or equal to 8. The session instance ID
length was passed to the application program on a previous APPCCMD
CONTROL=ALLOC or APPCCMD CONTROL=RCVFMH5 macroinstruction. This field
is labeled RPL6SIDL in the RPL extension.
RPL and RPL extension fields modified by macroinstruction
The
following information shows descriptions of RPL and RPL extension
fields:
- 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. It is labeled
RPLRTNCD in the RPL.
State changes
Conversation states do not
apply to this macroinstruction.
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 |
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'001F' |
PARAMETER_ERROR—APPCCMD_ISSUED_FOR_ NON-APPC |
X'002C' |
X'0020' |
PARAMETER_ERROR—PREVIOUS_REJECT_REQUEST_ OUTSTANDING |
X'002C' |
X'0023' |
PARAMETER_ERROR—INVALID_SESSION_INSTANCE_ IDENTIFIER |
X'002C' |
X'0027' |
PARAMETER_ERROR—INVALID_DEACTIVATION_TYPE_ CODE |
X'0078' |
X'0000' |
VTAM_INACTIVE_FOR_YOUR_ACB |
X'007C' |
X'0000' |
REQUEST_ABORTED |
X'0090' |
X'0000' |
APPLICATION_NOT_APPC_CAPABLE |
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 |