CONVCON — Retrieve console information

Description

IBM® suggests using the CnzConv service to retrieve console information. As of z/OS® V1R8 and later releases, the CONVCON service will no longer be enhanced. Future enhancement will be provided only on the CnzConv service. For more information about the CnzConv macro, see CnzConv -- Convert console name and ID.

Application programmers can retrieve information about MCS, SMCS, or extended MCS consoles by using the CONVCON macro.

You can use CONVCON to:

Determine the name of a console when you specify the ID
Determine the ID of a console when you specify the name
Validate a console name or console ID
Validate that a console area ID is syntactically correct
Check if a console is active.

You must initialize a parameter list as input. See z/OS MVS Data Areas in z/OS Internet Library at http://www.ibm.com/systems/z/os/zos/bkserv/ for a map of the CONVCON parameter list, called CONV, which is mapped by IEZVG200. See z/OS MVS Programming: Assembler Services Guide to determine which fields to initialize.

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:	24- or 31-bit
ASC mode:	Primary
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 CONVCON, do the following:

Include the IEZVG200 mapping macro in your program.
Obtain storage for the CONVCON parameter list. CONVGLEN in IEZVG200 contains the length of the parameter list. The parameter list can be in any type of storage.
Clear the entire parameter list by setting it to zeros. If you reuse it, clear it before each reuse.
Initialize fields in the parameter list mapped by macro IEZVG200. Depending on the task for which you are invoking CONVCON, you need to initialize a combination of different fields.
You must initialize the following fields no matter what task you perform:
CONVACRO

The CONV acronym

CONVVRSN

The current version level of the parameter list. The parameter list contains valid values in CONVRID.
The following describes the remaining parameter list fields. Depending on the task you choose, these fields are input fields, output fields, or both input and output fields. Use the information in the z/OS MVS Programming: Assembler Services Guide to determine which of these fields are input fields, and which are output fields.
CONVFLGS

A 1-byte flag field that indicates whether you are supplying the console name in CONVFLD (flag CONVPFLD) or the console ID (flag CONVPID) in CONVID. Set only the first bit on to indicate the console name; set only the second bit on to indicate the console ID.

CONVFLD
A 10-byte field containing the console name or console name with the area ID. The installation defines console names at initialization time in the CONSOLxx member of Parmlib. You can use the DISPLAY command to receive a list of defined names. Console area IDs can be only one character, A through K or Z. If you specify a console with an area ID, separate the name and area ID by a hyphen, left-justify it, and pad it to the right with blanks. Examples of valid console names with area IDs are:
- DATA-a
- DATADATA-a
Examples of incorrect names with area IDs and the reasons are:
DATA-abc - has an area ID with more than one character

DATA a - has a blank instead of a hyphen between the console name and the area ID
CONVAREA

A one-character input field containing a console area ID. Valid IDs are 'A' - 'K' and 'Z', and are only validated for MCS or SMCS consoles.

CONVRSN

A reason code explaining return codes 0, 4, or 8.

CONVNAME

An 8-byte field containing the console name received as output when you specify the console ID as input. The console name can be up to eight characters. If the name has fewer than eight characters, the name is left-justified and padded to the right with blanks.

CONVID

A 4-byte console ID. If you specified the name of the console in CONVFLD, on return, CONVID contains the ID of the same console. If you specify the ID of the console in CONVID, CONVCON will return the name of the console in CONVNAME. The system assigns console IDs.

CONVGFLG
Set flag CONVNPAR on in this field only if you want CONVCON to omit any area ID processing. If you do set the flag on, CONVCON:
- Ignores an area ID in CONVAREA
- Assumes the entire field is a console name, and issues return code X'08' if you included an area ID.
CONVSYSN

If the console name or ID that you specified is active, CONVCON places the name of the system to which the console is attached in CONVSYSN. If the console is not active, this field contains blanks.

CONVSMCS

Output flag that indicates that the console specified is an SMCS console.

Programming considerations

The CONVID 4-byte console id field can be used to determine if a console is extended MCS or MCS/SMCS. The first byte, mapped by CONVCLAS, is non-zero for an EMCS console. The first byte is zero for MCS and SMCS consoles. The CONVSMCS bit can be used to determine if a console is an SMCS console. This bit will always be on for SMCS consoles, and will be off for other types of consoles.

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 CONVCON, 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: Address of the CONV parameter list
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 CONVCON macro is written as follows:

Syntax	Description

`name`	`name`: Symbol. Begin `name` in column 1.

␢	One or more blanks must precede CONVCON.

CONVCON

␢	One or more blanks must follow CONVCON.

`register`	`register:` General purpose register (2) - (12).
`list name`	`list name:` RX-type address.
`,RTNCODE=ReturnCode`	`ReturnCode:` RX-type address or register (2)-(12).
`,RSNCODE=ReasonCode`	`ReasonCode:` RX-type address or register (2)-(12).

Parameters

The parameters are explained as follows:

register
list name: Contains the address (register) or the name (list name) of the CONV parameter list.

ABEND codes

077

Return and reason codes

When the CONVCON macro returns control to your program, the following table documents the possible return and reason codes. You can use the RTNCODE= and the RSNCODE= parameter on the CONVCON macro to save the return code and reason code into a variable or register. The return code is available in Register 15 and the reason code is available in Register 0 and CONVRSN when the CONVCON macro returns. Here are the possible return and reason codes:

Hexadecimal Return Code	Hexadecimal Reason Code	Meaning and Action
00	00	Meaning: The input console is active and the area ID (if specified) is syntactically valid. Action: None.
00	0C	Meaning: Program error. The input console is active and the area ID specified is not syntactically valid. Action: Correct the area ID specification. The area ID must be a letter between A-K or Z.
00	10	Meaning: Program error. The input console is active and the area ID was either not specified after the dash or additional non-blank characters were specified after the area ID in CONVFLD. Action: Correct the area ID specification. The area ID must be a letter between A-K or Z.
04	00	Meaning: Environmental error. The input console is inactive and the area ID (if specified) is syntactically valid. Action: Messages cannot be sent to this console. You must direct messages elsewhere.
04	0C	Meaning: Program error. The input console is inactive and the area ID specified is not syntactically valid. Action: Messages cannot be sent to this console. You must direct messages elsewhere. Correct the area ID specification. The area ID must be a letter between A-K or Z.
04	10	Meaning: Program error. The console is not active, but the requested console information was obtained. The specified area ID does not comply with syntax requirements. The area ID must be in the range between A-K, or Z. Action: Messages cannot be sent to this console. You must direct messages elsewhere. Correct the area ID specification. The area ID must be a letter between A-K or Z.
08	00	Meaning: Program error. The console name specified is not valid, for one of the following reasons: No console with the specified name exists. You specified an area ID with the console name, but you also set flag CONVNPAR in the CONVGFLG field in the CONV parameter list. You specified a console name with more than 8 characters. Action: Take the action number corresponding to the meaning number. Change the console name to one that is defined in the sysplex. Remove the area ID after the console name, or turn off the CONVNPAR in the CONV parameter list. Correct the console name.
08	08	Meaning: Program error. The console name specified contains invalid syntax. Action: Correct the syntax of the console name and resubmit the request.
08	0C	Meaning: Program error. You specified a reserved console name. Action: Correct the problem and resubmit the request.
0C	N/A	Meaning: Program error. You specified an incorrect console ID on input. Action: Specify a valid 4-byte console ID. Correct the problem and resubmit the request.
10	N/A	Meaning: Environmental error. The CONVCON service is not available. Action: Resubmit the request at a later time.
14	N/A	Meaning: System error. This return code is for IBM diagnostic purposes only. Action: Record the return code and supply it to the appropriate IBM support personnel.
18	N/A	Meaning: Program error. CONVCON processing completed unsuccessfully. You did not specify whether a console name or a console ID was being supplied as input. Action: Ensure that exactly one of the console input flags in field CONVFLGS is set and resubmit the request.
1C	N/A	Meaning: Program error. CONVCON processing completed unsuccessfully. You specified both the console name and console ID values in CONVFLGS. Action: Ensure that only one of the console input flags in field CONVFLGS is set and resubmit the request.
20	N/A	Meaning: Program error. CONVCON processing completed unsuccessfully. The CONV acronym was missing in the CONV parameter list. Action: Ensure that you are correctly referencing the parameter list when issuing CONVCON, and that the parameter list is correct. Resubmit the request.
24	N/A	Meaning: Program error. CONVCON was called while holding a lock. Action: Correct the program to invoke CONVCON while no locks are held.
28	N/A	Meaning: The CONVCON service was invoked in an incorrect environment. Action: Invoke the CONVCON service in the correct environment.

Example

A typical application of CONVCON 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. The example below has been coded with the following in mind:

If CONVCON indicated the console is active and you want to send the message only to that active console, add the necessary code at the CONTINUE label to send the message only to the active console.
If CONVCON indicated the console was inactive and you want to route this message to a different 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).
That you are not reusing your CONV parameter list. If you need to issue subsequent CONVCON request in other areas of the code, you must clear the CONV parameter list and initialize it to perform the subsequent query.

CALLCONV CSECT
ZERO     EQU 0
REG2     EQU 2
REG4     EQU 4
REG12    EQU 12
REG13    EQU 13
REG14    EQU 14
REG15    EQU 15
RCINACT  EQU 4
* THIS EXAMPLE CALLS CONVCON TO DETERMINE THE STATUS OF
* A CONSOLE
         STM   REG14,REG12,12(REG13)    SAVE REGISTERS OF CALLER
         BASR  REG12,0                  ESTABLISH BASE REGISTER
         USING *,REG12                  GET MODULE ADDRESSABILITY
         LA    REG2,CONVGLEN            AMOUNT OF STORAGE TO GET
         STORAGE OBTAIN,LENGTH=(REG2),ADDR=(REG4)
         USING CONV,REG4                GET ADDRESSABILITY TO CONV
         XC    0(CONVGLEN,REG4),0(REG4) CLEAR PARAMETER LIST
         MVC   CONVACRO,ACNMCONV        PUT ACRONYM INTO PARAMETER LIST
         MVI   CONVVRSN,CONVRID         PUT VERSION INTO PARAMETER LIST
         OI    CONVFLGS,CONVPFLD        TURN ON CONSOLE NAME FLAG
         MVC   CONVFLD,CONSNAME         PUT CONSOLE NAME IN PARAMETER  X
                                        LIST
         CONVCON (REG4)                 CALL CONVCON
         LTR   REG15,REG15              IS THE CONSOLE ACTIVE?
         BZ    CONTINUE                 YES, GOTO CONTINUE
         CHI   REG15,RCINACT            IS THE CONSOLE INACTIVE?
         BE    NOTACTIVE                YES, GOTO NOTACTIVE
         B     EXIT                     END PROCESSING
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.                            * 
*********************************************************************** 
EXIT EQU *
         STORAGE RELEASE,LENGTH=CONVGLEN,ADDR=(REG4)
         DROP  REG4                     DROP ADDRESSABILITY TO CONV
         LM    REG14,REG12,12(REG13)    RESTORE REGISTERS OF CALLER
         BR    REG14                    RETURN TO CALLER

ACNMCONV DC    C'CONV'                  CONVCON ACRONYM
CONSNAME DC    C'CONSOLE1'              CONSOLE NAME WITH AN AREA
         IEZVG200                       CONVCON PARAMETER LIST
         END