UPDATE IMS command

To change global PLEXPARM values in an IMSplex, use the UPDATE IMS SET(PLEXPARM()) command. To change local LCLPARM values in one or more IMS systems in an IMSplex, use the UPDATE IMS SET(LCLPARM()) command.

Subsections:

• Environment
• Syntax
• Keywords
• Usage notes
• Output fields
• Return, reason, and completion codes
• Examples

Environment

The following table lists the environments (DB/DC, DBCTL, and DCCTL) from which the UPDATE IMS command and keywords can be issued.

Syntax

>>-+-UPDATE-+--IMS---------------------------------------------->
   '-UPD----'        

>--+-SET(LCLPARM(-+-AUTOEXPORT(N)----------------------------+-))-+-><
   |              +-FPBP64STAT(-+-N-+-)----------------------+    |   
   |              |             '-Y-'                        |    |   
   |              |           .-,------------------------.   |    |   
   |              |           V                          |   |    |   
   |              +-LOCKTIME(---+-BMP(xx)--------------+-+-)-+    |   
   |              |             +-BMPOPT(-+-ABEND--+-)-+     |    |   
   |              |             |         '-STATUS-'   |     |    |   
   |              |             +-MSG(yy)--------------+     |    |   
   |              |             '-MSGOPT(-+-ABEND--+-)-'     |    |   
   |              |                       '-STATUS-'         |    |   
   |              '-REPO(Y)--REPOTYPE(IMSRSC)----------------'    |   
   |               .-,---------------------.                      |   
   |               V                       |                      |   
   +-SET(PLEXPARM(---+-GSTSAREA(-+-N-+-)-+-+-))-------------------+   
   |                 |           '-Y-'   |                        |   
   |                 +-GSTSDB(-+-N-+-)---+                        |   
   |                 |         '-Y-'     |                        |   
   |                 '-GSTSTRAN(-+-N-+-)-'                        |   
   |                             '-Y-'                            |   
   '-SET(PLEXPARM())--OPTION(-+-CONTINUE-+-)----------------------'   
                              '-FORCE----'                            

Keywords

The following keywords are valid for the UPDATE IMS command:

LCLPARM()

Specifies the values for the local parameters to be modified. The LCLPARM() keyword is mutually exclusive with the PLEXPARM() keyword in the UPDATE IMS SET() command.

The UPDATE IMS SET(LCLPARM()) command can be used to modify local parameters such as FPBP64STAT at each IMS system.

For the UPDATE IMS SET(LCLPARM()) command, all IMS systems that received the command from OM process the command.

Specify one of the following options:

AUTOEXPORT(N)

Specifies that the automatic export processing during system checkpoint should be disabled. The AUTOEXPORT keyword is valid in a DRD environment with or without the IMSRSC repository.

For the DRD users who are enabled with RDDS data sets, the UPDATE IMS SET(LCLPARM(AUTOEXPORT(N))) command can be used after successful migration to the repository. This command reduces the processor usage of automatic export at system checkpoints.

After the UPDATE IMS command with the AUTOEXPORT(N) keyword is issued, you can continue using system RDDS data sets on the EXPORT and IMPORT commands and during automatic import. However, during import and automatic import, make sure that the RDDS contains the current data especially if AUTOEXPORT is turned off.

Automatic export to the RDDS can be enabled by specifying AUTOEXPORT=N for the DFSDFxxx PROCLIB member and then starting IMS.

FPBP64STAT

Specifies whether Fast Path 64-bit buffer usage statistics per unit of work (UOW) for dependent regions are to be written to OLDS. The Fast Path 64-bit buffer usage is recorded in X'5945' log records.

N

Does not write Fast Path 64-bit buffer usage statistics per unit of work for dependent regions in X'5945' log records to OLDS.

Y

Writes Fast Path 64-bit buffer usage statistics per unit of work for dependent regions in X'5945' log records to OLDS.

LOCKTIME

Specifies the IMS LOCKTIME values. You can specify LOCKTIME values in any combination of the following keywords and parameters:

BMP(xx)

Specifies the amount of time that IMS waits before lock requests for BMP regions are timed out. BMP regions include IMS BMP and JBP regions. The value, which represents time in seconds, can range 1 - 32767.

BMPOPT(ABEND | STATUS)

Specifies whether IMS ends a timed-out task abnormally (ABEND) or returns a status code to the application (STATUS).

MSG(yy)

Specifies the amount of time that IMS waits before lock requests for MSG regions are timed out. MSG regions include IMS MPP, JMP, and IFP regions, as well as DRA threads. The value, which represents time in seconds, can range 1 - 32767.

MSGOPT(ABEND | STATUS)

Specifies whether IMS ends a timed-out task abnormally (ABEND) or returns a status code to the application (STATUS).

Updating IMS LOCKTIME values does not affect the lock timeout value in an IRLM. To change the lock timeout value in an IRLM, use the existing MODIFY IRLM command.

Recommendation: Generally, use the same timeout values for both IMS and IRLM. When using two values in IMS, setting the IRLM timeout value to the lower of the two IMS values allows IMS and IRLM to act together. When more than one IMS is identified to the same IRLM, workload conditions might require using different timeout values across IMS systems. In such a case, note the following:

• Using a lower timeout value in IRLM results in lock requests to wait until the time spent for waiting equals the lowest IMS LOCKTIME value.
• Using a higher timeout value in IRLM results in lock requests to wait beyond the IMS time because IRLM does not call IMS until the IRLM timeout value is exceeded.

REPO(Y)

Enables IMS to use the repository.

REPOTYPE(IMSRSC)

The repository type that is to be enabled. REPOTYPE is required with REPO(Y).

During command processing, IMS connects to RM for the repository services to enable IMS to use the repository. If RM is not enabled to use the repository, the UPDATE IMS command results in an error. You must first enable RM to use the repository by issuing the UPDATE RM command.

To disable use of the repository, IMS must be cold started.

When IMS is initialized, repository usage is enabled only if the REPOSITORY=(TYPE=IMSRSC) statement is defined in the REPOSITORY section of the DFSDFxxx PROCLIB member. Therefore, when the UPDATE IMS SET(LCLPARM(REPO(Y) REPOTYPE(IMSRSC)) command is successfully processed, the REPOSITORY=(TYPE=IMSRSC) statement must be added before any IMS restarts because we can disable usage of the repository only across an IMS cold start.

During IMS restart, if the IMS log records indicate that the IMSRSC repository was enabled before the restart and the REPOSITORY=(TYPE=IMSRSC) statement is not defined, IMS terminates with a U0168 abend code and X’1C’ error code.

For an XRF complex, entering the command on the IMS active system results in the command being processed on the IMS alternate system. Successful completion of the command requires that both the IMS active and alternate systems add the REPOSITORY=(TYPE=IMSRSC) statement in the REPOSITORY section of their respective DFSDFxxx PROCLIB members.

PLEXPARM()

Specifies the values for the global parameters to be modified. The LCLPARM keyword is mutually exclusive with the PLEXPARM keyword in the UPDATE IMS SET() command.

The UPDATE IMS SET(PLEXPARM()) command can be used to modify global status for areas, databases, and transactions that is maintained in an IMSplex. If the command is successful, the values in the RM global PLEXPARM entry along with the values maintained in each IMS system are updated.

For the UPDATE IMS SET(PLEXPARM()) command, all IMS systems in an IMSplex receive the command, but only the command master IMS processes the command. The non-master IMS systems do not process the command that is sent from OM. Instead, the command master IMS coordinates the change across all IMS systems in the IMSplex.

Specify one or more of the following resources:

GSTSAREA

Specifies how area status is maintained in the IMSplex.

N

No global status is maintained for area resources in RM. All global status in RM for area resources is deleted.

Y

Global status is maintained for area resources in RM. Global status is maintained on subsequent UPD AREA SCOPE(ALL) commands or type-1 area commands that include a GLOBAL keyword.

GSTSDB

Specifies how database status is maintained in the IMSplex.

N

No global status is maintained for database resources in RM. All global status in RM for database resources is deleted.

Y

Global status is maintained for database resources in RM. Global status is maintained on subsequent UPD DB SCOPE(ALL) commands or type-1 database commands that include a GLOBAL keyword.

GSTSTRAN

Specifies how transaction status is maintained in the IMSplex.

N

No global status is maintained for transaction resources in RM. All global status in RM for transaction resources is deleted.

Y

Global status is maintained for transaction resources in RM. Global status is maintained on subsequent UPD TRAN SCOPE(ALL) commands.

OPTION()

Specifies options for the UPDATE IMS SET command.

CONTINUE

Indicates that IMS should continue to process a previously entered UPDATE IMS SET command that encountered an error before it completed. The command must be at a point that allows processing to continue, otherwise the command is aborted.

If OPTION(CONTINUE) is specified, no parameters can be passed on the PLEXPARM parameter.

FORCE

OPTION(FORCE) can be used in a DBCTL warm-standby environment when the UPD IMS command fails because the standby did not finish restart processing. If OPTION(FORCE) is specified, the UPD IMS command can be completed even when an IMS is in restart mode. When OPTION(FORCE) is specified, the IMS in restart mode does not participate and update the UPD IMS values; this option only allows the UPD IMS command to finish at other IMS systems. The DBCTL standby rereads the global entry when it restarts to become the active in order to obtain the current PLEXPARM values. If OPTION(FORCE) is used when a non-DBCTL standby system did not finish restart, the results might not be as expected because the IMS does not run the UPD IMS command. This could lead to errors because of mismatch in the PLEXPARM values.

Usage notes

The UPDATE IMS SET command is a type-2 command that must be issued through the OM API. The command is defined to OM as ROUTE=ALL. OM routes the command to all IMS systems in an IMSplex. This command is not a recoverable command.

The only case in which the command is processed from a log record is on an XRF alternate system, which reads an X'220E' log record of the XRF active system to stay in step with the XRF active. Even in the XRF environment, if a takeover occurs and an IMS restart is required (/ERE or /NRE), the command is not recovered. It requires that the DFSDFxxx PROCLIB member be changed to include a REPOSITORY=(TYPE=IMSRSC) statement in the REPOSITORY section. Otherwise, IMS terminates with a U0168 abend code and X’1C’ error code.

In general, when a nonzero return code is received for the UPDATE IMS command, you must enter the UPD IMS SET(PLEXPARM()) OPTION(CONTINUE) command, which tells IMS to either complete the command or to cancel the command and clean up as required. The reason code from the UPD IMS SET(PLEXPARM()) OPTION(CONTINUE) command might indicate the state of the original UPD IMS command. If the command is unable to determine the state of the original UPD IMS command, the reason code indicates that fact. The user can use the QUERY IMS command to find out the state of the global IMSplex parameters.

If an error is encountered during the UPD IMS command processing, another new UPD IMS command cannot be processed until the UPDATE IMS SET(PLEXPARM()) OPTION(CONTINUE) command is issued and completes successfully.

If the error condition that caused the nonzero return code to be received for the UPDATE IMS command is not resolved, the UPDATE IMS SET(PLEXPARM()) OPTION(CONTINUE) command continues to encounter the same error condition. The error condition must be resolved before the command can be cleaned up and another UPDATE IMS command can be entered.

This command is not valid on an RSR tracker, an FDBR system, or an XRF alternate system. However, an FDBR system and an XRF alternate system maintain global PLEXPARM values internally and report their values with a QUERY IMS SHOW (PLEXPARM) command. IMS systems on RST tracker or FDBR systems return a completion code of ICC_NA or 1. The UPD IMS command is allowed to complete at other IMS systems.

The UPD IMS SET command is not allowed if an IMS is in restart. The command fails with a 'B0' return code. The UPD IMS command must be issued after the IMS completed restart processing.

When REPO(Y) is specified, some error conditions result in a DFS3308E, DFS4400E, DFS4457E, or other error message being sent as message output in the command reply. These messages can be used to help diagnose the cause of the error.

Output fields

Return, reason, and completion codes

The return and reason codes that can be returned as a result of the UPDATE IMS command are standard for all commands entered through the OM API.

The following table includes the return and reason codes and a brief explanation of the codes. The return or reason code returned for the command might also indicate an error from a CSL request.

Errors that are unique to the processing of the UPDATE IMS command are returned as completion codes. A completion code is returned for each action against an individual resource.