 |
Purpose This macroinstruction sends expedited
data to a partner LU over a full-duplex or a half-duplex conversation
established on a full-duplex-capable session. If the session
is not full-duplex capable, an RCPRI, RCSEC combination of X'00A0', X'0001',
REQUEST_NOT_ALLOWED—LU_PAIR_DOES_NOT_SUPPORT_ SENDING_EXPEDITED_DATA
is returned to the application.
Usage The amount of expedited data specified
by the application should be in the range of 1–86 bytes. If the length
of the expedited data is outside of this range, an RCRPI, RCSEC combination
of X'002C', X'002C', PARAMETER_ERROR—INVALID_EXPEDITED_DATA_LENGTH
is returned to the application.
This macroinstruction will
be posted complete immediately without waiting for a response from
the partner LU. A response will not be sent by the partner until the
expedited data has been received by the partner application.
If
the conversation ends before the macroinstruction has a chance to
process, RCRPI, RCSEC combination of X'0000', X'0009',
REQUEST_TERMINATED_BY_END_OF_CONVERSATION is returned to the application.
If
this macroinstruction is issued while another APPCCMD CONTROL=SENDEXPD
macroinstruction or an APPCCMD CONTROL=SEND, QUALIFY=RQSEND macroinstruction
is currently outstanding for the specified conversation, an RCRPI,
RCSEC combination of X'002C', X'0011', PARAMETER_ERROR—PREVIOUS_MACROINSTRUCTION_OUTSTANDING
is returned to the application.
If the EXPEDITED SEND queue
has been prohibited, then an RCRPI, RCSEC combination of X'00A0', X'0002',
REQUEST_NOT_ALLOWED—REQUEST_BLOCKED, is returned to the application.
An
RCRPI, RCSEC combination of X'0050', X'0000', STATE_ERROR,
will be returned when the macroinstruction is issued in PENDING_DEALLOCATE
state.
If the macroinstruction is issued and the response to
a previously issued SENDEXPD request has not been received, then an
RCPRI, RCSEC combination of X'00A0', X'0005', REQUEST_NOT_ALLOWED—
RSP_HAS_NOT_BEEN_RECEIVED_ FOR_A_PREVIOUS_SENDEXPD_REQUEST is returned
to the application.
This macroinstruction will always cause
a flow.
This macroinstruction corresponds to the SEND_EXPEDITED_DATA
verb described in the LU 6.2 architecture.
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
- PENDING_END_CONV_LOG
- PENDING_SEND
- PENDING_RECEIVE_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 
(1)
>>-+---------+--APPCCMD-- --CONTROL--=--SENDEXPD--,--QUALIFY--=--DATA------>
'-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--=--+-data_area_or_buffer_list_address_field----------+-----'
'-(--data_area_or_buffer_list_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) |
+-+-BUFFLST------+-----+
| | (3) | |
| '-NBUFFLST-----' |
| (3) (7) |
'-+-KEEPSRB----------+-'
| (3) (8) |
'-NKEEPSRB---------'
>--+--------------------------------------------------+--------><
| (3) |
'-,--RECLEN--=--+-data_length----------------+-----'
'-(--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=data_area_or_buffer_list_address_field
- AREA=(data_area_or_buffer_list_address_register)
- Specifies
the address of a data buffer or buffer list. If OPTCD=NBUFFLST, AREA
specifies the address of a data area containing the data to be sent.
If OPTCD=BUFFLST, AREA specifies the address of a buffer list that
in turn points to the data to be sent. 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.
- 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.
- OPTCD=BUFFLST
- Specifies
that the data supplied by the application program is contained within
multiple buffers. This option allows the application program to provide
data from discontiguous buffer areas. The indicator resides within
the RPLOPT6 field of the RPL.
If OPTCD=BUFFLST is chosen, the
AREA field of the RPL points to a buffer list that is a contiguous
set of 16-byte control blocks, called buffer list entries. (Refer
to z/OS Communications Server: SNA Programmer's
LU 6.2 Guide for a detailed description of these buffer
list entries.) The RECLEN field of the RPL specifies a buffer list
length that is a nonzero multiple of 16 bytes. RU boundaries are independent
of the buffer boundaries. VTAM creates
RUs based upon the maximum SEND RU size regardless of whether the
data is taken from one buffer, part of a buffer, or multiple buffers.
Logical records are also independent of the buffer boundaries.
- OPTCD=NBUFFLST
- Specifies that the data supplied by the application program is
contained within a single buffer area. The AREA field specifies the
address of the buffer and the RECLEN field specifies the length of
the buffer. The indicator resides within the RPLOPT6 field of the
RPL.
- RECLEN=data_length
- RECLEN=(data_length_register)
- Specifies
the length of the data to be sent or the length of the buffer list
containing the data to be sent. This field is labeled RPLRLEN in the
RPL.
- If OPTCD=NBUFFLST, RECLEN specifies the number of bytes of data
to be sent from the buffer area specified by AREA.
- If OPTCD=BUFFLST, RECLEN specifies the length of the buffer list
that in turn points to the data to be sent. The RECLEN specifies a
buffer list length that is a nonzero multiple of 16 bytes. (Buffer
list entries consist of 16 bytes.)
- 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
- 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 LUs. The FMH5RCV
field continues to be set to YES so 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.
- SIGDATA
- The
field in the RPL extension in which the signal code and signal extension
fields of a received SIGNAL RU are returned to the application program.
This field has meaning only when SIGRCV=YES. This field is labeled
RPL6SGNL in the RPL extension.
X'00010001' indicates
a REQUEST_TO_SEND notification has been received from the remote application
program.
- SIGRCV
- The
field in the RPL extension that returns an indication of whether an
application program's partner has requested permission to send. This
field is labeled RPL6RSIG in the RPL extension. This field and the
SIGDATA field correspond to the REQUEST_TO_SEND_RECEIVED parameter
described in the LU 6.2 architecture. The indication is either YES
or NO (RPL6RSIG bit set on or off).
- YES (B'1')
- A SIGNAL RU has been received from the partner LU. The values
carried in the signal code and signal extension fields of the SIGNAL
RU are returned to the application program in the SIGDATA field.
- NO (B'0')
- No SIGNAL RU has been received from the partner LU. When SIGRCV=NO,
the SIGDATA field contains no meaningful 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 the 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'0010' |
PARAMETER_ERROR—INVALID_DATA_ADDRESS_OR_ LENGTH |
| X'002C' |
X'0011' |
PARAMETER_ERROR—PREVIOUS_MACROINSTRUCTION_ OUTSTANDING |
| X'002C' |
X'0012' |
PARAMETER_ERROR—BUFFER_LIST_LENGTH_INVALID |
| X'002C' |
X'002C' |
PARAMETER_ERROR—INVALID_EXPEDITED_DATA_LENGTH |
| 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'0090' |
X'0000' |
APPLICATION_NOT_APPC_CAPABLE |
| X'00A0' |
X'0001' |
REQUEST_NOT_ALLOWED—LU_PAIR_DOES_NOT_ SUPPORT_SENDING_EXPEDITED_DATA |
| X'00A0' |
X'0002' |
REQUEST_NOT_ALLOWED—REQUEST_BLOCKED |
| X'00A0' |
X'0005' |
REQUEST_NOT_ALLOWED—RSP_TO_PREVIOUS_ REQUEST_NOT_RECEIVED |
| 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