Description

The MODESET macro is used to change system status by altering the PSW key and/or PSW problem state indicator. The MODESET macro has two forms: the form that generates inline code and the form that generates an SVC.

Parent topic: MODESET — Change system status

Inline code generation

Environment

The requirements for the caller are:

Environmental factor Requirement
Minimum authorization:
  • Problem state, with a PSW key mask that allows the program to switch to the requested PSW key, or
  • Supervisor state
Dispatchable unit mode: Task
Cross memory mode: Any PASN, any HASN, any SASN
AMODE: 24- or 31- or 64-bit
ASC mode: Primary or secondary
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

The caller must include the IKJTCB and IHARB mapping macros. If EXTKEY= TCB, RBT1, or RBT234 is specified, the home address space must be the currently addressable address space.

Restrictions

None.

Input register information

If any of the following parameters are specified: EXTKEY=TCB, EXTKEY=RBT1, or EXTKEY=RBT234, before issuing the MODESET macro, the caller must load the address of the active TCB into a register and establish addressability to that TCB. If none of the above is specified, the caller does not have to place any information into any register before issuing the MODESET macro unless using it in register notation for a particular parameter, or using it as a base register.

Output register information

All GPRs are unchanged except GPR 1 and 15, and those specified on the KEYADDR, KEYREG, SAVEKEY, and WORKREG keywords.
Register
Contents
0
Used as a work register by the system when specified on the WORKREG parameter; otherwise, unchanged.
1
Used as a work register by the system, even if you specify register 1 on the WORKREG or KEYREG parameter.
2
Used as a work register by the system when specified on the WORKREG, KEYREG, or KEYADDR parameters; otherwise, unchanged.
3-14
Used as work registers by the system when specified on the WORKREG, KEYREG, or KEYADDR parameters; otherwise, unchanged.
15
Used as a work register by the system.
When control returns to the caller, the 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 standard form of the MODESET macro that generates inline code is written as follows:

Syntax Description
   
   name name: Symbol. Begin name in column 1.
   
␢ One or more blanks must precede MODESET.
   
MODESET  
   
␢ One or more blanks must follow MODESET.
   
EXTKEY=key key: One of the following:
  1. ZERO
  2. TCB
  3. RBT1
  4. RBT234
  5. KEY2
  6. KEY3
  7. KEY4
  8. KEY7
KEYADDR=new key addr  
KEYREG=new key reg  
   
  new key addr: RX-type address or register (2).
  new key reg: Register 1-15 without parentheses; may be symbolic.
   
   ,SAVEKEY=old key addr old key addr: RX-type address or register (2).
   
 
Note:
  1. If KEYADDR=(2) is specified above, then SAVEKEY=(2) cannot be specified.
  2. If WORKREG and SAVEKEY are specified with KEYREG, the KEYREG register should be different from the WORKREG register. Also, if SAVEKEY is specified with KEYREG, the KEYREG register should not be register 2.
   
   ,WORKREG=work reg work reg: Decimal digits 0-15 without parentheses.
   
 
Note:
  1. WORKREG is required if the following are specified:
    • EXTKEY=TCB
    • EXTKEY=RBT234
    • EXTKEY=RBT1
    • KEYADDR=new key addr, unless KEYADDR=(2) is specified.
  2. The WORKREG parameter should be register 1-15 if one of these four parameters is specified because WORKREG is used as a base register on the SPKA instruction. WORKREG=0 sets the PSW key to zero.
   
   ,RELATED=value value: Any valid macro keyword specification.
   

Parameters

Note: The inline expansion of the MODESET macro does not result in a change to the caller’s PSW key mask.

The parameters are explained as follows:

EXTKEY=key
Specifies the key, or the address of the key, to be set in the current PSW.
ZERO
Set a key of zero.
TCB
Set the key of the active TCB.
RBT1
Set the key of the active RB of type 1 SVC routine issuing MODESET.
RBT234
Set the key of the active RB preceding SVRB of type 2, 3, or 4 SVC routine issuing MODESET.
KEY2
Set a key of 2.
KEY3
Set a key of 3.
KEY4
Set a key of 4.
KEY7
Set a key of 7.
KEYADDR=new key addr
Specifies a location 1 byte in length which contains the key in bit positions 0-3. If register (2) is specified, the key is contained in bit positions 24-27 (bits 28-31 are ignored). This parameter permits a previously saved key to be restored.
KEYREG=new key reg
Specifies a register that contains a key value in bit positions 24-27.
,SAVEKEY=old key addr
Specifies a location 1 byte in length where the current PSW key is to be saved, in bit positions 0-3. If register (2) is specified, the key is left in register 2.
,WORKREG=work reg
Specifies the register into which the contents of register 2 are to be saved while performing the SAVEKEY function, or the working register to be used by the EXTKEY or KEYADDR function. See Note 1 above. If WORKREG=2 is specified, no register saving takes place.
,RELATED=value
Specifies information used to self-document macros by “relating” functions or services to corresponding functions or services. The format and contents of the information specified are at the discretion of the user, and may be any valid coding values.

ABEND codes

The MODESET macro might abnormally terminate with abend code X'0C2'. See z/OS MVS System Codes for an explanation and programmer response.

Return and reason codes

None.

Example 1

Save the current PSW key, and change the key to that of the active TCB. 
MODESET EXTKEY=TCB,SAVEKEY=KEYSAVE,WORKREG=1

Example 2

Save the current key at location KEY and set the key to the value contained in bits 24-27 of register 3. 
MODESET KEYREG=REG3,SAVEKEY=KEY,WORKREG=4

SVC generation

Environment

The requirements for the caller are:

Environmental factor Requirement
Minimum authorization: One of the following:
  • - Supervisor state
  • - PSW key 0 - 7
  • - APF authorization
The program must reside in an APF–authorized library and be link–edited with authorization code AC=1.
Dispatchable unit mode: Task
Cross memory mode: PASN=HASN=SASN
AMODE: 24- or 31-bit
ASC mode: Primary
Interrupt status: Enabled or disabled for I/O and external interrupts
Locks: No locks held
Control Parameters: Must be in primary address space

Programming requirements

None.

Restrictions

None.

Input register information

Before issuing the MODESET 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 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 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 standard form of the MODESET macro that generates an SVC is written as follows:

Syntax Description
   
   name name: Symbol. Begin name in column 1.
   
␢ One or more blanks must precede MODESET.
   
MODESET  
   
␢ One or more blanks must follow MODESET.
   
KEY=ZERO
Note: KEY is required if MODE is not specified.
KEY=NZERO  
   
,MODE=PROB
Note: MODE is required if KEY is not specified.
,MODE=SUP  
   
   ,RELATED=value value: Any valid macro keyword specification.
   

Parameters

The parameters are explained as follows:

KEY=ZERO
KEY=NZERO
Specifies that the PSW key (bits 8-11) is to be either set to zero (ZERO) or set to the value in the caller's TCB (NZERO).
,MODE=PROB
,MODE=SUP
Specifies that the PSW problem state indicator (bit 15) is to be either turned on (PROB) or turned off (SUP). If the MODESET operation completes with a problem state PSW, the caller’s PSW key mask (PKM) is set according to the following rules:
  • The bit matching the resulting PSW key is set on.
  • The bit matching key 9 is set on.
  • For a task attached with ATTACHX using the KEY=NINE parameter, the bits that were on in the PKM of the ATTACHX issuer are set on.
  • All other bits are set off.
If the resulting PSW is in supervisor state, the caller’s PKM is unchanged.
,RELATED=value
Specifies information used to self-document macros by “relating” functions or services to corresponding functions or services. The format and contents of the information specified are at the discretion of the user, and may be any valid coding values.

ABEND codes

The MODESET macro might abnormally terminate with abend code X'16B'. See z/OS MVS System Codes for an explanation and programmer response.

Return and reason codes

When the MODESET macro returns control to your program, GPR 15 contains a hexadecimal return code and GPR 0 contains a hexadecimal reason code.

Table 1. Return and Reason Codes for the MODESET Macro
Return Code Reason Code Meaning and Action
00 00 Meaning: The operation was successful.

Action: None.

Example

Change to supervisor mode and key zero. 
 MODESET KEY=ZERO,MODE=SUP