SYSSTATE — Identify system state

Description

Use the SYSSTATE macro to generate code that is correct for the environment in which the program will run. Some macros need to know one or more of the following characteristics about that environment:
  • The addressing mode (AMODE) at the time the macro is issued
  • The ASC mode of the program at the time the macro is issued
  • The architectural level in which the program will run at the time the macro is issued
  • The earliest release level that the program will run on at the time the macro is issued
For those macros that are sensitive to their environment, SYSSTATE identifies the environment. During the assembly stage, SYSSTATE sets one or more of the following:
  • Global character symbol &SYSAM64, to identify the AMODE
  • Global character symbol &SYSASCE, to identify the ASC mode
  • Global arithmetic symbol &SYSALVL, to identify the Architectural level
  • Global character symbols &SYSOSREL and &SYSOSREL_NAME, to identify the release level
Later, when the program is assembled, the macros check the global symbol(s) and generate the correct code.
IBM recommends that you issue the SYSSTATE macro before issuing other macros. Once a program has issued SYSSTATE, there is no need to reissue it unless the program switches from one ASC mode to another, or from one AMODE to another, or has code paths that are isolated according to architecture level or z/OS® release. If you switch AMODE or ASC mode or to a different architecture code path or a different z/OS release code path, you should issue SYSSTATE immediately after the switch to indicate the new state. Without this information, the system assumes the macro is issued:
  • In AMODE other than 64-bit
  • In primary ASC mode
  • In ESA/390 architectural level
  • Prior to z/OS V1R6
Also, it is recommended that:
  • If you know that your program will run on or after a particular release of z/OS, use SYSSTATE with the OSREL parameter.
  • If you know that your program will run on or after the release of z/OS that provided the SYSSTATE macro with which you are assembling, use SYSSTATE with OSREL=SYSSTATE.
  • When using SYSSTATE with OSREL, use SYSSTATE ARCHLVL=OSREL, as that will set the ARCHLVL accordingly.
Another way to use the SYSSTATE macro is within a macro you write yourself. For example, you can issue SYSSTATE with the TEST parameter to ensure that the &SYSASCE global symbol has been set:
  1. Define the &SYSASCE global symbol within your macro.
  2. Issue SYSSTATE TEST, which sets &SYSASCE to the default if it has not yet been set.
  3. Define different logical paths within your macro to correspond to the ASC mode that is in effect based on the value of &SYSASCE.

A program need use SYSSTATE TEST only when it wants to query the value of one of the variables. When setting variables (i.e., not SYSSTATE TEST), you can specify one or more of the parameters available. The variables associated with not-specified variables remain unchanged.

Environment

The requirements for the caller are:

Environmental factor Requirement
Minimum authorization: Problem state, and any PSW key.
Dispatchable unit mode: Task or SRB
Cross memory mode: Any PASN, any HASN, any SASN
AMODE: 24- or 31- or 64-bit
ASC mode: Primary or AR
Interrupt status: Enabled or disabled for I/O and external interrupts
Locks: The caller may hold locks, but is not required to hold any.
Control parameters: None.
   

Programming requirements

None.

Restrictions

None.

Input register information

Before issuing the SYSSTATE 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 the following information:
Register
Contents
0-15
Unchanged
When control returns to the caller, the access registers (ARs) contain:
Register
Contents
0-15
Unchanged

Performance implications

None.

Syntax

The SYSSTATE macro is written as follows:

Syntax Description
   
   name name: Symbol. Begin name in column 1.
   
␣ One or more blanks must precede SYSSTATE.
   
SYSSTATE  
   
␣ One or more blanks must follow SYSSTATE.
   
  TEST  
   
  ASCENV=P Default: ASCENV=P
  ASCENV=AR  
   
  AMODE64=NO Default: AMODE64=NO
  AMODE64=YES  
   
  ARCHLVL=0 Default: ARCHLVL=0
  ARCHLVL=1  
  ARCHLVL=2  
  ARCHLVL=3  
  ARCHLVL=4  
  ARCHLVL=5  
  ARCHLVL=6  
  ARCHLVL=OSREL  
   
  OSREL=osrel  
   
  PUSH  
  POP  
   

Parameters

The parameters are explained as follows:

TEST
TEST checks each one of the global symbols &SYSASCE, &SYSAM64, and &SYSALVL, and does the following for each as required:
  • Sets the global symbol to its default, if the global symbol does not contain a value indicating that it had been set by a prior SYSSTATE macro.
  • Leaves the global symbol unchanged, if the global symbol does contain a value indicating that you issued a specific SYSSTATE during this assembly.
ASCENV=P
ASCENV=AR
Indicates your program's ASC mode by setting the global symbol &SYSASCE.
  • ASCENV=P indicates that the program is in primary mode.
  • ASCENV=AR indicates that the program is in AR mode.
AMODE64=NO
AMODE64=YES
Indicates whether your program is AMODE 64 at this point. It sets the global symbol &SYSAM64.
  • AMODE64=YES should be specified for any part of your program that runs in AMODE 64. Some macros process differently according to this specification. For example, macros such as ATTACHX, CALL, LINKX, LOAD, and XCTLX build prarmeter lists consisting of 8-byte entries when SYSSTATE AMODE64=YES.
  • AMODE64=NO should be specified for programs, or parts of programs, that do not run in AMODE 64.
ARCHLVL=0
ARCHLVL=1
ARCHLVL=2
ARCHLVL=3
ARCHLVL=4
ARCHLVL=5
ARCHLVL=6
ARCHLVL=OSREL
Indicates the architectural level of the system for which the subsequent section of your program is designed by setting the global symbol &SYSALVL.
0
Means that the architecture is ESA/390. When bit CVTOS390_R10 in byte CVTOSLV2 of the CVT data area is off, your program should not assume that ARCHLVL=1 or ARCHLVL=2 capabilities are available.
1
Means that the architecture is ESA/390. When bit CVTOS390_R10 in byte CVTOSLV2 of the CVT data area is on, ARCHLVL=1 capabilities are available.
2
Means that the architecture is z/Architecture. Macros that pay attention to ARCHLVL will avoid generating z/Architecture instructions when ARCHLVL < 2 is in effect. When byte FLCARCH in the PSA data area is not zero, ARCHLVL=1 and ARCHLVL=2 capabilities are available. If you set an ARCHLVL value less than the latest, your program can still run on more recent levels of the system, but it might not take advantage of all the new functions.
3
Means that the architecture is the architecture level required by z/OS V2R1, which corresponds, roughly, to the IBM System z9 processor.
4
Means that the architecture is the architecture level required by z/OS V2R2, which corresponds, roughly, to the IBM System z10 processor.
5
Means that the architecture corresponds, roughly, to the IBM System z196 processor.
6
Means that the architecture is the architecture level required by z/OS V2R3, which corresponds, roughly, to the IBM System zEC12 processor.
OSREL
Indicates to set the ARCHLVL according to the OSREL specification using the following rules:
  • When the OSREL release is at least z/OS V2R1, set &SYSALVL to 3.
  • When the OSREL release is at least z/OS V1R6, set &SYSALVL to 2.
  • Otherwise, set &SYSALVL to 1.
When an ARCHLVL greater than 0 is in effect, be aware of the following points:
  • Macros may expect that there is addressability to the literal area of your assembly language program at the point where the macro is invoked.
  • You might still need to use the IEABRC or IEABRCX macro to have subsequent macros generate code that avoids the use of base-displacement branch instructions, since many macros are not sensitive to the value specified for SYSSTATE ARCHLVL. See z/OS MVS Programming: Assembler Services Reference IAR-XCT for details about the IEABRC and IEABRCX macros.
OSREL=osrel
Indicates the earliest operating system release that subsequent macros may assume the code is running on by setting the global symbol &SYSOSREL and &SYSOSREL_NAME. Specify osrel by specifying the release name in the form ZOSVnRm, where n is the version number and m is the release number. For example, specify OSREL=ZOSV1R6 for z/OS V1R6. For each new release, an analogous value will be added for osrel. The system also provides global character macro variables for each supported release which you can check within a macro. These macro variables are of the form &SYSOSREL_ZOSVnRm.

You can also specify OSREL=SYSSTATE, which indicates that the OSREL is to match the release of z/OS that provided the SYSSTATE macro with which you are assembling.

You can also specify OSREL=MIGLIB, which indicates that the OSREL is to match the oldest supported release of z/OS at the time that the release of z/OS that provided the SYSSTATE macro with which you are assembling became available. Modules such as IBM-provided IPCS modules in SYS1.MIGLIB might use this.

PUSH
Saves current SYSSTATE global symbol settings. You can nest PUSH/POP to a depth of 255.
POP
Restore SYSSTATE global symbol settings to the previously saved levels. You can nest PUSH/POP to a depth of 255.

ABEND codes

None.

Return and reason codes

None.

Example 1

Change to AR mode and set the global symbol. 
SAC      512
SYSSTATE ASCENV=AR

Example 2

The following example shows how you would code the SYSSTATE macro to indicate that your code was in a section that knew that it was running on z/OS V1R6 or later:
   L     15,X'10'    Get CVT address
   TM  CVTOSLV3-CVT(15),CVTZOS_V1R6
   JZ    NOT_V1R6
   SYSSTATE PUSH   save SYSSTATE values
   SYSSTATE OSREL=ZOSV1R6
   LXRES  ELXLIST=...
   SYSSTATE POP   restore SYSSTATE values
NOT_V1R6 DS 0H

Example 3

The following example shows how you would use SYSSTATE to temporarily indicate a program's ASC mode, and then change back to the prior setting. In this example, the program issues SYSSTATE PUSH to save the current mode, changes to AR mode issues SYSSTATE to indicate that the program is running in AR ASC mode, and then issues SYSSTATE POP to restore the program to whatever the prior mode was:
 SAC   512
 SYSSTATE PUSH
 SYSSTATE ASCENV=AR  
* code running in AR-mode 
 SYSSTATE POP

Example 4

The following example shows how you would code a macro to be sensitive to SYSSTATE with the OSREL parameter, in this case for release z/OS V1R6: 
          MACRO
          TESTMAC
          GBLC  &SYSOSREL
          GBLC  &SYSOSREL_ZOSV1R6          
          SYSSTATE TEST
          AIF   (&SYSOSREL GE &SYSOSREL_ZOSV1R6).GENV1R6
* produce code suitable for prior to z/OS v1 R6
          AGO   .MACEND
.GENV1R6  ANOP
* produce code suitable for z/OS v1 R6 or later       
.MACEND   ANOP
          MEND