IMS Version 9

INITIATE

Format

INITIATE OLC

Read syntax diagramSkip visual syntax diagram>>-+-INITIATE-+--OLC-------------------------------------------->
   '-INIT-----'

>--+-PHASE(COMMIT)---------------------------------------------------+-><
   '-PHASE(PREPARE)-+-TYPE(ACBLIB)-+---------------------------+---+-'
                    |              |         .-,-----------.   |   |
                    |              |         V             |   |   |
                    |              '-OPTION(---+-BLDL----+-+-)-'   |
                    |                          +-FRCABND-+         |
                    |                          '-FRCNRML-'         |
                    +-TYPE(ALL)-+----------------------------+-----+
                    |           |         .-,------------.   |     |
                    |           |         V              |   |     |
                    |           '-OPTION(---+-BLDL-----+-+-)-'     |
                    |                       +-FRCABND--+           |
                    |                       +-FRCNRML--+           |
                    |                       +-PSWD-----+           |
                    |                       +-TERMINAL-+           |
                    |                       '-TRANCMDS-'           |
                    +-TYPE(FMTLIB)-+---------------------------+---+
                    |              |         .-,-----------.   |   |
                    |              |         V             |   |   |
                    |              '-OPTION(---+-FRCABND-+-+-)-'   |
                    |                          '-FRCNRML-'         |
                    '-TYPE(MODBLKS)-+----------------------------+-'
                                    |         .-,------------.   |
                                    |         V              |   |
                                    '-OPTION(---+-FRCABND--+-+-)-'
                                                +-FRCNRML--+
                                                +-PSWD-----+
                                                +-TERMINAL-+
                                                '-TRANCMDS-'

|INITIATE OLREORG

| |
Read syntax diagramSkip visual syntax diagram|                                    .-,--------.
|                                    V          |
|>>-+-INITIATE--+--OLREORG--NAME--(----partname-+--)------------->
|   +-INIT------+
|   +-/INITIATE-+
|   '-/INIT-----'
|
|   .-SET(RATE(100))--.  .-OPTION(DEL)---.
|>--+-----------------+--+---------------+----------------------><
|   '-SET(RATE(rate))-'  '-OPTION(NODEL)-'
|
|

Environments and Keywords

Table 66 and Table 67 lists the environments (DB/DC, DBCTL, and DCCTL) from which the INITIATE command and keywords can be issued.

Table 66. Valid Environments for the INITIATE OLC Command and Keywords
Command / Keywords DB/DC DBCTL DCCTL
INITIATE OLC X X X
ACBLIB X X X
BLDL X X X
FMTLIB X X
FRCABND X X X
FRCNRML X X X
MODBLKS X X X
OPTION X X X
PHASE X X X
PSWD X X X
TERMINAL X X
TRANCMDS X X
TYPE X X X
Table 67. Valid Environments for the INITIATE OLREORG Command and Keywords
|Command |/ Keywords |DB/DC |DBCTL |DCCTL
|OLREORG | X |X |
|NAME |X |X |
|SET |X |X |
|OPTION |X |X |

INITIATE OLC

|If an IMSplex is running with an RM environment (RMENV=Y), |the INITIATE OLC (initiate online change) command initiates a phase of global |online change of resources and coordinates the phase with all of |the IMSs in the IMSplex. The RM environment (RMENV = Y | N) is specified |in the DFSCGxxx PROCLIB member. INITIATE OLC is similar to /MODIFY PREPARE and /MODIFY COMMIT, except that it applies to an IMSplex-wide global online |change. OM sends the INITIATE OLC command to one master IMS in the IMSplex. The command master |IMS uses RM services to coordinate the online change with all participating |IMSs.

|If the command master IMS in an IMSplex is running |without an RM environment (RMENV=N), the INITIATE OLC command is performed locally at the IMS to which the command |was sent. The OLCSTAT DS must be unique for each IMS in the IMSplex that |is running with no RM environment (RMENV=N). The OLCSTAT DS cannot |be shared between IMSs and must be unique. If the OLCSTAT DS contains |the name of an IMS other than the one processing the online change, INITIATE OLC is rejected with a reason code indicating that the OLCSTAT |data set is invalid for the environment. You can use the QUERY OLC command to display the contents of the OLCSTAT data set to |determine which IMS member name is invalid. To correct the data |set, you can use the OLC utility, DFSUOLC0.

|If INITIATE OLC is issued with a route list containing either the default |Route All or multiple IMSs that do not have RM running, the INITIATE OLC command must be issued separately to each IMS. To perform |online change for IMSs that do not have RM, you must issue the INITIATE OLC command to each IMS. For example, if you have four IMS systems, |you must issue the command to each IMS. To determine which IMSs |are defined with RMENVNO in the DFSCGxxx PROCLIB member, you can |issue the QUERY MEMBER SHOW(ATTRIB) command.

|If multiple IMS sytems are in an IMSplex where some |IMSs use RM services and other IMSs do not, you must ensure that |the OLCSTAT data sets are properly defined to the IMS systems. The |IMS systems that use RM services and global online change must share |one OLCSTAT DS. Each IMS system that does not use RM services must have |its own unique OLCSTAT DS.

INITIATE OLC is not supported if local online change is enabled. The INITIATE OLC PHASE(PREPARE) command is rejected if the IMS to which the command is routed does not support global online change. If this occurs and there is an IMS that supports global online change, the user must route the command to a specific IMS that supports global online change.

The correct online change command sequence is INITIATE OLC PHASE(PREPARE) followed by INITIATE OLC PHASE(COMMIT). Use the /DISPLAY MODIFY command to display the work in progress for resources to be changed or deleted, before attempting the COMMIT phase. When COMMIT is successful, the modifications persist across all IMS restarts, unless global online change occurs while this IMS is down.

If the INITIATE OLC PHASE(PREPARE) is specified without a FRCABND or FRCNRML keyword and the command fails as one or more IMSs are down or go down before the online change is committed, the online change must be aborted and started over. Issue the TERMINATE OLC command to abort the online change.

If the INITIATE OLC PHASE(PREPARE) is specified with the FRCNRML keyword and the command fails for any IMS, you can proceed with an INITIATE OLC PHASE(COMMIT) command, if desired, after shutting down those IMSs where prepare failed. Otherwise, you must abort the online change and start over.

If the INITIATE OLC PHASE(PREPARE) is specified with the FRCABND keyword and the command fails for any IMS, you can proceed with an INITIATE OLC PHASE(COMMIT) command, if desired, after cancelling those IMSs where prepare failed. Otherwise, you must abort the online change and start over.

The INITIATE OLC command master usually performs the online change phase locally first. If the online change phase fails locally, the command master usually skips sending the online change phase to the other IMSs, sets a completion code for each other IMS indicating that the online change phase was not attempted, and terminates command processing. However, if the INITIATE OLC PHASE(COMMIT) command fails on the local IMS because of work in progress, the command master still sends the commit phase 1 to the other IMSs. The purpose is to report work in progress for all the IMSs in the IMSplex, to facilitate completion of work in progress.

In a mixed IMSplex, you might have some variations of IMSs that support a particular type of online change and some that do not. At least one IMS in the IMSplex must successfully perform the online change phase for the command to be considered successful. If no IMS in the IMSplex supports the type of online change that the command is attempting, the command reason code indicates that none of the IMSs performed the online change phase. If you enter an INITIATE OLC PHASE(PREPARE) command that does not apply to any IMS in the IMSplex, you must terminate the online change with a TERMINATE OLC command.

If the INITIATE OLC PHASE(COMMIT) command fails for any IMS before the OLCSTAT data set is updated, you may either correct the errors and try the commit again or abort the online change with a TERMINATE OLC command.

If the INITIATE OLC PHASE(COMMIT) command fails for any IMS after the OLCSTAT data set has been updated, you may correct the errors and try the commit again. The online change cannot be aborted.

If an IMS abends during online change and the INITIATE OLC PHASE(PREPARE) command was not specified with FRCABND, then issue the TERMINATE OLC command to abort the online change. The INITIATE OLC PHASE(COMMIT) command is not permitted in this case. If an IMS abends during online change and the INITIATE OLC PHASE(PREPARE) command was specified with FRCABND, then the INITIATE OLC PHASE(COMMIT) command is permitted.

IMSplex commands and classic commands that come from the OM interface are rejected during the commit phase, if the command changes resources. Commands that change resources could interfere with the online change of the resources. IMSplex commands and classic commands that come from the OM interface are permitted during the commit phase, if the command displays resources, such as QUERY or /DISPLAY. Classic commands that are entered from the system console or an IMS terminal are queued during the online change commit phase. These commands run after the online change is committed or aborted.

The resources that may be changed online are areas, databases, DMBs, Fast Path DEDB databases, MFS formats, programs, routing codes, SMU security definitions, and transactions.

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 an INITIATE OLC PHASE(COMMIT) command results in the IMS remaining in a COMMIT2F state, a completion code of the error that caused it is returned to OM. If the error can be fixed, the INITIATE OLC PHASE(COMMIT) can be re-issued and CSLRMUPD retried and the online change completed. If the error cannot be fixed, the IMS has to be cancelled and warm started as the online change is not complete

This command is invalid on an XRF alternate, RSR tracker, and FDR system.

Each IMS participating in the global online change does not issue the same synchronous online change messages to the master terminal or system console that it does for a local online change. The OM command response contains information equivalent to the online change messages that appear for the local online change, such as the DFS3499 message contents. See INITIATE OLC Return and Reason Codes for more information about what is returned from an INITIATE OLC command.

Each IMS participating in the global online change may issue asynchronous online change messages to the system console, such as DFS3400, DFS3445, and DFS3498.

The OM command time-out default of 300 seconds (5 minutes) may not be enough time for the online change phase to complete. It may be required to specify a time-out value on the command based on the needs of the installation.

OPTION()
Specifies an additional function to be performed during an online change. Following is a list of additional functions:
BLDL
Sends asynchronous information message DFS3498I to the system console for each PSB or DMB not found in ACBLIB. This message does not affect the success of the command.
FRCABND
Forces the online change prepare phase even if one or more required IMSs in the IMSplex have abended. An IMS is required to participate in the global online change if it is listed in the OLCSTAT data set as being current with the online change libraries. An IMS is listed in the OLCSTAT data set because it either participated in the last global online change or coldstarted since the last global online change. A successful global online change specified with the FRCABND removes an abended IMS from the list of required IMSs in the OLCSTAT data set.
FRCNRML
Forces the online change prepare phase even if one or more required IMSs in the IMSplex have terminated normally. An IMS is required to participate in the global online change if it is listed in the OLCSTAT data set as being current with the online change libraries. An IMS is listed in the OLCSTAT data set because it either participated in the last global online change or coldstarted since the last global online change. A successful global online change specified with the FRCNRML keyword removes an IMS that shut down normally from the list of required IMSs in the OLCSTAT data set.
PSWD
Specifies specific types of SMU password security definitions to add, if they had not existed before. The application of new security definitions are always attempted based upon the prevailing security options in effect from the last IMS initialization.
TERMINAL
Specifies specific types of SMU terminal security definitions to add, if they had not existed before. The application of new security definitions are always attempted based upon the prevailing security options in effect from the last IMS initialization.
TRANCMDS
Specifies specific types of SMU transaction command security definitions to add, if they had not existed before. The application of new security definitions are always attempted based upon the prevailing security options in effect from the last IMS initialization.
PHASE()
Refers to the online change phase to start. The PREPARE phase must be performed first, followed by the COMMIT phase:
PREPARE
Performs the online change prepare phase on each IMS system listed in the OLCSTAT data set by specifying which resources are to be added, changed, and deleted. PREPARE is not recovered across an emergency restart and must be reentered after restart if the COMMIT phase did not complete prior to IMS failure.

The prepare phase is rejected if any IMSs in the IMSplex current with the online change libraries are down, unless the FRCABND or the FRCNRML option is used. The OLCSTAT data set lists the IMSs that are current with the online change libraries. These IMSs either participated in the last global online change or coldstarted after the last global online change. To force a global online change in spite of abended IMSs, use the FRCABND option. To force a global online change in spite of IMSs that are shut down normally, use the FRCNRML option. The prepare phase fails if any IMS participating in the global online change prepare phase fails, detects an error, or fails to respond in time. Zero, one, or more of the IMSs remain in an online change prepare complete state. Issue the QUERY MEMBER TYPE(IMS) SHOW(STATUS) command to display the online change state of all the IMSs in the IMSplex. Evaluate the QUERY MEMBER TYPE(IMS) output to help you decide whether to issue the INITIATE OLC PHASE(PREPARE) command to try the prepare again, or to issue the TERMINATE OLC command to abort the online change. The IMSs that are in an online change state remain in an online change state until you abort or commit the online change. IMS does not automatically abort online change because of a failure. IMS leaves the IMSs in their online change states. You must issue the QUERY MEMBER TYPE(IMS) SHOW(STATUS) command and evaluate the output to decide whether to abort the online change or attempt the online change phase again.

COMMIT
Performs the online change commit phase on each IMS listed in the OLCSTAT data set, which commits the online changes by bringing all the newly defined resources online, updating changed resources, and removing deleted resources. The commit phase consists of commit phase 1, the OLCSTAT data set update, commit phase 2, and commit phase 3. The OLCSTAT data set is updated with the new current online change libraries and the list of IMSs that are current with the current online change libraries. The commit phase 2 switches the online environment from the active ACBLIB, FORMAT, MATRIX, or MODBLKS libraries to the inactive libraries containing the new or changed resource descriptions.

The commit phase fails if any IMS participating in the global online change commit phase fails, detects an error, or fails to respond in time. Zero, one, or more of the IMSs might be in an online change prepare complete state, a commit phase 1 complete state, or no longer in an online change state because commit phase 2 succeeded. Issue the QUERY MEMBER TYPE(IMS) SHOW(STATUS) command to display the online change state of all the IMSs in the IMSplex. Evaluate the QUERY MEMBER TYPE(IMS) output to help you decide whether to issue the INITIATE OLC PHASE(COMMIT) command to try the commit again, or issue the TERMINATE OLC command to abort the online change. The IMSs that are in an online change state remain in an online change state until you abort or commit the online change.

IMS does not automatically abort online change because of a failure. IMS leaves the IMSs in their online change states. You must issue the QUERY MEMBER TYPE(IMS) SHOW(STATUS) command and evaluate the output to decide whether to abort the online change or attempt the online change phase again.

If a database is deleted, IMS closes the database and makes it unavailable to programs. Also, if the database is authorized for DBRC, COMMIT unauthorizes it.

If FMTLIB is being changed, most new and in-progress requests are queued for processing after the INITIATE OLC PHASE(COMMIT) command is completed.

Most new and in-progress requests are queued for processing.

An INITIATE OLC PHASE(COMMIT) is rejected if:

  • An INITIATE OLC PHASE(PREPARE) command was not previously entered.
  • Commit phase 1 fails on one or more IMSs in the IMSplex.
  • 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 queues 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 command, the /STO command might need to be entered because the /PSTOP command might not allow the INITIATE OLC command to complete the transaction.
  • Programs or databases to be changed or deleted are scheduled.
  • 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 INITIATE OLC PHASE(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.
  • An IMS that participated in the prepare phase shut down normally or abended. The online change must be aborted and started over.
  • OM routed the command to an IMS where local online change is enabled.
  • The OLCSTAT data set is not locked for global online change.

    The INITIATE OLC PHASE(PREPARE) commands locks the OLCSTAT data set, so that no IMSs can initialize during the global online change. The commit command is rejected if the lock is not set. The INITIATE OLC PHASE(PREPARE) command might not have completed successfully or the OLCSTAT data set contents might be invalid.

  • |An IFP region is running. INITIATE OLC PHASE(COMMIT) is rejected because an active route code exists. All IFP |regions must be terminated before issuing a COMMIT.

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 INITIATE OLC PHASE(COMMIT) command is entered or the operator should issue /STOP, /PSTOP, or UPDATE TRAN for the associated transaction.

TYPE()
Specifies the types of resources that are changed online. The resources are as follows:
ACBLIB
Causes IMS to prepare to add, change, or delete database descriptors (DMB) and program descriptors (PSB) to ACBLIB. The online environment is switched from the active ACBLIB to the inactive ACBLIB containing new or changed DMB and PSBs. 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. Quiesces transactions to be changed or deleted and transactions that access databases or programs to be changed or deleted. Fast Path DEDBs are supported but Fast Path MSDBs are not supported.
ALL
Prepares to add, change, and delete resources for the ACBLIB, FMTLIB, or MODBLKS libraries. The BLDL function is performed for ACBLIB.
FMTLIB
Causes IMS to prepare to add, change, or delete MFS maps in the FMTLIB library that are produced by the MFS Language utility and Service utility. The online environment is switched from the active FMTLIB to the inactive FMTLIB containing new MFS maps produced by the MFS Language utility and Service utility. The FMTLIB parameter is ignored with DBCTL. There are no restrictions on the use of MFS format blocks until the INITIATE OLC PHASE(COMMIT) command is entered.
MODBLKS
Causes IMS to prepare to add, change, or delete database, transaction, program, or RTCODE resources in the MODBLKS library or SMU security definitions in the MATRIX library. The online environment is switched from the active MODBLKS and MATRIX libraries to the inactive MODBLKS and MATRIX libraries. The MODBLKS library contains a subset of control blocks produced by IMS system definition and SMU security definitions. The MATRIX library contains SMU security definitions for resources defined in the MODBLKS library. Transactions to be changed or deleted and transactions that access databases or programs to be changed or deleted are quiesced.

INITIATE OLC Output Fields

Table 68 shows the output fields for an INITIATE OLC command. The columns in the table are as follows:

Short Label
Contains the short label generated in the XML output.
Keyword
Identifies the keyword on the command that caused the field to be generated. N/A appears for output fields that are always returned.
Meaning
Provides a brief description of the output field.
Table 68. INITIATE OLC Output Field Descriptions
SHORT LABEL KEYWORD MEANING
MBR N/A IMSplex member that built the line of output. IMS identifier of the IMS that is the master of this online change phase. IMS identifier is always returned.
IMSMBR N/A IMS member that performed the global online change phase. The IMS member name is always returned.
CC N/A Completion code returned by IMS member that performed the global online change phase. Completion code is always returned.
ERRT N/A Error text returned by IMS member that failed performing the global online change phase. Error text may be returned if the completion code is nonzero.
ACBL N/A Current ACBLIB library suffix (if prepare succeeded or commit succeeded that did not include ACBLIB), or new ACBLIB library suffix (if commit succeeded for ACBLIB). The ACBLIB suffix is returned if the online change prepare phase or commit phase is successful. Suffix A means that ACBLIBA is current. Suffix B means that ACBLIBB is current.
FMTL N/A Current FMTLIB library suffix (if prepare succeeded or commit succeeded that did not include FMTLIB), or new FMTLIB library suffix (if commit succeeded for FMTLIB). The FMTLIB suffix is returned if the online change prepare phase or commit phase is successful. Suffix A means that FMTLIBA is current. Suffix B means that FMTLIBB is current.
MODB N/A Current MODBLKS library suffix (if prepare succeeded or commit succeeded that did not include MODBLKS), or new MODBLKS library (if commit succeeded for MODBLKS). The MODBLKS suffix is returned if the online change prepare phase or commit phase is successful. Suffix A means that MODBLKSA and MATRIXA are current. Suffix B means that MODBLKSB and MATRIXB are current.
MODI N/A Current modify id (if prepare succeeded), or new modify id (if commit succeeded). The modify id - 1 indicates the number of global online changes that have been performed. The modify id is returned if the online change prepare phase or commit phase is successful.

INITIATE OLC Return and Reason Codes

Two sets of return and reason codes are returned when a command is issued through the OM API. One set of codes is for the OM request and the other set of codes is for the command itself. The OM request return and reason codes that can be returned as a result of the INITIATE OLC command are standard for all commands entered through the OM API.

The return and reason codes returned by the INITIATE OLC command are passed from the OM API on to the SPOC application. These codes are encapsulated in XML tags similar to how the response to the command is encapsulated in XML tags. The IBM-supplied TSO SPOC displays these codes, whereas a user-written SPOC application might choose not to display these codes.

Some reason codes are accompanied by a complete list of IMSs and return codes. The reason code meaning indicates whether a list is returned. A partial list of IMSs and return codes might be returned with any INITIATE OLC error reason code, if any output was built before the error was detected.

Table 69 shows the return and reason codes that might be returned by the INITIATE OLC command as well as the meaning of the codes.

Table 69. Return and Reason Codes for INITIATE OLC
Return Code Reason Code Meaning
X'00000000' X'00000000' The INITIATE OLC command completed successfully. The INITIATE OLC command applies to all of the IMSs listed in the OLCSTAT data set. Each IMS listed in the OLCSTAT data set is current with the online change libraries and required to participate in the online change. Neither FRCABND nor FRCNRML was specified.

If the INITIATE OLC PHASE(PREPARE) command was specified, all of the IMSs listed in the OLCSTAT data set are now in an online change prepare state.

If the INITIATE OLC PHASE(COMMIT) command was specified, all of the IMSs listed in the OLCSTAT data set successfully committed the online change.

An output line is built for each IMS listed in the OLCSTAT data set. Each output line contains the IMS member name and a completion code of zero.

X'00000004' X'0000100C' The command completed successfully, but was not applicable to one or more IMSs for acceptable reasons. The INITIATE OLC command applies to all of the IMSs listed in the OLCSTAT data set. Each IMS listed in the OLCSTAT data set is current with the online change libraries and required to participate in the online change (unless FRCABND or FRCNRML is specified).

An output line is built for each IMS listed in the OLCSTAT data set. Each output line contains the IMS member name and a completion code. A nonzero completion code may be accompanied by error text. One or more of the IMSs contain a completion code indicating the online change phase did not apply to this IMS, such as the IMS state is shutdown and FRCSHUT was specified, the IMS state is abended and FRCABND was specified, the online change type does not apply to this IMS, or this IMS is already in the correct online change state. The INITIATE OLC completion code table contains the list of completion codes and error text that can be returned by the INITIATE OLC command.

X'00000008' X'00002040' The INITIATE OLC command is rejected because of an invalid filter. The INITIATE OLC PHASE(PREPARE) OPTION(BLDL) can only be specified with TYPE ACBLIB or ALL. The PSWD, TERM, and TRANCMDS options can only be specified with TYPE MODBLKS or ALL. The INITIATE OLC PHASE(COMMIT) command does not support TYPE or OPTION.
X'0000000C' X'00003000' The INITIATE OLC command is successful for at least one IMS but not all IMSs. The INITIATE OLC command applies to all of the IMSs listed in the OLCSTAT data set. Each IMS listed in the OLCSTAT data set is current with the online change libraries and required to participate in the online change (unless FRCABND or FRCNRML is specified).

An output line is built for each IMS listed in the OLCSTAT data set. Each output line contains the IMS member name and a completion code. A nonzero completion code may be accompanied by error text. One or more of the IMSs returned an error completion code. The INITIATE OLC completion code table contains the list of completion codes and error text that can be returned by the INITIATE OLC command.

If INITIATE OLC PHASE(PREPARE) fails, the online change must be aborted and started over.

If INITIATE OLC PHASE(COMMIT) fails and you want to retry the commit, correct the problem and issue the INITIATE OLC PHASE(COMMIT) command again.

To abort the online change, issue the TERMINATE OLC command. If the INITIATE OLC PHASE(PREPARE) command failed or the INITIATE OLC PHASE(COMMIT) command failed before the commit master updated the OLCSTAT data set, the online change is aborted.

See 'INITIATE OLC error handling' for more details.

X'0000000C' X'00003004' The INITIATE OLC command failed for all of the IMSs. The INITIATE OLC command applies to all of the IMSs listed in the OLCSTAT data set. Each IMS listed in the OLCSTAT data set is current with the online change libraries and required to participate in the online change (unless FRCABND or FRCNRML is specified).

An output line is built for each IMS listed in the OLCSTAT data set. Each output line contains the IMS member name and a completion code. A nonzero completion code may be accompanied by error text. The INITIATE OLC completion code table contains the list of completion codes and error text that can be returned by the INITIATE OLC command.

If INITIATE OLC PHASE(PREPARE) fails for all of the IMSs listed in the OLCSTAT data set, no IMS is in an online change state. You may try the online change again with another INITIATE OLC PHASE(PREPARE) command.

If INITIATE OLC PHASE(COMMIT) fails and you want to retry the commit, correct the problem and issue the INITIATE OLC PHASE(COMMIT) command again.

To abort the online change, issue the TERMINATE OLC command. If the INITIATE OLC PHASE(PREPARE) command failed or the INITIATE OLC PHASE(COMMIT) command failed before the commit master updated the OLCSTAT data set, the online change is aborted.

See 'INITIATE OLC error handling' for more details.

X'00000010' X'00004004' The INITIATE OLC command failed because there is no CQS. RM attempted to access the process resource on the resource structure, but it failed because CQS is not available. The online change phase may have succeeded on one or more IMSs.

See 'INITIATE OLC error handling' for more details.

X'00000010' X'0000400C' The INITIATE OLC command failed because it is invalid for an XRF alternate.
X'00000010' X'00004014' The INITIATE OLC command failed because it is invalid for an RSR tracker.
X'00000010' X'0000401C' The INITIATE OLC command failed because it is invalid for an FDR region.
X'00000010' X'00004018' The INITIATE OLC command failed because the RM resource structure is not available. The online change phase may have succeeded on one or more IMSs.

See 'INITIATE OLC error handling' for more details.

X'00000010' X'00004100' The INITIATE OLC PHASE(PREPARE) command is rejected because the resource structure is full. RM failed trying to create the process resource on the resource structure.
X'00000010' X'00004104' The INITIATE OLC command failed because RM is not available. The online change phase may have succeeded on one or more IMSs. Either there is no RM address space, or RM is active but not registered to SCI because CQS or the resource structure is not available.

See 'INITIATE OLC error handling' for more details.

X'00000010' X'00004108' The INITIATE OLC command failed because SCI is not available. The online change phase may have succeeded on one or more IMSs.

See 'INITIATE OLC error handling' for more details.

X'00000010' X'0000410C' The INITIATE OLC command is rejected, because global online change is not enabled. Local online change is enabled. Use the /MODIFY command for local online change. If your IMSplex is made up of some IMSs that support global online change and some that support local online change, route the INITIATE OLC command to an IMS that is enabled for global online change.
X'00000010' X'00004110' The INITIATE OLC command is rejected, because the command does not apply to the online change state of the command master.

INITIATE OLC PHASE(COMMIT) is rejected if the command master is not in an online change prepare state.

INITIATE OLC PHASE(COMMIT) is rejected if routed to an IMS that already successfully completed commit phase 3.

INITIATE OLC PHASE(PREPARE) is rejected if the command master is already in an online change prepare state.

See 'INITIATE OLC error handling' for more details.

X'00000010' X'00004111' The INITIATE OLC command failed because the command master is not in the OLCSTAT data set.
X'00000010' X'00004114' The INITIATE OLC command failed because of an error accessing the OLCSTAT data set. The online change phase may have succeeded on one or more IMSs.

A DFS2843 message is sent to the OM output exit as unsolicited output.

See 'INITIATE OLC error handling' for more details.

X'00000010' X'00004118' The INITIATE OLC command failed because of an error allocating the OLCSTAT data set. The online change phase may have succeeded on one or more IMSs.

A DFS2848 message is sent to the OM output exit as unsolicited output.

See 'INITIATE OLC error handling' for more details.

X'00000010' X'0000411C' The INITIATE OLC command failed because of an error in the OLCSTAT data set contents. One or more of the values is invalid.

A DFS2844 message is sent to the OM output exit as unsolicited output.

X'00000010' X'00004120' The INITIATE OLC command is rejected because an online change command is already in progress on this IMS, which may be INITIATE OLC, TERMINATE OLC, or /DISPLAY MODIFY.
X'00000010' X'00004124' The INITIATE OLC PHASE(PREPARE) command is rejected because another process of the same type is already in progress. Wait until the other process has completed.

If QUERY MEMBER TYPE(IMS) shows no IMS in an online change state, the process resource is residual after an online change error. Clean up the process resource with a TERMINATE OLC command.

|X'00000010' X'0000412C' The OLCSTAT data set contains the name of an IMS other than the IMS processing the online change. Use DFSUOLC0 to correct the data set.
X'00000014' X'00005000' The INITIATE OLC command is rejected because an IMODULE GETSTOR storage request failed.
X'00000014' X'00005004' The INITIATE OLC command failed because a DFSOCMD response buffer could not be obtained. The online change phase may have succeeded on one or more IMSs.

See 'INITIATE OLC error handling' for more details.

X'00000014' X'0000500C' The INITIATE OLC command failed because an AWE could not be obtained.
X'00000014' X'00005100' The INITIATE OLC command failed because of an RM error. The online change phase may have succeeded on one or more IMSs. The RM error may be due to a resource structure failure that causes RM to lose knowledge of an IMSplex-wide process.

See 'INITIATE OLC error handling' for more details.

X'00000014' X'00005104' The INITIATE OLC command failed because of a CQS error. The online change phase may have succeeded on one or more IMSs.

See 'INITIATE OLC error handling' for more details.

X'00000014' X'00005108' The INITIATE OLC command failed because of an SCI error. The online change phase may have succeeded on one or more IMSs.

See 'INITIATE OLC error handling' for more details.

X'00000014' X'00005FFF' The INITIATE OLC command failed because of an internal IMS error. The online change phase may have succeeded on one or more IMSs.

See 'INITIATE OLC error handling' for more details.

INITIATE OLC Completion Codes

The INITIATE command (with the OLC keyword) can result in errors that leave one or more of the IMSs in the IMSplex in various online change states. Table 70 contains the possible completion codes that can be returned as a result of issuing an INITIATE OLC command. The table also includes a brief explanation of the code and provides the error text if applicable.

Table 70. Completion Codes for the INITIATE OLC Command
Completion Code Meaning ERROR TEXT (upper case)
0 The online change prepare phase or commit phase completed successfully.
1 The online change type does not apply to this IMS. For example, an FMTLIB online change does not apply to a DBCTL IMS. This IMS keeps status indicating that it is participating in the online change. This IMS is included in the OLCSTAT data set IMS list after a successful commit phase 1.
2 The online change phase was not attempted by this IMS for one of the following reasons:
  • The online change phase master encountered an error and did not direct this IMS to perform the online change phase.
  • The online change phase master rejected the online change because one or more IMSs are down and the FRCNRML or FRCABND keyword was not specified on the INITIATE OLC PHASE(PREPARE) command. The online change phase master did not direct this IMS to perform the online change phase.
3 This IMS is already in the correct online change state. The INITIATE OLC command must have been retried after a previous INITIATE OLC command resulted in a mix of successes and failures. This IMS keeps status indicating that it is participating in the online change. This IMS is included in the OLCSTAT data set IMS list after a successful commit phase 1.
4 The online change commit phase is incomplete on this IMS. One or more online change commit phases have been completed on this IMS. All online change commit phases were not sent to this IMS due to errors.
57 The queue structure is unavailable. IMS is unable to check if there is a global queue count for transactions to be added, changed, or delted. Commit is not permitted to proceed. The structure may be unavailable for one of the following reasons:
  • CQS is unavailable
  • The MSGQ structure failed and it hasn't been rebuilt yet
  • CQS lost connectivity to the MSGQ structure
THE QUEUE STRUCTURE IS UNAVAILABLE.
|58

An IMS is not registered to RM. An OLCSTAT dataset contains an IMS that is not registered to RM. Initiate fails for that IMS.

If the INITIATE OLC PHASE(PREPARE) command is issued to an IMS that is registered to RM and the OLCSTAT data set contains an IMS system that is not registered to RM, the command fails. The unregistered IMS command line response is cc=58. To initiate online change, you must remove the unregistered IMS from the OLCSTAT data set. To remove the IMS, you need to perform the following steps:

  1. Issue QRY MEMBER TYPE(IMS) SHOW(ATRIB) or SHOW(ALL) to verify the IMS that received the cc=58 was initialized with RMENV=N.
  2. Unlock the OLCSTAT data set using the DFSUOLC0 utility. When online change is in progress it is necessary for the utility to delete the invalid member name.
  3. Delete the invalid IMSID from the OLCSTAT data set using the DFSUOLC0 utility.
  4. Issue TERM OLC to terminate the OLC with the valid IMSs.
  5. Re-issue the OLC.
60 IMODULE GETMAIN storage error.
61 BCB storage error.
62 HIOP storage error.
63 WKAP storage error.
70 Module load error. Module name (8 char), module type (8 char).

The module type can be 'SECURITY'.

71 Module locate error. Module name (8 char), module type (8 char).

The module type can be 'SECURITY'.

72 Randomizer load error. FP area randomizer name (8 char).
80 Data set error. Function (8 char), ddname (8 char), return code (8 bytes), and error detail (8 char).

Function can be one of the following:

  • BLDL

    Data set BLDL error.

  • BUSY

    The data set is busy. The detail contains the jobname that has the data set.

  • DIR

    Data set directory error.

  • EMPTY

    Library is empty.

  • ENQUEUE

    Data set enqueue error.

  • EOF

    Data set end-of-file (EOF) error.

  • OPEN

    Data set open error. Error detail can be 'DLS REG'.

  • READ

    Data set read error.

  • WRITE

    Data set write error.

DDname can be ACBLIBA, ACBLIBB, FMTLIBA, FMTLIBB, MATRIXA, MATRIXB, MODBLKSA, MODBLKSB, or MODSTAT.

Return code is the data set service return code.

Reason code is the data set service reason code.

90 Internal error Module name that detected internal error (8 char), unused (8 char), return code or function code (8 bytes), and error detail (8 char).
91 The online change prepare phase, commit phase, or abort phase timed out before this IMS responded to the online change prepare or commit phase. The online change prepare phase or commit phase may have succeeded on this IMS. Issue QUERY MEMBER TYPE(IMS) to determine the online change state of this IMS.
B0 Resource definition error. Resource type (8 char), resource name (8 char), error detail (16 char).

The resource type can be AREA, DATABASE, DMB, PROGRAM, SECURITY, or TRAN.

The resource name can be a resource name, ACBLIB or MODBLKS.

The error detail can be one of the following:

  • CISIZE GT BSIZE

    An attempt to add the areaname to the DEDB failed. The area's CI size exceeds the Fast Path buffer size (BSIZ=) of the IMS online control region.

  • CPCTRAN CONFLICT

    The online change command attempted to add a transaction name that conflicts with a CPIC transaction name. Tranname specifies the transaction that already exists as a CPIC transaction.

  • DESC CONFLICT

    The online change command attempted to add a transaction name that conflicts with a descriptor name. Tranname specifies the transaction that already exists as a descriptor name.

  • DUPLICATE

    A duplicate area name was found in the named DEDB DBD defined in the IMS system. The area name, that was defined in the DD1 operand on one of the AREA statements in the DBDGEN, is defined in another DEDB DBDGEN or is defined within the DEDB DBDGEN.

  • INCOMPATIBLE

    The DMB in the inactive ACBLIB is not compatible with IMS. The level of the inactive library is not compatible with the current IMS release.

  • INCONSISTENT

    IMS detected an inconsistency between the indicated security module and the definition of the new blocks in the inactive MODBLKS data set. Either the security option was requested on the online change command or the prevailing security option is YES or FORCE. In the module name, nnnns is the specific table name, where s is the suffix.

  • LTERM CONFLICT

    The online change command attempted to add a transaction name that conflicts with a dynamic lterm name.

B0 Resource definition error (continued). Tranname specifies the transaction that already exists as a dynamically created LTERM.
The error detail can be one of the following (continued):
  • MSNAME CONFLICT

    The online change command attempted to add a transaction name that conflicts with an MSNAME. Tranname specifies the transaction that already exists as an MSNAME.

  • NOT DEFINED

    Control block was not defined in the active library during the online prepare phase. This is an internal error that should not occur.

  • NO BLOCKS

    Control blocks were missing from the inactive library during the online prepare phase.

  • NO FP INSTALLED

    An attempt was made to add a data entry database (DEDB) to an IMS system that does not have Fast Path installed.

  • NO OTHREADS

    An attempt was made to add a data entry database (DEDB) to an IMS system that was not initialized with DEDBs. No output threads (OTHREADS) were initialized and no I/O will be possible to the added DEDB.

  • PARTITION EXISTS

    A database partition by that name already exists.

  • RSRC CONFLICT

    The online change command is attempting to add a transaction name that conflicts with another message destination resource in the Resource Manager (RM). The resource can be a LTERM, CPIC transaction, MSNAME, or descriptor. Tranname specifies the transaction that already exists as another resource type.

  • UNSUPPORTED MSDB

    The online change attempted to add an MSDB or change a DEDB to an MSDB, which is not permitted.

B1 Resource state error.

The online change phase failed on this IMS because of the state of the specified resource.

Many of the resource states indicate work is in progress for resources to be changed or deleted by online change. Online change commit detected a resource in a state that results in commit failure. This is the first resource for which an error is detected. IMS is returned to an online change prepare state. Issue a /DISPLAY MODIFY command to display the work in progress for resources to be changed or deleted by online change. Resolve the work in progress, then attempt the INITIATE OLC PHASE(COMMIT) command again.

Resource type (8 char), resource name (8 char), error detail (16 char).

The resource name is the name of the resource as it is defined to IMS, such as the database name, the program name, or the transaction name.

The resource type can be DATABASE, DMB, FORMAT, PROGRAM, PSB, RTCODE, or TRAN.

B1 Resource state error. The error detail can be one of the following:
  • ACTIVE

    The routing code rtcode is active.

  • AREA OPEN

    An area associated with the FP DEDB is open.

  • AREA STARTED

    An area associated with the FP DEDB is started.

  • CONVERSATION

    The transaction to be changed or deleted or the transaction referencing a program or database to be changed or deleted is in conversation.

  • DBD ACTIVE

    A /DBDUMP command is active for the database.

  • DBR ACTIVE

    A /DBRECOVERY command is active for the database.

  • DBR NEEDED

    A /DBRECOVERY command is needed for the database resource. Online change was initiated to either change or delete one or more HALDBs which have not been taken off-line with a /DBR command.

  • DEP REGS ACTIVE

    Dependent regions using the FP DEDB are active.

B1 Resource state error (continued). Error detail (continued):
  • DYNAMIC OR CPIC

    The transaction being added already exists and is not dynamic or CPIC. This is an internal error that should not occur.

  • INTERNAL ERROR

    The resource control block is not found in the active IMS, or the resource control block already exists. These are internal errors that should not occur.

  • IN USE

    The resource is in use.

    A transaction has queueing in progress (either terminal input program-to-program switch).

    A database is in use.

  • PSB SCHEDULED

    A program referencing a database to be changed or deleted is scheduled.

  • QUEUEING

    Messages are queued to the transaction or program.

  • SCHEDULED

    The named resource (a transaction or program to be changed or deleted, or a program referencing a database to be changed or deleted) is scheduled.

  • SUSPENDED

    The transaction to be changed or deleted is on the suspend queue.

B2 IMS state error. IMS state error (32 char). The IMS state can be one of the following:
  • ABENDED

    This IMS abended since the last successful online change. Online change is not permitted if any IMS abended since the last online change, unless the FRCABND option is specified on prepare. If the online change phase was rejected, issue TERMINATE OLC to abort the online change, correct the problem, and try the online change again. If an online change specified with the FRCABND option succeeds, this IMS may have to coldstart.

  • CHECKPOINT IN PROGRESS

    This IMS has checkpoint in progress.

  • NOT-REACHABLE

    The online change phase is rejected because this IMS is NOT-REACHABLE. The SCI on the OS image where this IMS is active is down. Restart the SCI and re-issue the INITIATE OLC or TERMINATE OLC command.

  • OLC ALREADY COMMITTED

    The online change phase is rejected because online change is already committed. All IMSs have completed commit phase 1 and the OLCSTAT data set was updated.

  • OLC NOT IN PROGRESS

    The online change phase is rejected because this IMS is not in an online change state.

B2 IMS state error (continued). IMS state error (32 char). The IMS state can be one of the following:
  • OLC PHASE IN PROGRESS

    The online change phase is rejected because this IMS has an online change phase already in progress.

  • ORS IN PROGRESS

    The Online change command is rejected because the online recovery service is already in progress.

  • RESOLVE DB INDOUBTS

    This IMS has DB indoubts. You must resolve the DB indoubts either by reconnecting the coordinator controller and IMS or by using an operator command.

  • RESTART IN PROGRESS

    This IMS has restart in progress.

  • RESTART NOT COMPLETE

    This IMS initialized before the online change was initiated, but has not completed restart. The online prepare or abort phase is rejected as long as this IMS is in this state. Cancel this IMS, then abort the online change before attempting the online change prepare phase again.

  • SHUTDOWN

    This IMS shut down normally since the last successful online change. Online change is not permitted if any IMS shut down normally since the last online change, unless the FRCNRML option is specified on prepare. If the online change phase was rejected, issue TERMINATE OLC to abort the online change, correct the problem, and try the online change again. If an online change specified with the FRCNRML option succeeds, this IMS may have to cold start.

INITIATE OLC Error Handling

The INITIATE OLC command can result in errors that leave one or more of the IMSs in the IMSplex in various online change states. Issue the QUERY MEMBER command and the QUERY OLC command to help you determine whether to terminate the online change or try the INITIATE OLC command again.

Before attempting online change, issue the QUERY OLC LIBRARY(OLCSTAT) SHOW(MODID) command to get the current modify id. If the INITIATE OLC command fails, issue the QUERY OLC LIBRARY(OLCSTAT) SHOW(MODID) command again, to see if the modify id is the same. If the modify id increased by 1, the online change is considered to be successfully completed.

If the INITIATE OLC command fails, issue the QUERY MEMBER TYPE(IMS) SHOW(STATUS) command to display the online change state of all the IMSs in the IMSplex. Evaluate the QUERY MEMBER TYPE(IMS) SHOW(STATUS) output to help you to determine what to do:

Errors unique to the processing of this command are returned as a completion code. A completion code is returned for an IMS participating in the online change phase. See Table 70 for a listing of the completion codes that may be returned on an INITIATE OLC command.

Examples for INITIATE OLC Command

The following are examples of the INITIATE OLC command.

Example 1 for INITIATE OLC Command

TSO SPOC input:

INITIATE OLC PHASE(PREPARE) TYPE(MODBLKS,ACBLIB)

TSO SPOC output:

MbrName  Member     CC ACBLIB FMTLIB MODBLKS    ModId
IMS3     IMS2        0                                         
IMS3     IMS3        0      B      A       B        1          
IMS3     SYS3        0  

OM API input:

CMD (INITIATE OLC PHASE(PREPARE) TYPE(MODBLKS,ACBLIB))

OM API output:

<imsout>
<ctl>
<omname>OM1OM   </omname>
<omvsn>1.1.0</omvsn>
<xmlvsn>1   </xmlvsn>
<statime>2003.163 15:40:53.336327</statime>
<stotime>2003.163 15:41:08.282146</stotime>
<staseq>B7C4AC11FED070C6</staseq>
<stoseq>B7C4AC203FB220C1</stoseq>
<rqsttkn1>USRT011 10084053</rqsttkn1>
<rc>0200000C</rc>
<rsn>00003000</rsn>
</ctl>
<cmderr>
<mbr name="IMS2    ">
<typ>IMS     </typ>
<styp>DBDC  </styp>
<rc>02000004</rc>
<rsn>00001008</rsn>
</mbr>
<mbr name="SYS3    ">
<typ>IMS     </typ>
<styp>DBDC   </styp>
<rc>02000004</rc>
<rsn>00001008</rsn>
</mbr>
</cmderr>
<cmd>
<master>IMS3    </master>
<userid>USRT011 </userid>
<verb>INIT</verb>
<kwd>OLC            </kwd>
<input>INITIATE OLC PHASE(PREPARE) TYPE(MODBLKS,ACBLIB)</input>
</cmd>
<cmdrsphdr>
<hdr slbl="MBR"    llbl="MbrName" scope="LCL" sort="n" key="0" scroll="yes" len="8"
 dtype="CHAR" align="left" />
<hdr slbl="IMSMBR" llbl="Member"  scope="LCL" sort="a" key="1" scroll="no"  len="8"
 dtype="CHAR" align="left" />
<hdr slbl="CC"     llbl="CC"      scope="LCL" sort="n" key="0" scroll="yes" len="4"
 dtype="INT"  align="right" />
<hdr slbl="ACBL"   llbl="ACBLIB"  scope="GBL" sort="n" key="0" scroll="yes" len="1"
 dtype="CHAR" align="right" />
<hdr slbl="FMTL"   llbl="FMTLIB"  scope="GBL" sort="n" key="0" scroll="yes" len="1"
 dtype="CHAR" align="right" />
<hdr slbl="MODB"   llbl="MODBLKS" scope="GBL" sort="n" key="0" scroll="yes" len="1"
 dtype="CHAR" align="right"/>
<hdr slbl="MODI"   llbl="ModId"   scope="GBL" sort="n" key="0" scroll="yes" len="8"
 dtype="CHAR" align="right"/>
</cmdrsphdr>
<cmdrspdata>
<rsp>MBR(IMS3    ) IMSMBR(SYS3    ) CC(   0) </rsp>
<rsp>MBR(IMS3    ) IMSMBR(IMS2    ) CC(   0) </rsp>
<rsp>MBR(IMS3    ) IMSMBR(IMS3    ) CC(   0) ACBL(B) FMTL(A) MODB(B) MODI(    1)
</rsp>
</cmdrspdata>
</imsout>

Explanation: The IMSplex consists of three IMSs -- SYS3, IMS2, and IMS3. All three of the IMSs complete the online change prepare phase successfully for the MODBLKS library. IMS3 is the master of the prepare phase. The current online change libraries are ACBLIBB, FMTLIBA, and MODBLKSB. The current modify id is 1.

Example 2 for INITIATE OLC Command

TSO SPOC input:

INITIATE OLC PHASE(COMMIT)

TSO SPOC output:

MbrName  Member     CC ACBLIB FMTLIB MODBLKS    ModId 
IMS3     IMS2        0                                
IMS3     IMS3        0      B      A       A        2 
IMS3     SYS3        0                               

OM API input:

CMD (INITIATE OLC PHASE(COMMIT))

OM API output:

<imsout>
<ctl>
<omname>OM1OM   </omname>
<omvsn>1.1.0</omvsn>
<xmlvsn>1   </xmlvsn>
<statime>2002.163 16:26:14.660563</statime>
<stotime>2002.16316:26:22.293891</stotime>
<staseq>B7C4B635409D30C6</staseq>
<stoseq>B7C4B63C88383347</stoseq>
<rqsttkn1>USRT011 10092614</rqsttkn1>
<rc>0200000C</rc>
<rsn>00003000</rsn>
</ctl> 
<cmderr>
<mbr name="IMS2    ">
<typ>IMS     </typ>
<styp>DBDC   </styp>
<rc>02000004</rc>
<rsn>00001008</rsn>
</mbr>
<mbr name="SYS3    ">
<typ>IMS     </typ>
<styp>DBDC    </styp>
<rc>02000004</rc>
<rsn>00001008</rsn>
</mbr>
</cmderr>
<cmd>
<master>IMS3    </master>
<userid>USRT011 </userid>
<verb>INIT</verb>
<kwd>OLC            </kwd>
<input>INITIATE OLC PHASE(COMMIT) </input>
</cmd>
<cmdrsphdr>
<hdr slbl="MBR"    llbl="MbrName" scope="LCL" sort="n" key="0" scroll="yes" len="8"
 dtype="CHAR" align="left" />
<hdr slbl="IMSMBR" llbl="Member"  scope="LCL" sort="a" key="1" scroll="no"  len="8"
 dtype="CHAR" align="left" />
<hdr slbl="CC"     llbl="CC"      scope="LCL" sort="n" key="0" scroll="yes" len="4"
 dtype="INT"  align="right" />
<hdr slbl="ACBL"   llbl="ACBLIB"  scope="GBL" sort="n" key="0" scroll="yes" len="1"
 dtype="CHAR" align="right" />
<hdr slbl="FMTL"   llbl="FMTLIB"  scope="GBL" sort="n" key="0" scroll="yes" len="1"
 dtype="CHAR" align="right" />
<hdr slbl="MODB"   llbl="MODBLKS" scope="GBL" sort="n" key="0" scroll="yes" len="1"
 dtype="CHAR" align="right"/>
<hdr slbl="MODI"   llbl="ModId"   scope="GBL" sort="n" key="0" scroll="yes" len="8"
 dtype="CHAR" align="right" />
</cmdrsphdr>
<cmdrspdata>
<rsp>MBR(IMS3    ) IMSMBR(SYS3    ) CC(   0) </rsp>
<rsp>MBR(IMS3    ) IMSMBR(IMS2    ) CC(   0) </rsp>
<rsp>MBR(IMS3    ) IMSMBR(IMS3    ) CC(   0) ACBL(B) FMTL(A) MODB(A) MODI(      2)
</rsp>
</cmdrspdata>
</imsout>

Explanation: A global online change commit is initiated and completes successfully.

| | |

INITIATE OLREORG

|

The INITIATE OLREORG command causes HALDB OLR to begin or resume on the partition |or partitions that are specified by partname.

|

|The INITIATE OLREORG command might be routed to one or more of the IMSs in the IMSplex |depending on the ROUTE specifications. The default for the command |is ROUTE=ALL which means that the command is routed to all active DB/DC |and DBCTL IMSs in the IMSplex. The first IMS to successfully process |the INITIATE OLREORG command owns the online reorganization and the command fails |on all of the other IMS subsystems where the command has been routed.|

|

Part of the HALDB OLR processing involves: |

| |

If the partition is tracked at an RSR tracker site, the OPTION |value (DEL or NODEL) that is in effect at the completion of the HALDB OLR also |determines whether the inactive data sets for the shadow partition |are deleted at the completion of the tracking of the reorganization.

|

When HALDB OLR completes, a message indicating that the reorganization |has completed is sent to the System Console.

|

The output for this command is defined in XML and is available |to automation programs that communicate with OM if the command is |issued as a type-2 command.

|

Related Reading: Refer to the Appendix of the IMS Version 9: Common Service Layer Guide and Reference for |sample XML for IMS commands.

|
|
NAME()
|
|For |the type-2 version of this command, you can specify one or more HALDB |partitions to HALDB OLR. | |

|For the type-1 version of the command, you can specify |only one NAME keyword for each of these commands that you issue.|

| |
|
PARTNAME
|
The name of a HALDB partition. Only PHDAM or PHIDAM HALDB |partition names can be specified. Also, the use of wildcard character |(*), for example DBPART* or just *, is NOT allowed. |
|
| |
|
SET()
|
Allows you to specify the RATE option as described here. | |
| |
RATE()
|
Allows you to specify the RATE at which |the HALDB OLR is to be run. | |
|
rate
|
You can specify a rate value of 1 to 100. An online reorganization's |impact on the system is affected by the available system resources, |by total system utilization (including other online reorganizations), |by total logging volume, by log contention, and by the intensity |at which this reorganization was requested to run. These same factors |also affect the speed at which the reorganization runs. | |

A rate value of 50 specifies that 50% of the elapsed time be |spent copying records and the remaining 50% be spent in a delay. |This causes the reorganization to run approximately twice as long |as it would have run with a rate value of 100.

| |

You can use the RATE parameter to control the intensity at which |the reorganization runs. This can affect both the reorganization's |speed and its impact on the rest of the system. The value you specify |for rate is the percentage of elapsed time to be devoted to copying |records. The remaining time is to be an intentionally introduced |delay in the copying process that minimizes the reorganization's |impact on other IMS work and on the whole system.

| |

RATE(100) is the default.

|
|
|
| |
|
|
OPTION()
|
Allows the specification of the DEL/NODEL options as described here. |If the partition is tracked at an RSR tracker site, the OPTION value |(DEL or NODEL) in effect at the completion of the online reorganization |also determines whether the inactive data sets for the shadow partition |are deleted at the completion of the tracking of the reorganization. | |
|
DEL
|
Indicates the deletion of the inactive data sets is to be attempted |when the online reorganization completes. The attempted deletion |occurs regardless of who created the data sets or when the data |sets were created. DEL is the default. |
|
NODEL
|
|Indicates that the deletion of the inactive data |sets is not to be attempted at online reorganization |completion.| |
|
|
|
|
|Attention: If the HALDB OLR is stopped prior to completion, |the OPTION(NODEL) if specified is not retained or remembered by IMS. OPTION(NODEL) must be specified on the INITIATE OLREORG command that is issued to resume the stopped online reorganization. OPTION(NODEL) can also be specified on the UPDATE OLREORG command.|
| | |

Command Responses for /INITIATE OLREORG

|

When the /INITIATE OLREORG command is issued as a type-1 command, the command response |is returned in a message format.

|

|When the command completes successfully, a DFS0725I |message with a completion code of 0 is returned to the system console |and master terminal. If the command results in an error, a non-zero |completion code or an error message is returned to the master terminal |and system console.|

|

If the command results in an error, an error message is returned |to the entering terminal. One or more of the following messages |might also be returned: |

|
DFS0725I INITIATE|UPDATE|TERMINATE OLREORG COMMAND FOR DB dbnamexx COMPLETE.
|CC=  nn 
|  where: dbnamexx is the HALDB partition name entered on the command
|         nn       is the completion code
|
|DFS058  - INITIATE COMMAND IN PROGRESS
|DFS107  - REQUIRED KEYWORD NOT PRESENT
|DFS110  - COMMAND KEYWORD OLREORG INVALID FOR yyyyyyyy (tracker, XRF alt)
|DFS128  - TOO FEW KEYWORDS
|DFS136  - COMMAND xxxxxxxxxxx INVALID FOR yyyyyyyy (tracker, XRF alt)
|DFS165  - COMMAND VERB IS INVALID
|DFS2026 - NO WKAP STORAGE
|DFS2038 - INSUFFICIENT STORAGE AVAILABLE TO PROCESS COMMAND
|DFS2262 - TOO MANY DATABASE PARAMETERS
|DFS3630 - GENERIC PARAMETER NOT ALLOWED
|

For more complete information about these messages, see IMS Version 9: Messages and Codes, Volume 2.

|| | |

INITIATE OLREORG Output Fields

|

|This section describe the responses from the |OM API for the INITIATE OLREORG command. Table 71 shows the INITIATE OLREORG output fields. The columns in the table are as follows: |

|
|
Short |Label
|
Contains the short label generated in the XML output. | |

Note: This field does not apply |to the /INITIATE or to the /INIT command.

|
|
Show Keyword
|
Identifies keyword on the command that caused the field to |be generated. |
|N/A appears for output fields that are always returned. |
|
Meaning
|
Provides a brief description of the output field. |
|
| | |||||||||||||||||||||||||||
Table 71. Output Fields for INITIATE OLREORG Command
|Short Label Show Keyword Meaning
PART N/A Partition name.
|MBR N/A The IMS that processed the command and built |the command response line.
CC N/A Completion code.
| | |

INITIATE OLREORG Return and Reason Codes

|

The OM return and reason codes that might |be returned as a result of the INITIATE OLREORG command are standard for all commands entered through the |OM API.

|

Table 72 includes the return |and reason codes and a brief explanation of the INITIATE OLREORG command.

Table 72. Return and Reason Code for the INITIATE OLREORG Command
|Return Code |Reason Code |Meaning
|X'00000000' |X'00000000' |The INITIATE OLREORG command completed successfully.
|X'00000010' |X'0000400C' |Command issued on an XRF alternate.
| |X'00004014' |Command issued on an RSR tracker.
| |X'00004030' |Command Invalid for LSO=Y.
|X'00000014' |X'00005000' |A GETMAIN error occurred.
| | |

INITIATE OLREORG Completion Codes

|

Table 73 includes |an explanation of the completion codes. Errors unique to the processing |of INITIATE OLREORG command are returned as completion codes. A completion code |is returned for each action against a HALDB partition.

| |||||||||||||||||||||||||||||||
Table 73. Completion Codes for the INITIATE OLREORG Command
Completion Code Meaning
0 The INITIATE OLREORG command completed successfully for the partition.
10 Resource name invalid.
14 Resource not a partition name.
1C Resource is a partitioned secondary index.
20 HALDB OLR is already in progress.
| |

Examples for INITIATE OLREORG Command

|

The following are examples of the INITIATE OLREORG command.

| |

Example 1 for INITIATE OLREORG Command

|

|Entry ET: |

|
/INITIATE OLREORG NAME(HALDBPRT) SET(RATE(50))
| |

|Response ET: |

|
DFS058I INITIATE COMMAND IN PROGRESS 
| |

|System Console/MTO: |

|
DFS0725I INITIATE OLREORG COMMAND FOR DB HALDBPRT COMPLETE. CC= 0
| |

Explanation: Issue the INITIATE OLREORG command to start HALDB OLR for partition HALDBPRT at the |entering terminal. The DFS058I command response is returned to the |entering terminal followed by the DFS0725I message to the system |console and MTO.

| |

Example 2 for INITIATE OLREORG Command

|

Entry ET: |

|
/INIT OLREORG NAME(PDHDOKA) SET(RATE(5))
|

Response ET: |

|
DFS058I INITIATE COMMAND IN PROGRESS
|

Response MTO/System console: |

|
DFS2970I - OLR STARTED FOR NAME=PDHDOKA
|DFS0725I INITIATE  OLREORG COMMAND FOR DB PDHDOKA  COMPLETE. CC=   0
|

Explanation: The INIT OLREORG command for partition PDHDOKA is issued from a terminal, |resulting in the message, DFSO58I INITIATE COMMAND IN PROGRESS being |sent to that entering terminal.

|

When OLR is started successfully, the DFS0725I and the DFS2970 |messages are sent to the system console and to the MTO.

| |

Example 3 for INITIATE OLREORG Command

|

|TSO SPOC Input: |

|
INIT OLREORG NAME(PDHDOKA,PDHDOKB) SET(RATE(5))
| |

|TSO SPOC Output: |

|
    Partition MbrName    CC
|    PDHDOKA   IMSA        0 
|    PDHDOKA   IMS1       C3
|    PDHDOKB   IMSA        0
|    PDHDOKB   IMS1       C3
| |

OM API Input: |

|
|CMD (INIT OLREORG NAME(PDHDOKA,PDHDOKB) SET(RATE(5)))|
|

OM API Output: |

|
 
|<imsout> 
|<ctl>
|<omname>OM1OM   </omname>
|<omvsn>1.2.0</omvsn>
|<xmlvsn>1   </xmlvsn>
|<statime>2003.168 21:19:06.827362</statime> 
|<stotime>2003.168 21:19:07.036292</stotime>
|<staseq>B99629BFEC66256E</staseq>
|<stoseq>B99629C01F684F44</stoseq>
|<rqsttkn1>USRT005 10141906</rqsttkn1> 
|<rc>00000000</rc> 
|<rsn>00000000</rsn>
|</ctl> 
|<cmd> 
|<master>IMSA    </master> 
|<userid>USRT005 </userid> 
|<verb>INIT</verb>
|<kwd>OLREORG         </kwd>
|<input>INIT OLREORG NAME(PDHDOKA,PDHDOKB) SET(RATE(5)) </input>
|</cmd>
|<cmdrsphdr>
|<hdr slbl="PART" llbl="Partition" scope="LCL" sort="A" key="1"
| scroll="NO" len="9" dtype="CHAR" align="left" /> 
|<hdr slbl="MBR" llbl="MbrName" scope="LCL" sort="N" key="0" scroll="NO"
| len="8" dtype="CHAR" align="left" />
|<hdr slbl="CC" llbl="CC" scope="LCL" sort="N" key="0" scroll="YES" 
| len="4" dtype="INT" align="right" />
|</cmdrsphdr>                                                                   <cmdrspdata>                                                                   <rsp> <rsp> PART(PDHDOKA ) MBR(IMSA    ) CC(   0) </rsp>
|<rsp> PART(PDHDOKB ) MBR(IMSA    ) CC(   0) </rsp>
|<rsp> PART(PDHDOKA ) MBR(IMS1    ) CC(  C3) </rsp>
|<rsp> PART(PDHDOKB ) MBR(IMS1    ) CC(  C3) </rsp>
|</cmdrspdata> 
|</imsout>
|

Explanation: The INIT OLREORG command is issued from TSO SPOC for partitions PDHDOKA and |PDHDOKB. The command is routed to IMSA and IMS1. The command is |successful at IMSA for both partitions. The command is not successful |for both partitions at IMS1.

Go to the previous page Go to the next page

IBM Confidential

Downloads | Library | Support | Support Policy | Terms of use | Feedback
Copyright: IBM Corporation 1974, 2004 Copyright IBM Corporation 1974, 2004  timestamp Last updated: March, 2004