Application programmers can retrieve information about an input
console name or console ID using the CnzConv macro.
You can use the CnzConv service to obtain the following information: - The console name associated with an input console ID.
- The console ID associated with an input console name.
- The console status (active or inactive).
- The console type (MCS, SMCS, Subsystem, EMCS, or Special).
- The console subtype:
- HMCS is a valid subtype for a console type of MCS.
- SYSCON is a valid subtype for a console type of EMCS.
- Internal, Instream, Unknown, and JES3 are valid subtypes for a
console type of Special.
- The system name where a console is active.
- The logic unit name of an SMCS console.
- The subsystem owner name of a subsystem console.
- The subsystem ASID of a subsystem console.
Environment
The requirements for the caller are:
Environmental factor |
Requirement |
---|
Minimum authorization: |
Problem state and any PSW key |
Dispatchable unit mode: |
Task |
Cross memory mode: |
Any PASN, any HASN, any SASN |
AMODE: |
31- or 64-bit |
ASC mode: |
Primary or access register (AR) |
Interrupt status: |
Enabled for I/O and external interrupts |
Locks: |
No locks held |
Control parameters: |
Must be in the primary address space. |
Programming requirements
Before issuing CnzConv, take the following actions: - If in access register ASC mode, specify SYSSTATE ASCENV=AR before
invoking this macro.
- If in access register ASC mode, the ALET associated with the CnzConv
parameter list must be zero.
- If in AMODE 64, specify SYSSTATE AMODE64=YES before invoking this
macro.
- If a list and execute form of CnzConv is being used, clear the
list form of the parameter list before each use.
Programming considerations
Make sure you have all the information necessary to process the
results of your CnzConv query. For example, SUBSYSASID will only
be returned for an active subsystem console. As a result on your
CnzConv query, you should request the CONSOLESTATUS, CONSOLETYPE,
and SUBSYSASID at a minimum. Then after verifying the console status
is active and the console type is subsystem, it can be concluded that
the SUBSYSASID has been returned.
Restrictions
There are six reserved console names. Do not use any of the following
as console names: - HC
- LOGON
- LOGOFF
- OPERLOG
- SYSLOG
- UNKNOWN
Input register information
Before issuing the CnzConv macro, the caller does not have to place
any information into any register unless using it in register notation
for a particular parameter, or using it as a base register.
Output register information
When control returns to the caller, the general purpose registers
(GPRs) contain: - Register
- Contents
- 0
- Reason code
- 1
- Used as a work register by the system
- 2-13
- Unchanged
- 14
- Used as a work register by the system
- 15
- Return code
When control returns to the caller, the access registers (ARs)
contain: - Register
- Contents
- 0-1
- Used as work registers by the system
- 2-13
- Unchanged
- 14-15
- Used as work registers by the system
Some callers depend on register contents remaining the same before
and after issuing a service. If the system changes the contents of
registers on which the caller depends, the caller must save them before
issuing the service, and restore them after the system returns control.
Syntax
The CnzConv macro is written as follows:
Syntax |
Description |
---|
|
|
name |
name: Symbol. Begin name in
column 1. |
|
|
␢ |
One or more blanks must precede CnzConv. |
|
|
CnzConv |
|
|
|
␢ |
One or more blanks must follow CnzConv. |
|
|
InConsoleName =InConsoleName Addr |
InConsoleName Addr: RX-type
address or register (2) - (12). |
InConsoleId =InConsoleId Addr |
InConsoleId Addr: RX-type address
or register (2) - (12). |
|
|
,OutConsoleId =OutConsoleId Addr |
OutConsoleId Addr: RX-type
address or register (2) - (12). |
|
|
,OutConsoleName =OutConsoleName
Addr |
OutConsoleName Addr: RX-type
address or register (2) - (12). |
|
|
,ConsoleStatus =ConsoleStatus Addr |
ConsoleStatus Addr: RX-type
address or register (2) - (12). |
|
|
,ConsoleType =ConsoleType Addr |
ConsoleType Addr: RX-type
address or register (2) - (12). |
|
|
,ConsoleSubType =ConsoleSubType
Addr |
ConsoleSubType Addr: RX-type
address or register (2) - (12). |
|
|
,Sysname =Sysname Addr |
Sysname Addr: RX-type address
or register (2) - (12). |
|
|
,SMCS_LU =SMCS_LU Addr |
SMCS_LU Addr: RX-type address
or register (2) - (12). |
|
|
,SubsysOwnerName =SubsysOwnerName
Addr |
SubsysOwnerName Addr: RX-type
address or register (2) - (12). |
|
|
,SubsysASID =SubsysASID Addr
|
SubSysASID Addr: RX-type
address or register (2) - (12). |
|
|
,RtnCode =RtnCode Addr |
RtnCode Addr: RX-type address
or register (2)-(12). |
|
|
,RsnCode =RsnCode Addr |
RsnCode Addr: RX-type address
or register (2)-(12). |
|
|
Parameters
The parameters are explained as follows:
- InConsoleName
- Belongs to a set of mutually exclusive keys. It is the name (RS-type),
or address in register (2)-(12), of an 8 character input that is the
input console name to query.
- InConsoleId
- Belongs to a set of mutually exclusive keys. It is the name (RS-type),
or address in register (2)-(12), of a fullword input that is the input
console ID to query.
- OutConsoleId
- Is the name (RS-type), or address in register (2)-(12), of an
optional fullword output that contains the console ID of the requested
console when the query completes successfully. When the query does
not complete successfully, OutConsoleId will contain binary zeros.
- OutConsoleName
- Is the name (RS-type), or address in register (2)-(12), of an
optional 8 character output that contains the console name of
the requested console when the query completes successfully. When
the query does not complete successfully, OutConsoleName will contain
binary zeros.
- ConsoleStatus
- Is the name (RS-type), or address in register (2)-(12), of an
optional byte output that contains the status of the requested
console when the query completes successfully. When the query does
not complete successfully, ConsoleStatus will contain binary zeros
which means not applicable. A console status will be returned for
a console type of MCS, SMCS, Subsys, or EMCS. A console status of
binary zeros, which means not applicable, will be returned for a console
type of Special. The console statuses are: active, inactive. The constants
for the console statuses are defined in macro IEZVG200.
- ConsoleType
- Is the name (RS-type), or address in register (2)-(12), of an
optional byte output that contains the type of the requested console
when the query completes successfully. When the query does not complete
successfully, ConsoleType will contain binary zeros. Any query that
completes successfully will have a console type set. The console types
are: MCS, SMCS, Subsys, EMCS, Special. The constants for the console
types are defined in macro IEZVG200.
- ConsoleSubType
- Is the name (RS-type), or address in register (2)-(12), of an
optional byte output that contains the subtype of the requested console
when the query completes successfully. When the query does not complete
successfully, or completes successfully, but the requested console
does not have a console subtype, ConsoleSubtype will contain binary
zeros which means not applicable. Console subtypes
are only returned for the console types of MCS, EMCS, and Special.
HMCS is a valid subtype for the console type of MCS. SYSCON is a valid
subtype for the console type of EMCS. Internal, Instream, Unknown,
and JES3 are valid subtypes for the console type of Special. The
constants for the console subtypes are defined in macro IEZVG200.
- Sysname
- Is the name (RS-type), or address in register (2)-(12), of an
optional 8 character output that contains the system name where the requested
console is active when it has a console status of active, and a console
type of MCS, SMCS, Subsys, or EMCS, and the query completes successfully.
When the console status is not active, or the console type is Special,
or the query does not complete successfully, Sysname will contain
binary zeros.
- SMCS_LU
- Is the name (RS-type), or address in register (2)-(12), of an
optional 8 character output that contains the LU name of the requested
console when it has a console type of SMCS and the query completes
successfully. When the console type is not SMCS or the query does
not complete successfully, SMCS_LU will contain binary zeros.
- SubsysOwnerName
- Is the name (RS-type), or address in register (2)-(12), of an
optional 8 character output that contains the subsystem owner name of
the requested console when it has a console type of Subsys, and a
console status of active, and the query completes successfully. When
the console type is not Subsys, or the console status is not active,
or the query does not complete successfully, SubsysOwnerName will
contain binary zeros.
- SubsysASID
- Is the name (RS-type), or address in register (2)-(12), of an
optional halfword output that contains the ASID of the requested
console when it has a console type of Subsys, and a console status
of active, and the query completes successfully. When the console
type is not Subsys, or the console status is not active, or the query
does not complete successfully, SubsysASID will contain binary zeros.
- RtnCode
- Is the name (RS-type) of an optional fullword output variable,
or register (2)-(12), into which the return code is to be copied from
GPR 15.
- RsnCode
- Is the name (RS-type) of an optional fullword output variable,
or register (2)-(12), into which the reason code is to be copied from
GPR 0.
Return and reason codes
When the CnzConv macro returns control to your program, if any
return code is specified, it will be copied from Register 15 into
RtnCode, if any reason code is specified, it will be copied from Register
0 into RsnCode. The following table shows the meanings and actions
for the hexadecimal return codes and reason codes:
Return Code |
Reason Code |
Meaning and Action |
---|
0 |
N/A |
Name: CnzConvRc0_Ok
Meaning:
The input console name or ID was found and the applicable requested
data was returned.
Action: None.
|
4 |
xxxxxxxx |
Name: CnzConvRc4_ConditionallyOK
Meaning: The request completed successfully with an
exception.
Action: Examine the reason code to determine
how to proceed.
|
4 |
xxxx0401 |
Name: CnzConvRsn401_IdNotFound
Meaning: The console ID in InConsoleId is not associated
with any console.
Action: Correct the console ID in
InConsoleId to be the ID of a defined console or take appropriate
action when the console ID in InConsoleId was not found.
|
4 |
xxxx0402 |
Name: CnzConvRsn402_NameNotFound
Meaning: The console name in InConsoleName is not
associated with any console.
Action: Correct the console
name in InConsoleName to be the name of a defined console or take
appropriate action when the console name in InConsoleName was not
found.
|
4 |
xxxx0403 |
Name: CnzConvRsn403_NameIsReserved
Meaning:
The input console name is a reserved console name.
Action:
Correct the console name in InConsoleName to be the name of a defined
console or take appropriate action when the console name in InConsoleName
is reserved.
|
8 |
xxxxxxxx |
Name: CnzConvRc8_SpecificationError
Meaning:
An error was detected in the CnzConv parameter list. None of the
requested data has been returned.
Action: Correct the
CnzConv parameter list. Examine the reason code to determine how to
proceed.
|
8 |
xxxx0801 |
Name: CnzConvRsn801_BadPlistVer
Meaning:
The PLISTVER in the CnzConv parameter list is incorrect.
Action:
Correct the PLISTVER in the CnzConv parameter list.
|
8 |
xxxx0802 |
Name: CnzConvRsn802_ExtraneousInput
Meaning:
InConsoleName and InConsoleId are mutually exclusive keywords but
both were specified.
Action: Specify one and only one
of the following keywords: InConsoleName or InConsoleId.
|
8 |
xxxx0803 |
Name: CnzConvRsn803_IncompleteArgs
Meaning:
Neither InConsoleName nor InConsoleId keyword was specified.
Action: Specify one and only one of the following keywords:
InConsoleName or InConsoleId.
|
8 |
xxxx0804 |
Name: CnzConvRsn804_NameInvalidSyntax
Meaning:
The console name in InConsoleName is syntactically invalid and cannot
be a console name.
Action: Correct the input console
name.
|
8 |
xxxx0805 |
Name: CnzConvRsn805_RsvSpaceNotZero
Meaning:
The reserved space in the CnzConv parameter list is not binary zeros.
Action:
Correct the CnzConv parameter list so that the reserved space contains
binary zeros.
|
C |
xxxxxxxx |
Name: CnzConvRcC_Error
Meaning:
The request failed to complete successfully. None of the requested
data has been returned.
Action: Examine the reason
code to determine how to proceed.
|
C |
xxxx0C01 |
Name: CnzConvRsnC01_NotAvailable
Meaning:
The CnzConv service is not available at this time,. This typically
would not occur after system initialization.
Action:
Resubmit your request at a later time.
|
C |
xxxx0C02 |
Name: CnzConvRsnC02_IncorrectEnv
Meaning:
The CnzConv service was invoked in an incorrect environment.
Action:
Invoke the CnzConv service in the correct environment.
|
10 |
xxxxxxxx |
Name: CnzConvRc10_UnexpectedError
Meaning:
Unexpected failure occurred. The outcome of the request is unpredictable,
meaning that it might have completed successfully, or partially, or
not at all. All, some, or none of the data requested has been returned.
A dump might have been taken.
Action: Examine the reason
code to determine how to proceed.
|
10 |
xxxx1001 |
Name: CnzConvRsn1001_SevereError
Meaning:
The CnzConv service was unable to complete your request due to an
unexpected error processing the CnzConv request.
Action:
Supply the return code, reason code, and the dump to the appropriate IBM®
support personnel.
|
Example
A typical application of CnzConv would be in an MPF message exit.
A message exit could be built to reroute a message to an active console
in your system or sysplex. As shown in the following example, you
can change the routing information or the message destination depending
on the status of the console: - If CnzConv indicates the console is active and you want to send
the message only to that active console, add the necessary code at
the CONTINUE label.
- If CnzConv indicates the console is inactive and you want to route
this message to an active console, add the necessary code to the NOTACTIVE
label.
.
This example assumes that you would have function specified at
the labels referenced as locations of branch instructions (block comments
are also in the example showing where these would be). NZCONVEX CSECT
NZCONVEX AMODE 31
NZCONVEX RMODE ANY
***********************************************************************
* *
* REGISTER ASSIGNMENTS *
* *
***********************************************************************
REG0 EQU 0 REGISTER 0
REG1 EQU 1 REGISTER 1
REG2 EQU 2 REGISTER 2
REG3 EQU 3 REGISTER 3
REG4 EQU 4 REGISTER 4
REG5 EQU 5 REGISTER 5
REG6 EQU 6 REGISTER 6
REG7 EQU 7 REGISTER 7
REG8 EQU 8 REGISTER 8
REG9 EQU 9 REGISTER 9
REG10 EQU 10 REGISTER 10
REG11 EQU 11 REGISTER 11 - DYNAMIC DATA AREA
REG12 EQU 12 REGISTER 12
REG13 EQU 13 REGISTER 13
REG14 EQU 14 REGISTER 14
REG15 EQU 15 REGISTER 15
SPACE 1
***********************************************************************
* *
* STANDARD ENTRY LINKAGE *
* *
***********************************************************************
BAKR REG14,0 SAVE REGS
BALR REG12,0 BASE REG
USING *,REG12 ADDRESSABILITY
MODID ,
***********************************************************************
*
* OBTAIN DYNAMIC AREA STORAGE.
*
***********************************************************************
SPACE 1
LA REG0,DYNL LENGTH OF DATA AREAS
GETMAIN RU,LV=(REG0),SP=0 OBTAIN DYNAMIC STORAGE
LR REG11,REG1 ADDRESS RETURNED IN REG1
USING DYNMODEL,REG11 ADDRESSABILITY TO DYNAMIC
XC MYCNZCONV,MYCNZCONV CLEAR CNZCONV PARMLIST
***********************************************************************
*
* INVOKE CNZCONV FOR A CONSOLE NAME.
*
***********************************************************************
CNZCONV INCONSOLENAME=MYCONSOLENAME, X
OUTCONSOLEID=OUTCONSOLEID, X
OUTCONSOLENAME=OUTCONSOLENAME, X
CONSOLESTATUS=OUTCONSOLESTATUS, X
CONSOLETYPE=OUTCONSOLETYPE, X
CONSOLESUBTYPE=OUTCONSOLESUBTYPE, X
SYSNAME=OUTSYSNAME, X
SMCS_LU=OUTSMCS_LU, X
SUBSYSOWNERNAME=OUTSUBSYSOWNERNAME, X
SUBSYSASID=OUTSUBSYSASID, X
RTNCODE=CNZCONVRETURNCODE, X
RSNCODE=CNZCONVREASONCODE, X
MF=(E,MYCNZCONV)
CLI CNZCONVRETURNCODE,CNZCONVRC0_OK X
Was the query successful?
BNZ FINISHED No, free storage and return
CLI OUTCONSOLESTATUS,CNZCONV_KSTATUS_INACTIVE X
Was the console inactive?
BE NOTACTIVE Yes, handle not active
CLI OUTCONSOLESTATUS,CNZCONV_KSTATUS_ACTIVE X
Was the console active?
BE CONTINUE
B FINISHED Undefined status, free storage X
and return
CONTINUE EQU *
***********************************************************************
* HERE YOU WOULD PROVIDE SUPPORT FOR THE ACTIONS YOU WANTED *
* TO TAKE IF THE CONSOLE WAS ACTIVE. *
***********************************************************************
NOTACTIVE EQU *
***********************************************************************
* HERE YOU WOULD PROVIDE SUPPORT FOR THE ACTIONS YOU WANTED
* TO TAKE IF THE CONSOLE WAS INACTIVE.
***********************************************************************
FINISHED EQU *
FREEMAIN RU,LV=DYNL,A=(REG11),SP=0
PR
MYCONSOLENAME DC C'MCSY13E0 ' CONSOLE NAME
*---------------------------------------------------------------------*
*- DYNAMIC AREA that contains the data returned by CnzConv macro -*
*- plus the CnzConv parameter list -*
*---------------------------------------------------------------------*
DYNMODEL DSECT
DS 0F
OUTCONSOLEID DS F
OUTCONSOLENAME DS CL8
OUTCONSOLESTATUS DS CL1
OUTCONSOLETYPE DS CL1
OUTCONSOLESUBTYPE DS CL1
RSV000001 DS CL1
OUTSYSNAME DS CL8
OUTSMCS_LU DS CL8
OUTSUBSYSOWNERNAME DS CL8
OUTSUBSYSASID DS H
CNZCONVRETURNCODE DS F
CNZCONVREASONCODE DS F
CNZCONV MF=(L,MYCNZCONV) CNZCONV PARAMETER LIST
ORG
DYNL EQU *-DYNMODEL DYNAMIC AREA LENGTH
EJECT
IEZVG200 CNZCONV CONSTANTS
EJECT
END
|