/MODIFY command

It switches the online environment from the active ACBLIB, FORMAT, and MODBLKS libraries to the inactive libraries containing the new or changed resource descriptions.

Subsections:

• Environment
• Syntax
• Keywords
• Usage notes
• Examples

Environment

The following table lists the environments (DB/DC, DBCTL, and DCCTL) in which you can use the command and keywords.

Syntax

>>-+-/MODIFY-+--+-ABORT--------------------------------+-------><
   '-/MOD----'  +-COMMIT-------------------------------+   
                '-PREPARE--| A |--+------------------+-'   
                                  '-LTERM--ltermname-'     

A

|--+-ALL----------------------+---------------------------------|
   | .----------------------. |   
   | V                      | |   
   '---+-ACBLIB--+------+-+-+-'   
       |         '-BLDL-' |       
       +-FMTLIB-----------+       
       +-MODBLKS----------+       
       '-RACF-------------'       

Keywords

The following keywords are valid for the /MODIFY command:

ABORT

Resets the status that was set by the /MODIFY PREPARE command after a /MODIFY PREPARE, or can be used if the /MODIFY COMMIT was not successful and the operator chooses not to attempt the online change at that time.

COMMIT

Brings all the newly defined resources online, updates the changed resources, and invalidates the deleted resources.

If ALL was specified on the /MODIFY PREPARE command, the ACBLIB, FMTLIB, and MODBLKS changes must be successful or the /MODIFY COMMIT will be rejected. When COMMIT is successful, the modifications will persist across all IMS restarts. If FMTLIB is entered, most new and in-progress requests will be queued for processing after the /MODIFY COMMIT command is completed.

If MODBLKS or ACBLIB is specified, work in progress for changed or deleted resources in the IMS.ACBLIB data set or in the IMS.MODBLKS data set that are directly affected must be completed, or the /MODIFY command is rejected.

If DRD is enabled and /MODIFY PREPARE ALL was specified, the /MODIFY COMMIT command does not swap the MODBLKS library suffix. The DFS3499 message shows the same MODBLKS suffix before and after the online change.

IMS does not reject the /MODIFY COMMIT command if the online change indirectly affects transactions (having work in progress) that reference resources in the ACB library or in the MODBLKS data set that are directly affected by the online change. These transactions themselves are not being changed (no attribute on the TRANSACT macro is being changed), but they reference a PDIR, PSB, or DMB that is affected by the online change. A transaction can be indirectly affected by an online change in one of the following situations:

• The transaction references a PSB directory (PDIR) control block in the IMS.MODBLKS data set that is being changed
• The transaction references a PSB in the ACB library (IMS.ACBLIB) that is being changed online
• The transaction references a PSB directory (PDIR) control block in the IMS.MODBLKS data set which in turn references a database that is being changed online
• The transaction references a PSB in the ACB library (IMS.ACBLIB) that references a database that is being changed online

/DISPLAY MODIFY is used to display the work that was in progress prior to the entering of /MODIFY COMMIT.

IMS will prevent messages entered from terminals from being queued to transactions, but program-to-program switches from applications can still occur. Therefore, a /DISPLAY MODIFY command can indicate that no work is pending for the resources to be modified or deleted, but the /MODIFY COMMIT might be rejected. If this occurs, the new work must be allowed to complete and then the /MODIFY COMMIT command must be reentered.

/MODIFY COMMIT is rejected if:

• A /MODIFY PREPARE command was not previously entered.
• Transactions to be deleted have messages queued.
• Transactions to be changed by the following system definition keywords have messages queued:
  • MSGTYPE
  • INQUIRY
  • FPATH
  • EDIT
  • SPA
• Transactions to be changed by keywords not shown in the previous bullet have messages queued, and the transactions have not been the object of a /STOP or /PSTOP command.
• Transactions with access to programs or databases to be changed or deleted are prevented from updating, and the transactions have not been the object of a /STOP or /PSTOP command. When a transaction shows a status of USTOP during a /DISPLAY TRAN, the /STOP command might need to be entered, because the /PSTOP command might not enable the /MODIFY command to complete the transaction.
• Any program (PSB) that is currently scheduled has a program, database, or transaction change or deletion. This includes Wait for Input (WFI) and Fast Path transactions. All WFI and Fast Path regions that reference changed or deleted routing codes, programs, or databases must be stopped before entering the /MODIFY COMMIT.
• An I/O error occurs while reading the inactive MFS FORMAT library directory or the resident index ($$IMSDIR) member.
• A /START DATABASE command is in progress for any database that is changed or deleted.
• A /DBDUMP or /DBRECOVERY command is in progress for any database that is changed or deleted.

Operator action might be required to prevent the preceding conditions. For example, if a program or database is scheduled, the operator should either wait until the program or database is finished before the /MODIFY COMMIT command is entered, or the operator should issue /STOP or /PSTOP for the associated transaction.

If IMS is in an IMSplex and Resource Manager (RM) is using a resource structure, the transactions being added by the online change are registered to RM if they are not already registered to RM. If any error occurs during the CSLRMUPD request to register the transactions, the /MODIFY or INITIATE OLC command will fail and IMS will be in a COMMIT2F state.

If a /MODIFY COMMIT command results in the COMMIT2F state, the command is rejected with a DFS178 message. A DFS3308 message is sent to the system console with the CSLRMUPD return/reason code. The IMS remains in a COMMIT2F state and the /MODIFY cannot be committed or aborted. The IMS must be canceled and warm started as the online change is not complete.

PREPARE

/MODIFY PREPARE is not recovered across an emergency restart and must be reentered after restart if the /MODIFY COMMIT did not complete prior to an IMS failure.

The parameters in the following table are valid with /MODIFY PREPARE. The environments in which the parameters are valid are also shown in this table.

Table 2. /MODIFY PREPARE parameters environments

Parameter	DB/DC	DBCTL	DCCTL
ACBLIB	X	X	X
ALL	X	X1	X
BLDL	X	X	X
FMTLIB	X		X
LTERM	X		X
MODBLKS	X	X	X
RACF®	X		X
Note: Only applies to ACBLIB, MODBLKS, and BLDL.

ACBLIB

Quiesces the transactions to be changed or deleted and transactions that access databases or programs to be changed or deleted. ACBLIB members that are not found are displayed as CHANGED because a DDIR or PDIR exists in MODBLKS. Additions or deletions to ACBLIB require the MODBLKS parameter.

If a DMB is being added to the ACBLIB with no MODBLKS change (no DMB exists in the active ACBLIB and a DMB exists in the inactive ACBLIB), then the display will show ADDED instead of CHANGED. If a DMB is being deleted from the ACBLIB with no MODBLKS change (DMB exists in the active ACBLIB and no DMB exists in the inactive ACBLIB), then the display will show DELETED instead of CHANGED. No MODBLKS change means a DDIR exists in the MODBLKS and the same MODBLKS is used before and after the online change.

ALL

Indicates that /MODIFY PREPARE is to be performed for ACBLIB, FMTLIB, RACF, MODBLKS and BLDL.

BLDL

Causes information message DFS3498I to be issued for each PSB or DMB not found in ACBLIB. This message does not affect the success of the command.

FMTLIB

Indicates that there will be no restrictions on the use of MFS format blocks until the /MODIFY COMMIT command is entered.

LTERM ltermname

Specifies a logical terminal to receive lists of added, changed, or deleted resources.

MODBLKS

Causes IMS to prepare to bring the changes or deletions defined by the new system definition to IMS. Using MODBLKS also quiesces the transactions to be changed or deleted and transactions that access databases or programs to be changed or deleted. This command is rejected if it is issued on an IMS that has DRD enabled.

RACF

Use of the RACF data space invalidates the IMS online change support for RACF with the /MODIFY command. The IMS online change support is still valid, though, when the RACF data space is not being used.

The message DFS3432 RACF PARAMETER INVALID IF RACF DATA SPACE IS USED is issued if the RACF parameter is used on the /MODIFY PREPARE command when the RACF data space is being used. You can use the RACF command SETROPTS RACLIST (classname) REFRESH to refresh the RACF resource profiles in the RACF data space without requiring the IMS applications to suspend work.

Usage notes

The following table lists the resources and parameters available to the /MODIFY command:

The correct sequence for /MODIFY commands is PREPARE followed by COMMIT. If the online change is not to be completed, the /MODIFY ABORT command is used. The /MODIFY PREPARE command specifies which resources are to be changed or deleted. Depending on the parameters entered, the system will initiate quiescing of appropriate resources. COMMIT initiates the changes entered in a preceding PREPARE. If a previously entered /MODIFY PREPARE command is to be canceled, ABORT must be entered.

An IMS automated operator program can issue the /MODIFY PREPARE and /MODIFY ABORT commands, but it cannot issue the /MODIFY COMMIT command. Thus, you can automatically prepare or abort online change.

If this command is used to delete a database, IMS closes the database and makes it unavailable to programs. Also, if the database is authorized for DBRC, /MODIFY deauthorizes it.

Fast Path DEDBs are supported by the /MODIFY command, but Fast Path MSDBs are not supported.

In an IMSplex, /MODIFY is not supported if coordinated online change is enabled. This command can be issued to an IMSplex using the Batch SPOC utility.

If DRD is enabled, the /MODIFY command specified with the MODBLKS keyword alone or with other keywords is rejected. The command /MODIFY PREPARE ALL ignores resources in the MODBLKS data set. If IMS is started without the MODBLKS DD cards, the MODBLKS-name field in the DFS3499 message is blank, which means that the MODBLKS data set is not applicable. This is consistent with what DBCTL does with FMTLIB. If IMS is started with the MODBLKS DD statements, the MODBLKS-name field is displayed, with a name suffix of A during prepare and during commit, which means that the MODBLKS libraries were not changed. The ACBLIB and FMTLIB data sets are still supported if DRD is enabled.

An online change of a PSB or DBD will remove the member from the 31-bit pool as well as the 64-bit pool.

If a resident program is changed, it becomes nonresident locally because its definition in the resident PSB pool is no longer valid. If its resident definition attribute was not changed, it becomes resident again at the next IMS restart. If a nonresident program is changed to be resident, the residency takes effect at the next IMS restart.