z/OS MVS Programming: Assembler Services Reference ABE-HSP
Previous topic | Next topic | Contents | Contact z/OS | Library | PDF


Description

z/OS MVS Programming: Assembler Services Reference ABE-HSP
SA23-1369-00

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.

Performance implications

None.

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.

ABEND codes

077

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

Go to the previous page Go to the next page




Copyright IBM Corporation 1990, 2014