Description

Description

z/OS MVS Programming: Authorized Assembler Services Reference ALE-DYN
SA23-1372-00

Use the CONFCHG macro to request notification about dynamic changes in the I/O configuration in your installation. When you invoke CONFCHG with the NOTIFY parameter, you specify whether you want to be notified about one of the following:

A requested or rejected configuration change that involves deleting a device or deleting a path to a device (CHGREQ parameter)
Note: IBM® recommends that you use the ENFREQ macro (event code 31) instead of CONFCHG.
A successful configuration change (CHGCOMPL parameter).
Note: IBM recommends that you use the ENFREQ macro (event code 32) instead of CONFCHG.

When you invoke CONFCHG with the CANCEL parameter, you specify that you no longer want to be notified of changes. You must cancel your NOTIFY request when you no longer want to receive notification.

When you invoke CONFCHG with NOTIFY, you must specify a user-written configuration change exit routine (EXIT parameter). To determine when the exit routine will receive control, you code either the CHGREQ or CHGCOMPL parameter. When an ACTIVATE command is issued, the system ensures that the devices to be deleted are off-line and unallocated. If the activate request has passed this validation step and an authorized program issues CONFCHG CHGREQ, the system passes control to the exit routine. When a requested activation change is rejected, the system also passes control to the exit routine.

If the program issues CONFCHG CHGCOMPL, the system passes control to the exit routine when a dynamic I/O configuration change completes successfully.

When the configuration change exit routine receives control, general purpose register (GPR) 1 contains the address of a parameter list. The parameter list contains information about the change that occurred, such as the specific device that is being added, modified, or deleted. See z/OS MVS Programming: Authorized Assembler Services Guide for complete information on coding the configuration change exit routine.

Environment

The requirements for the caller are:

Environmental factor	Requirement
Minimum authorization:	Supervisor state, with any PSW key
Dispatchable unit mode:	Task
Cross memory mode:	PASN=HASN=SASN
AMODE:	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

Restrictions

None.

Register information

After the caller issues the macro, the system might use some registers as work registers or might change the contents of some registers. When the system returns control to the caller, the contents of these registers are not the same as they were before the macro was issued. Therefore, if the caller depends on these registers containing the same value before and after issuing the macro, the caller must save these registers before issuing the macro and restore them after the system returns control.

When control returns to the caller, the general purpose registers (GPRs) contain:

Register: Contents
0-1: Used as work registers 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

Programming requirements

The caller of CONFCHG must ensure that the configuration change exit routine resides in common storage. Before coding CONFCHG with the EXIT parameter, the caller must set to 1 the high-order bit of the exit routine's address.

Performance implications

None.

Syntax

The standard form of the CONFCHG macro is written as follows:

Syntax	Description

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

␢	One or more blanks must precede CONFCHG

CONFCHG

␢	One or more blanks must follow CONFCHG
NOTIFY
CANCEL

,CHGREQ
,CHGCOMPL

,TOKEN=`token addr`	`token addr`: RS-type address or register (2) - (12). Required with NOTIFY only if you plan to cancel the request upon completion. Required with CANCEL.

,EXIT=`exitrtn addr`	`exitrtn addr`: RS-type address or register (2) - (12). Required only with NOTIFY. Not valid with CANCEL.

,RETCODE=`rc addr`	`rc addr`: RX-type address or register (2) - (12).

,MF=S

Parameters

The parameters are explained as follows:

NOTIFY

CANCEL

The required parameter that requests:

Notification of I/O configuration changes (NOTIFY), or
Cancellation of a previous notification request (CANCEL).

,CHGREQ

,CHGCOMPL

The required parameter that specifies whether the caller wants notification of:

Requested or rejected I/O configuration changes that involve deleting a device or deleting a path to a device (CHGREQ)
I/O configuration changes that completed successfully (CHGCOMPL).

,TOKEN=token addr

For NOTIFY, specifies a 4-character output field into which the system returns a token to identify the request. TOKEN is required with NOTIFY only if you plan to cancel your notification request when completed.

For CANCEL, specifies the 4-character token returned by NOTIFY to cancel a specific notification request. TOKEN is required with CANCEL.

,EXIT=exitrtn addr

The required parameter (for NOTIFY) that specifies the address of the configuration change exit routine to receive control. The exit routine must reside in common storage, and the high-order bit of the routine's address must be set to 1. Do not code this parameter with CANCEL.

,RETCODE=rc addr

Specifies the location where the system is to store the return code. The return code is also in GPR 15.

,MF=S

An optional parameter that specifies the standard form of the macro. The standard form places the parameters into an in-line parameter list and invokes the service. The system checks for required parameters and supplies optional parameters that are not specified. MF=S is the default.

Return codes

When control returns from CONFCHG, GPR 15 (and rc addr, if you coded RETCODE) contains one of the following return codes:

Table 1. Return Codes for the CONFCHG Macro
Hexadecimal Return Code	Meaning
00	Meaning: CONFCHG processing completed successfully.
04	Meaning: Duplicate CONFCHG NOTIFY request.
08	Meaning: Error in the control parameter list.
10	Meaning: Error in CONFCHG processing.
14	Meaning: System is not able to process request.
18	Meaning: System cannot obtain storage for the request.
1C	Meaning: Token for CANCEL request is not valid.

Example 1

Issue the CONFCHG macro so that the user exit, CHGEXIT, gets control when a configuration change completes.

CONFCHG NOTIFY,CHGCOMPL,EXIT=EXIT_ADD,TOKEN=TOKEN

Example 2

Use the CONFCHG macro to indicate the user exit, CHGEXIT, should not be called after configuration changes.

CONFCHG CANCEL,CHGCOMPL,TOKEN=TOKEN