Purpose
This macroinstruction returns information
associated with an LU or a mode name of an LU.
Usage
The information returned from this
macroinstruction is contained in the DEFINE/DISPLAY control block.
You must specify the address of this control block in the RPL when
issuing the macroinstruction. It is contained in the RPLAREA field,
which can be set with the AREA keyword. Refer to z/OS Communications Server: SNA Programmer's
LU 6.2 Guide for a description of the control block.
The
execution of this macroinstruction involves only the application program.
It does not cause any information to be sent through the network.
There is no direct correlation to the DISPLAY verb described in the
LU 6.2 architecture.
Context
Conversation states are not applicable
to this macroinstruction.
Syntax
(1)
>>-+---------+--APPCCMD-- --CONTROL--=--OPRCNTL--,--QUALIFY--=--DISPLAY------>
'-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--=--+-define/display_session_limits_structure_address_field----------+-----'
'-(--define/display_session_limits_structure_address_register--)-'
>--+--------------------------------------------------------------------------------------+-->
| (3) |
'-,--AREALEN--=--+-define/display_session_limits_structure_length----------------+-----'
'-(--define/display_session_limits_structure_length_register--)-'
>--+---------------------------+-------------------------------->
| (3) |
'-,--BRANCH--=--+-NO--+-----'
'-YES-'
>--+-------------------------------------------------------------+-->
| (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) |
'-,--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.
- AREA=define/display_session_limits_structure_address_field
- AREA=(define/display_session_limits_structure_address_register)
- Specifies
the address of a data area for the DEFINE/DISPLAY session limits data
structure (Refer to z/OS Communications Server: SNA Programmer's
LU 6.2 Guide for a description of this control block.).
This field is labeled RPLAREA in the RPL.
- AREALEN=define/display_session_limits_structure_length
- AREALEN=(define/display_session_limits_structure_length_register)
- Specifies
the length of the area in which the DEFINE/DISPLAY session limits
data structure is to be returned. If a mode name is specified for
the LOGMODE field, the application program must supply an area large
enough to contain the entire session limits data structure. If LOGMODE=0
is specified, a length of 40 can be coded for this field. 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.
- 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 allocated 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 to which the requested
session information applies. The LU name is a name that is valid as
the LU name value on the APPCCMD CONTROL=ALLOC macroinstruction and
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 it on the right with blanks. This
field is labeled RPL6LU in the RPL extension.
- NETID=8-byte_network_identifier
- Specifies
the network identifier of the partner application program to which
the requested session information applies.
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.)
The network identifier also is used to find and update the contents
of the logon mode table. It is the same as the NETID value on the
APPCCMD CONTROL=ALLOC macroinstruction.
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.
- USERFLD=4_bytes_of_user_data
- USERFLD=(user_data_register)
- Specifies
4 bytes of information that the application program can associate
with this operator control request. The information is returned unchanged
when the macroinstruction completes. This data cannot be used by any
conversations. It can be used for correlation purposes. 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:
- 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.
- 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 program the actual length
of the session limits structure being returned by the AREA field.
If the application program specified LOGMODE=0, the value 40 is returned
for this field. This field is labeled RPLRLEN in the RPL.
A description
of the session limits structure is found in the z/OS Communications Server: SNA Programmer's
LU 6.2 Guide.
- 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
- Returns any
unchanged user data that the application program placed in this field.
This field is labeled RPL6USR in the RPL extension.
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')
- Partner's application capabilities vector (X'1A')
Return codes
The following (RCPRI, RCSEC)
combinations can be returned to the application program when it issues
this APPCCMD. 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'0010' |
PARAMETER_ERROR—INVALID_DATA_ADDRESS_OR_ LENGTH |
| X'002C' |
X'0013' |
PARAMETER_ERROR—NO_CORRESPONDING_MODE_IN_ LOGMODE_TABLE |
| X'002C' |
X'0016' |
PARAMETER_ERROR—NO_CORRESPONDING_LU_IN_ LOGMODE_TABLE |
| X'002C' |
X'001F' |
PARAMETER_ERROR—APPCCMD_ISSUED_FOR_ NON-APPC |
| X'002C' |
X'002B' |
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'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'0006' |
NAME_RESOLUTION_ERROR—LUNAME_FOUND_IN_ UNUSABLE_NAME_ENTRY |
| X'00B0' |
X'0008' |
NAME_RESOLUTION_ERROR—LU_NAME_FOUND_ IN_A_DISASSOCIATED_NAME_ENTRY |
z/OS Communications Server: SNA Programmer's LU 6.2 Reference
Copyright IBM Corporation 1990, 2014