There are six reserved console names. Do not use any of the following as console names:

• HC
• LOGON
• LOGOFF
• OPERLOG
• SYSLOG
• UNKNOWN

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

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