|
Purpose This macroinstruction reserves
an active contention-winner session for a conversation, if session
limits allow, without establishing a conversation. If no session is
available, the preallocation request fails. After a session is reserved,
session related information can be passed between the application
program and VTAM®. The conversation
is not active until the APPCCMD CONTROL=SENDFMH5 is issued.
Usage QUALIFY=IMMED is used to preallocate
a conversation when the application program needs an immediate response
from VTAM. This macroinstruction
completes successfully only when an active contention-winner session
is available to be reserved for a conversation. If the request cannot
be met immediately, VTAM does
not queue it. VTAM neither
tries to activate a new session nor bids on a contention-loser session.
When
a conversation is preallocated, VTAM assigns
a conversation identifier to it. This identifier is returned in the
CONVID field. The application program must associate a conversation
with a particular transaction by using the conversation identifier.
The
application program can specify how expedited data is to be received.
Context This macroinstruction is independent
of conversation states when it is issued. The initial conversation
state is created after this macroinstruction completes.
When
a mode is retained for persistent LU-LU sessions, this macroinstruction
is not allowed.
Syntax
(1)
>>-+---------+--APPCCMD-- --CONTROL--=--PREALLOC--,--QUALIFY--=--IMMED------>
'-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---'
>--+---------------------------+-------------------------------->
| (1) |
'-,--CONXMOD--=--+-CA-+-----'
'-CS-'
>--+-------------------------------------------------------------+-->
| (4) (3) |
+-,--ECB--=--+-INTERNAL-------------------+-------------------+
| +-ecb_address_field----------+ |
| '-(--ecb_address_register--)-' |
| (5) (3) |
'-,--EXIT--=--+-exit_routine_address_field----------+---------'
'-(--exit_routine_address_register--)-'
>--+-------------------------------------------+---------------->
| (1) |
'-,--LOGMODE--=--8-byte_logon_mode_name-----'
>--+----------------------------------+------------------------->
| (1) |
'-,--LUNAME--=--8-byte_lu_name-----'
>--+--------------------------------------------+--------------->
| (1) |
'-,--NETID--=--8-byte_network_identifier-----'
>--+-----------------------------------------------------+------>
| .-,----------------------------. |
| V (6) (3) | |
'-,--OPTCD--=--(--------+-+-ASY-----+----------+-+--)-'
| | (3) | |
| '-SYN-----' |
| (3) (7) |
'-+-KEEPSRB----------+-'
| (3) (8) |
'-NKEEPSRB---------'
>--+-----------------------------+------------------------------>
| (1) |
'-,--RTSRTRN--=--+-BOTH-+-----'
'-EXPD-'
>--+-------------------------------------------------+---------->
| (1) |
'-,--USERFLD--=--+-4-bytes_of_user_data-----+-----'
'-(--user_data_register--)-'
>--+-----------------------------------------------------+------>
| (1) |
'-,--VTRINA--=--+-vector_address_field----------+-----'
'-(--vector_address_register--)-'
>--+----------------------------------------------------+------><
| (1) |
'-,--VTRINL--=--+-vector_length_field----------+-----'
'-(--vector_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.
- 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.
- LOGMODE=8-byte_logon_mode_name
- Specifies the logon mode name designating the network properties
for the session to be preallocated for this conversation. The network
properties include, for example, the class of service to be used.
The logon mode name cannot be blanks. The logon mode name can
be up to 8 characters in length. If it is fewer than 8 characters
in length, VTAM pads it on
the right with blanks.
If the logon mode parameter on the
APPCCMD macroinstruction specifies a logon mode name that does not
exist in the logon mode table, VTAM uses
the mode name of blanks to retrieve the default mode entry when processing
session activation requests. (Refer to z/OS Communications Server: SNA Programmer's
LU 6.2 Guide for
more information.) This logon mode name corresponds to a logon mode
name specified in a MODEENT definition statement. (The MODEENT statement
is used to build the logon mode table named in the MODETAB operand
of the APPL definition statement for this application program.) For
more information on the MODEENT macroinstruction, refer to z/OS Communications Server: SNA Resource Definition
Reference. This field is labeled RPL6MODE in the RPL
extension.
- LUNAME=8-byte_lu_name
- Specifies the name of the partner application program at which
the remote transaction program, specified in the FMH-5 supplied in
the AREA field, is located. This LU name is the network name of the
target LU. It can be up to 8 characters in length. If it is less than
8 characters in length, VTAM pads
the LU name on the right with blanks. It is labeled RPL6LU in the
RPL extension.
- NETID=8-byte_network_identifier
- Specifies the network identifier of the partner application program
at which the remote transaction program, specified in the FMH-5 supplied
in the AREA field, is found.
If PARMS= (NQNAMES=NO) is specified
on the ACB macroinstruction and you specify NETID, the NETID value
is ignored. If PARMS= (NQNAMES=YES) is specified on the ACB macroinstruction,
NETID must be supplied.
If NQNAMES=YES, LUNAME and NETID are
used together to form the network-qualified name of the target LU.
(If NETID is specified, LUNAME must be specified.)
This network
identifier is the identifier of the target LU. It can be up to 8 characters
in length. If it is fewer than 8 characters in length, VTAM pads the network identifier on the right
with blanks. It is labeled RPL6NET in the RPL extension.
- 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 the RPL and RPL extension
fields: - AVFA
- The field in the RPL extension that indicates whether the partner
LU accepts the already-verified indicator in place of the password
security access subfield on the FMH-5s that it receives. This field
is labeled RPL6AVFA in the RPL extension.
- YES (B'1')
- The partner LU accepts the already-verified indicator.
- NO (B'0')
- The partner LU does not accept the already-verified indicator.
- 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.
This field
can have the following value at the completion of this macroinstruction:
- X'00'
- RESET
- X'08'
- END_CONV
- X'FF'
- PENDING_ALLOCATE
- CONVID
- Specifies the resource identifier of the conversation. This field
is labeled RPL6CNVD in the RPL extension.
- CONVSECP
- The field in the RPL extension that returns an indication of whether
the partner LU accepts FMH-5s that include security subfields and
indicators. The indication is either YES or NO (RPL6CLSA in RPL6RTUN
set on or off). This field is labeled RPL6CLSA in the RPL extension.
- YES (B'1')
- The partner LU accepts FMH-5s with security subfields and indicators.
The subfields allow the application program to include a password,
user ID, and profile on allocation requests.
- NO (B'0')
- The partner LU does not accept FMH-5s with security subfields.
If this is the case, VTAM strips
out any security subfields and indicators that might be included on
an allocation request.
- 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
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.
- PRSISTVP
- Indicates that the partner LU accepts requests for persistent
verification. This field is labeled RPL6PV in the RPL extension.
- YES (B'1')
- The partner LU accepts persistent-verification indicators.
- NO (B'0')
- The partner LU does not accept persistent-verification indicators.
- 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.
- SESSID
- The field in the RPL extension that returns a session instance
identifier of the session over which the FMH-5 flows. The FMH-5 is
supplied by the application program using the AREA field. This field
is labeled RPL6SSID in the RPL extension. The format of the session
instance identifier is described in the z/OS Communications Server: SNA Programmer's
LU 6.2 Guide .
- 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 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')
- Indicates that the session was established using session-level
LU-LU verification.
- NO (B'0')
- Indicates that 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')
- Send FMH_5 sequence number vector (X'15')
- Receive FMH_5 sequence number vector (X'16')
- PCID vector (X'17')
- Name change vector (X'18')
- Session information vector (X'19')
- Partner's application capabilities vector (X'1A')
State changes The conversation state is
PENDING_ALLOCATE after successful completion of this macroinstruction.
Return codes The following (RCPRI, RCSEC)
combinations can be returned to the application program when it issues
this APPCCMD macroinstruction. Refer to Return codes for
a description of these return codes.
RCPRI |
RCSEC |
Meaning |
---|
X'0000' |
X'0000' |
OK |
X'0004' |
X'000E' |
MODE_MUST_BE_RESTORED_BEFORE_USING |
X'002C' |
X'0000' |
PARAMETER_ERROR—INVALID_LU_NAME_OR_ NETWORK_IDENTIFIER |
X'002C' |
X'0001' |
PARAMETER_ERROR—INVALID_MODE |
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'002B' |
PARAMETER_ERROR—NETWORK-QUALIFIED_NAME_REQUIRED |
X'002C' |
X'002E' |
PARAMETER_ERROR—VECTOR_AREA_NOT_VALID |
X'002C' |
X'002F' |
PARAMETER_ERROR—VECTOR_AREA_LENGTH_INSUFFICIENT |
X'0058' |
X'0000' |
UNSUCCESSFUL,_SESSION_NOT_AVAILABLE |
X'0070' |
X'0000' |
TEMPORARY_STORAGE_SHORTAGE_OR_RESOURCE_ SHORTAGE |
X'0074' |
X'0000' |
HALT_ISSUED |
X'0078' |
X'0000' |
VTAM_INACTIVE_FOR_YOUR_ACB |
X'007C' |
X'0000' |
REQUEST_ABORTED |
X'0090' |
X'0000' |
APPLICATION_NOT_APPC_CAPABLE. |
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 |
X'00B0' |
X'0001' |
NAME_RESOLUTION_ERROR—LUNAME_FOUND_IN_ VARIANT_NAME_ENTRY |
X'00B0' |
X'0002' |
NAME_RESOLUTION_ERROR—NAME_RETURNED_ DIFFERS_FROM_ASSOCIATED_NAME |
X'00B0' |
X'0003' |
NAME_RESOLUTION_ERROR—NAME_RETURNED_FOUND_ IN_VARIANT_NAME_ENTRY |
X'00B0' |
X'0004' |
NAME_RESOLUTION_ERROR—NAME_RETURNED_ FOUND_IN_SUPPLIED_NAME_ENTRY |
X'00B0' |
X'0005' |
NAME_RESOLUTION_ERROR—PARTNER_NETWORK_ NAME_MISMATCH |
X'00B0' |
X'0006' |
NAME_RESOLUTION_ERROR—LUNAME_FOUND_IN_ UNUSABLE_NAME_ENTRY |
X'00B0' |
X'0007' |
NAME_RESOLUTION_ERROR—NAME_RETURNED_ FOUND_IN_UNUSABLE_NAME_ENTRY |
X'00B0' |
X'0008' |
NAME_RESOLUTION_ERROR—LU_NAME_FOUND_ IN_A_DISASSOCIATED_NAME_ENTRY |
|