 |
Purpose This macroinstruction receives
an FMH-5, which begins the application program's participation in
a conversation.
This macroinstruction allows the application
to specify how expedited information is received.
Usage When this macroinstruction is issued, VTAM® copies the FMH-5, which represents
a new conversation, into the area specified on the AREA parameter.
When the macroinstruction completes, the new conversation identifier
can be found in the CONVID field. The new conversation will be in
RECEIVE state for half-duplex conversations and in SEND/RECEIVE state
for full-duplex conversations.
If this macroinstruction is
issued before an FMH-5 is received, VTAM waits
for the FMH-5 to complete the macroinstruction. When an FMH-5 is received, VTAM bypasses the ATTN exit. If VTAM receives the FMH-5 before
this macroinstruction is issued, VTAM schedules
the ATTN exit. In either case, VTAM then
moves the FMH-5 to the application's buffer and returns the CONVID
and other return parameters. VTAM retains
any data that accompanies the FMH-5.
The application program
can use the FMH-5 to perform conversation level security processing.
Also, the FMH-5 indicates whether any GDS fields, such as DCE security
or program initialization (PIP) data, follows the FMH-5. If so, the
application program should issue APPCCMD CONTROL=RECEIVE to receive
the PIP data.
For information on how the application program
is informed that an FMH-5 is ready to be received, refer to z/OS Communications Server: SNA Programmer's
LU 6.2 Guide.
Context This macroinstruction can be issued
from the RESET conversation state.
This macroinstruction is
not mode-specific and might be issued for a mode that is retained
for persistent LU-LU sessions. However, an FMH-5 is not returned for
a mode that is being retained for persistent LU-LU sessions when this
macroinstruction is issued.
Syntax 
>>-+---------+--APPCCMD-- --CONTROL--=--RCVFMH5--,--QUALIFY--=--QUEUE-->
'-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) |
'-,--AREA--=--+-data_area_address_field----------+-----'
'-(--data_area_address_register--)-'
>--+--------------------------------------------------------+--->
| (2) |
'-,--AREALEN--=--+-data_area_length----------------+-----'
'-(--data_area_length_register--)-'
>--+---------------------------+-------------------------------->
| (2) |
'-,--BRANCH--=--+-NO--+-----'
'-YES-'
>--+-------------------------------+---------------------------->
| (3) |
'-,--CONMODE--=--+-BUFFCA-+-----'
+-CS-----+
'-LLCA---'
>--+---------------------------+-------------------------------->
| (3) |
'-,--CONXMOD--=--+-CA-+-----'
'-CS-'
>--+-------------------------------------------------------------+-->
| (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) |
'-,--RTSRTRN--=--+-BOTH-+-----'
'-EXPD-'
>--+-------------------------------------------------+---------->
| (3) |
'-,--USERFLD--=--+-4-bytes_of_user_data-----+-----'
'-(--user_data_register--)-'
>--+-----------------------------------------------------+------>
| (3) |
'-,--VTRINA--=--+-vector_address_field----------+-----'
'-(--vector_address_register--)-'
>--+----------------------------------------------------+------><
| (3) |
'-,--VTRINL--=--+-vector_length_field----------+-----'
'-(--vector_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.
- AREA=data_area_address_field
- AREA=(data_area_address_register)
- Specifies the data area in which the application program is to
receive the FMH-5. This field is labeled RPLAREA in the RPL.
- AREALEN=data_area_length
- AREALEN=(data_area_length_register)
- Specifies the size of the supplied buffer area. An FMH-5 is, at
most, 255 bytes in length. Because the application cannot determine
the length of the FMH-5 when the RCVFMH5 request is queued, VTAM fails this macroinstruction
if the length of AREALEN is less than 255 with an RCPRI, RCSEC combination
of X'002C', X'0008'. This field is labeled RPLBUFL
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 on 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 APPCCMD CONTROL=RECEIVE, QUALIFY=SPEC|ISPEC
macroinstruction.
- 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.
- 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.
- RTSRTRN
- Specifies the manner in which the Request_To_Send_Received indication
is to be reported to the application on subsequent macroinstructions.
- RTSRTRN=BOTH
- Specifies that the Request_To_Send_Received indication can be
reported in the SIGRCV and SIGDATA fields on all APPCCMDs that return
these parameters.
- RTSRTRN=EXPD
- Specifies that the Request_To_Send_Received indication can be
reported in the SIGRCV and SIGDATA fields on an APPCCMD CONTROL=SENDEXPD
or an APPCCMD CONTROL=RCVEXPD.
- USERFLD=4_bytes_of_user_data
- USERFLD=(user_data_register)
- Specifies 4 bytes of user data to be associated with the new conversation.
Whenever an APPCCMD macroinstruction completes for this conversation, 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.
- VTRINA=vector_address_field
- VTRINA=(vector_address_register)
- Specifies the address of the data area where VTAM places vector list information for the
application.
This parameter is ignored if one of the following
items is true: - VTRINA=0
- The value for VTRINL is less than the minimum length required
to return the APPCCMD vector area header.
- The value for VTRINL is not specified.
This field is labeled RPL6VAIA in the RPL extension.
- VTRINL=vector_length_field
- VTRINL=(vector_length_register)
- Specifies the length of the data area where VTAM places vector list information for the
application.
This parameter is ignored if the value for VTRINA
is 0 or is not specified. This field is labeled RPL6VAIL in the RPL
extension.
RPL and RPL extension fields modified by macroinstruction The
following information shows descriptions of RPL and RPL extension
fields: - CGID
- Specifies the 32-bit conversation group identifier. It is labeled
RPL6CGID in the RPL extension.
- CONVID
- The field in the RPL extension that returns the resource identifier
of the new conversation. This field is labeled RPL6CNVD in the RPL
extension.
- CONSTATE
- The field in the RPL extension that indicates what state the conversation
is in. It is labeled RPL6CCST.
For half-duplex conversations,
this field can have the following values: - X'00'
- RESET
- X'02'
- RECEIVE
- X'08'
- END_CONVERSATION
For full-duplex conversations, this field
can have the following values. - X'00'
- RESET
- X'80'
- FDX_RESET
- X'81'
- SEND/RECEIVE
- CRYPTLVL
- Indicates the encryption level for the conversation. This field
is labeled RPL6CRYP in the RPL extension.
- NONE (B'00')
- No data is to be encrypted.
- SELECTIVE (B'01')
- The application program specifies the data that is to be encrypted.
- REQUIRED (B'11')
- All data is to be encrypted.
- 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
another FMH-5, other than the one currently being passed to the application
program on this APPCCMD, 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 other FMH-5s are waiting to be received by the application
program.
- LOGMODE
- The field in the RPL extension that returns the logon mode name
of the session over which the FMH-5 is being returned on this APPCCMD
macroinstruction. It is an 8-byte name, padded on the right with blanks.
It is labeled RPL6MODE.
- LUNAME
- The field in the RPL extension that returns the name of the partner
LU that sent the FMH-5 being returned on this APPCCMD macroinstruction.
This LU name is the network name of the partner LU. It is an 8-byte
name, padded on the right with blanks. This field is labeled RPL6LU
in the RPL extension.
- NETID
- The field in the RPL extension that returns the network identifier
of the partner LU that sent the FMH-5 being returned on this APPCCMD
macroinstruction.
This network identifier is the identifier of
the partner LU. It can be up to 8 characters in length. If it is fewer
than 8 characters, VTAM pads
it on the right with blanks. This field is labeled RPL6NET in the
RPL extension.
- 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.
- RECLEN
- The field in the RPL that returns to the application the size,
in bytes, of the FMH-5. This field is labeled RPLRLEN in the RPL.
If the RCPRI field equals X'0000', (OK), RECLEN specifies
the number of bytes of the supplied AREA field that were used to return
the FMH-5 to the application program.
- 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.
- SENSE
- The field in the RPL extension that returns a 4-byte sense code.
This sense code has meaning if the RCPRI return code indicates a resource
failure problem. It is labeled RPL6SNSI. The sense code also can be
set when the return code is RESOURCE_FAILURE_NO_RETRY. This code indicates
why the session for the conversation was deactivated.
- SESSID
- The field in the RPL extension that, when SESSIDL is not equal
to 0, returns a session instance identifier for the session over which
the FMH-5 was received. The format of the session instance identifier
is described in the z/OS Communications Server: SNA Programmer's
LU 6.2 Guide. This field is labeled RPL6SSID in the RPL
extension.
- SESSIDL
- The field in the RPL extension that returns the length of the
session instance identifier, which is itself returned in the SESSID
field. Values in the range 0–8 are valid. This field is labeled RPL6SIDL
in the RPL extension.
- SLS
- The field in the RPL extension that indicates whether the session
was established using session-level LU-LU verification. This field
is labeled RPL6SLS in the RPL extension.
- YES (B'1')
- The session was established using session-level LU-LU verification.
- NO (B'0')
- The session was not established using session-level LU-LU verification.
Vectors returned VTAM may return the following vectors in the
area supplied by the VTRINA parameter: - VTAM-to-APPL required information vector (X'10')
- Partner's DCE capabilities vector (X'12')
- Local nonce vector (X'13')
- Partner's nonce vector (X'14')
- PCID vector (X'17')
- Session information vector (X'19')
- Partner's application capabilities vector (X'1A')
State changes These changes are applicable
when RCPRI indicates OK.
For half-duplex conversations, the
conversation state is RECEIVE after successful processing.
For
full-duplex conversations, the conversation state is SEND/RECEIVE
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. SeeReturn codes for
a description of these return codes.
| RCPRI |
RCSEC |
Meaning |
|---|
| X'0000' |
X'0000' |
OK |
| X'002C' |
X'0008' |
PARAMETER_ERROR—SUPPLIED_LENGTH_ INSUFFICIENT |
| 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'002E' |
VECTOR AREA NOT VALID |
| X'002C' |
X'002F' |
VECTOR AREA LENGTH INSUFFICIENT |
| X'0048' |
X'0000' |
RESOURCE_FAILURE_NO_RETRY |
| X'004C' |
X'0000' |
RESOURCE_FAILURE_RETRY |
| 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'00A4' |
X'0000' |
MODE_MUST_BE_RESTORED_BEFORE_USING |
| 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