|
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.
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 GDS data.
If
no FMH-5 is available for the application to receive, this macroinstruction
is rejected with an RCPRI return code of X'0060'.
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--+---------------------+-->
'-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) |
'-,--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. The supplied buffer area must
be large enough to contain the entire FMH-5. An FMH-5 is at most 255
bytes in length (it has only 1 byte for a length count). If a 255-byte
buffer is used to receive the FMH-5, the RCVFMH5 macroinstruction
will never fail for lack of buffer space. 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.
- CONSTATE
- The field in the RPL extension
that indicates what state the conversation is in. It is labeled RPL6CCST
in the RPL extension.
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
- 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.
- 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 in the
RPL extension.
- 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. If
the (RCPRI, RCSEC) fields equal X'002C', X'0008',
PARAMETER_ERROR—SUPPLIED_LENGTH_INSUFFICIENT, it indicates the size
of the FMH-5. However, in the latter case, because the supplied buffer
was not large enough to contain the entire FMH-5, the FMH-5 is not
returned to the application program. The application program is informed,
through the FMH5LEN, of how large the buffer must be in order to receive
the FMH-5.
- 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 in the RPL extension. 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 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 or not 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. See Return 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' |
PARAMETER_ERROR—VECTOR_AREA_NOT_VALID |
X'002C' |
X'002F' |
PARAMETER_ERROR—VECTOR_AREA_LENGTH_INSUFFICIENT |
X'0048' |
X'0000' |
RESOURCE_FAILURE_NO_RETRY |
X'004C' |
X'0000' |
RESOURCE_FAILURE_RETRY |
X'0060' |
X'0000' |
NO_FMH5_AVAILABLE |
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 |
|