Detecting I/O configuration changes

You can use the MVS™ I/O configuration token to detect I/O configuration changes. The MVS I/O configuration token is a 48-byte token that uniquely identifies an I/O configuration to the system. The token will change whenever the software configuration definition changes. Thus, if your program obtains the current I/O configuration token and compares it to one previously obtained, the program can determine whether there has been a change in the I/O configuration: If the tokens do not match, the I/O configuration has changed.

Both the MVS I/O configuration token and the ENFREQ macro (or the CONFCHG macro) with its related exit can be used to detect I/O configuration changes. (See Requesting notification of I/O configuration changes for information on the ENFREQ or CONFCHG macro and related exit routine.) However, there are two important differences:

The ENFREQ macro (or the CONFCHG macro) and related exit are available only to authorized programs, whereas both authorized and unauthorized programs can use the MVS I/O configuration token.
With the ENFREQ macro (or the CONFCHG macro) and related exit, you can also receive notification of requested configuration changes that involve deleting a device or deleting a path to a device but have not yet occurred. With the MVS I/O configuration token, you can only detect changes that have already taken place.

An optional parameter, IOCTOKEN, is available with the UCB macros. Specifying IOCTOKEN ensures that the system will notify the caller through a return code and will not return any data if the current I/O configuration is not consistent with the configuration represented by the token that was specified as input by the caller.

There are two ways to obtain the current I/O configuration token:

Issue the IOCINFO macro. See z/OS MVS Programming: Assembler Services Reference IAR-XCT for information on how to code the IOCINFO macro.
Issue any of the UCB macros, setting the input specified by the IOCTOKEN parameter to binary zeroes. The macro will then return the current I/O configuration token.
Note: For the UCBSCAN macro, setting the IOCTOKEN to binary zeroes returns the I/O configuration token at the start of the scan.

Use of the I/O configuration token can help prevent data inconsistencies that might occur if the I/O configuration changes between the time the caller obtained the token and the time the service returns the information. For example, you can use the configuration token to identify a case in which the I/O configuration changes during a UCB scan. If the IOCTOKEN parameter is specified with UCBSCAN, the system will notify the caller through a return code if the set of UCBs changes while the scan is in progress. Checking for the return code would allow the caller to restart the scan to ensure that all UCBs in the current configuration are referenced.

Specifying IOCTOKEN also allows the caller to receive notification if a dynamic device reconfiguration (DDR) swap occurs. DDR SWAP causes a token change.

The I/O configuration token can also serve to identify that the relationship between a device number and a UCB address has changed. This could be useful when a device number or UCB address is saved along with a configuration token and used for later processing. For example, a program may obtain a device number from the EDTINFO macro. The program may then want to issue UCBLOOK to obtain the UCB address for that device number. To ensure that the device definition of the UCB address obtained from UCBLOOK is consistent with the definition of the device number obtained by EDTINFO, the configuration token can be used.

In some cases, a change in the relationship between device number and UCB can only be detected through the use of an I/O configuration token. For example:

A dynamic configuration change occurs that deletes a UCB and adds a different UCB at the same device number.
A dynamic configuration change occurs that deletes a UCB. Then, a subsequent dynamic configuration change adds a new UCB at the same address as that of the deleted one.
A dynamic device reconfiguration (DDR) swap occurs that swaps the contents of two UCBs.