Purpose
This macroinstruction changes the
existing continuation modes of a conversation. For example, it can
change the conversation from continue-specific (CS) mode to logical-record-continue-any
(LLCA) mode for receiving normal information.
This macroinstruction
can also change the existing mode for receiving expedited information.
Usage
When this macroinstruction is issued, VTAM® changes the continuation mode
for receiving normal information of the conversation specified with
the CONVID parameter to the continuation mode specified on the CONMODE
parameter.
VTAM also
changes the expedited information mode of the conversation specified
with the CONXMOD parameter to the expedited information mode specified
on the CONXMOD parameter.
For a complete discussion of continuation
modes and an example of how this macroinstruction can be used, refer
to z/OS Communications Server: SNA Programmer's
LU 6.2 Guide.
Context
For half-duplex conversations,
this macroinstruction can be issued from the following conversation
states:
- SEND
- RECEIVE
- RECEIVE_CONFIRM
- RECEIVE_CONFIRM_SEND
- RECEIVE_CONFIRM_DEALLOCATE
- PEND_END_CONV_LOG
- PEND_RCV_LOG
For full-duplex conversation, this macroinstruction can
be issued form the following conversations states:
- 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
>>-+---------+--APPCCMD-- --CONTROL--=--RESETRCV--+---------------------+-->
'-name-- -' '-,--QUALIFY--=--NULL-'
(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) |
'-,--CONMODE--=--+-BUFFCA-+-----'
+-CS-----+
+-LLCA---+
'-SAME---'
>--+---------------------------------------------------------+-->
| (3) |
'-,--CONVID--=--+-32-bit_resource_id_field----------+-----'
'-(--32-bit_resource_id_register--)-'
>--+-----------------------------+------------------------------>
| (3) |
'-,--CONXMOD--=--+-CA---+-----'
+-CS---+
'-SAME-'
>--+-------------------------------------------------------------+-->
| (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---------'
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.
- CONMODE
- Specifies the mode for receiving
normal information upon completion of the APPCCMD. This field is labeled
RPL6CMOD in the RPL extension.
- CONMODE=BUFFCA
- Specifies that the conversation is to be placed in buffer-continue-any
mode. It indicates that APPCCMD CONTROL=RECEIVE, QUALIFY=ANY|IANY
can be used to receive data and that the application program is to
receive data independently of the logical-record format of the data.
BUFFCA corresponds to FILL=BUFFER on the APPCCMD CONTROL=RECEIVE,
QUALIFY=SPEC|ISPEC macroinstruction.
- CONMODE=CS
- Specifies that the conversation is to be placed in continue-specific
mode. It indicates that only APPCCMD CONTROL=RECEIVE, QUALIFY=SPEC|ISPEC
can be used to receive data on this conversation. When the application
program issues APPCCMD CONTROL=RECEIVE, QUALIFY=SPEC|ISPEC, it must
indicate whether the data is to be received in terms of the logical-record
format of the data or independently of the logical-record format of
the data.
- CONMODE=LLCA
- Specifies that the conversation is to be placed in logical-record-continue-any
mode. It indicates that APPCCMD CONTROL=RECEIVE, QUALIFY=ANY|IANY
can be used to receive data on this conversation and that the application
program is to receive data in terms of the logical-record format of
the data. LLCA corresponds to FILL=LL on the APPCCMD CONTROL=RECEIVE,
QUALIFY=SPEC|ISPEC macroinstruction.
- CONMODE=SAME
- Specifies that the continuation mode of the conversation is to
remain unchanged.
- 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.
- CONXMOD
- Specifies the mode for receiving
expedited information upon completion of the APPCCMD. This field is
labeled RPL6CXMD in the RPL extension.
- CONXMOD=CA
- Specifies that the mode for expedited information is to be put
in such a state that expedited information can be received by either
a specific-type macroinstruction or an any-type macroinstruction,
such as, APPCCMD CONTROL=RCVEXPD, QUALIFY=SPEC|ISPEC or APPCCMD CONTROL=RCVEXPD,
QUALIFY=ANY|IANY.
- CONXMOD=CS
- Specifies that the mode for expedited information is to be put
in such a state that expedited information can be received only by
a specific-type macroinstruction, such as, APPCCMD CONTROL=RCVEXPD,
QUALIFY=SPEC or ISPEC.
- CONXMOD=SAME
- Specifies that the conversation mode for expedited information
is to remain unchanged at the completion of this macroinstruction.
- 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.
- When the application program regains control after issuing this
APPCCMD asynchronously, it is prevented from issuing another APPCCMD
against the same conversation resource (that processes on the SEND/RECEIVE
queue if the conversation is half-duplex, or on the SEND queue if
the conversation is full-duplex) until the command has completed.
The exceptions to this are the APPCCMD CONTROL=REJECT, QUALIFY=CONV
macroinstruction and the abnormal termination APPCCMD CONTROL=DEALLOC|DEALLOCQ
macroinstruction. The application program can issue APPCCMDs against
the same conversation resource that processes on the RECEIVE (if the
conversation is full-duplex), EXPEDITED SEND, EXPEDITED RECEIVE, and
TESTSTAT queues. For more information about conversation queues, refer
to z/OS Communications Server: SNA Programmer's
LU 6.2 Guide.
The application program is allowed to
issue APPCCMDs against other conversations. OPTCD=ASY is recommended
when issuing the APPCCMD on a full-duplex conversation.
- 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.
RPL and RPL extension fields modified by macroinstruction
The
following information shows descriptions of RPL and RPL extension
fields:
- CONSTATE
- The field
in the RPL6 extension that indicates the state of conversation. This
field is labeled RPL6CCST 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 contain 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
- 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.
- 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.
State changes
There are no state changes
associated with 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'0002' |
PARAMETER_ERROR—INVALID_CONVERSATION_ID |
| 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'0011' |
PARAMETER_ERROR—PREVIOUS_MACROINSTRUCTION_ OUTSTANDING |
| X'002C' |
X'001F' |
PARAMETER_ERROR—APPCCMD_ISSUED_FOR_ NON-APPC |
| 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'00A0' |
X'0002' |
REQUEST_NOT_ALLOWED—REQUEST_BLOCKED |
| 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