APPCCMD CONTROL=SEND, QUALIFY=RQSEND

Purpose

This macroinstruction notifies the partner LU on a half-duplex conversation that the local application program is requesting to enter SEND state. The conversation is changed to SEND state when the local application program subsequently receives a SEND indication from the remote application program.

Usage

This macroinstruction can only be used on half-duplex conversations.

When this macroinstruction is issued, VTAM® sends a SIGNAL RU to the partner application program to indicate that the local LU is requesting to enter SEND state. The signal code and signal extension fields of the SIGNAL RU carry X'00010001'.

When the partner application receives the REQUEST_TO_SEND notification, it can enter RECEIVE state. When an APPCCMD CONTROL=RECEIVE macroinstruction completes and the SEND indicator is on in the WHATRCV field, the local application program is informed that it is in SEND state.

This macroinstruction can be issued while other macroinstructions are outstanding. However, if this macroinstruction is issued while an APPCCMD CONTROL=SEND, QUALIFY=RQSEND or an APPCCMD CONTROL=SENDEXPD macroinstruction is outstanding, it completes with return codes that indicate PARAMETER_ERROR—PREVIOUS_MACROINSTRUCTION_OUTSTANDING.

This macroinstruction corresponds to the REQUEST_TO_SEND verb described in the LU 6.2 architecture.

Context

For half-duplex conversations, this macroinstruction can be issued from the following conversation states:

RECEIVE
RECEIVE_CONFIRM
RECEIVE_CONFIRM_SEND
RECEIVE_CONFIRM_DEALLOCATE
SEND
PENDING_SEND

This macroinstruction is not allowed on full-duplex conversations.

This macroinstruction is not allowed for conversations pending deallocation for persistent LU-LU sessions.

Syntax


                                                                    (1)   
>>-+---------+--APPCCMD-- --CONTROL--=--SEND--,--QUALIFY--=--RQSEND------>
   '-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) |   
   '-,--BRANCH--=--+-NO--+-----'   
                   '-YES-'         

>--+-------------------------------+---------------------------->
   |                           (1) |   
   '-,--CONMODE--=--+-BUFFCA-+-----'   
                    +-CS-----+         
                    +-LLCA---+         
                    '-SAME---'         

>--+---------------------------------------------------------+-->
   |                                                     (1) |   
   '-,--CONVID--=--+-32-bit_resource_id_field----------+-----'   
                   '-(--32-bit_resource_id_register--)-'         

>--+-----------------------------+------------------------------>
   |                         (1) |   
   '-,--CONXMOD--=--+-CA---+-----'   
                    +-CS---+         
                    '-SAME-'         

>--+-------------------------------------------------------------+-->
   |                                           (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---------'

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.

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 an APPCCMD asynchronously, it is prevented from issuing another APPCCMD against the same conversation resource that processes on the EXPEDITED SEND queue until the command has completed. The application can issue APPCCMDs against the same conversation resource that processes on the SEND/RECEIVE if the conversation is half-duplex, or the SEND and RECEIVE queues if the conversation is full-duplex, and the 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 this APPCCMD.
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 the 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'06': PENDING_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

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 LUs. 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.

USERFLD

Specifies 4 bytes of user data that the application 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

No state changes are 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'0000'	X'0009'	REQUEST_TERMINATED_BY_END_OF_CONVERSATION
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'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_DEALLOCATE_ABEND
X'0090'	X'0000'	APPLICATION_NOT_APPC_CAPABLE
X'00A0'	X'0002'	REQUEST_NOT_ALLOWED—REQUEST_BLOCKED
X'00A0'	X'0004'	REQUEST_NOT_ALLOWED—CONTROL/QUALIFY_VALUE_ INVALID_FOR_FULL-DUPLEX_CONVERSATION
X'00A0'	X'0005'	REQUEST_NOT_ALLOWED—RSP_HAS_NOT_BEEN_ RECEIVED_FOR_A_PREVIOUS_SENDEXPD_REQUEST
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