>>-+-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-'
|| .-,--------. | V | |>>-+-INITIATE--+--OLREORG--NAME--(----partname-+--)-------------> | +-INIT------+ | +-/INITIATE-+ | '-/INIT-----' | | .-SET(RATE(100))--. .-OPTION(DEL)---. |>--+-----------------+--+---------------+---------------------->< | '-SET(RATE(rate))-' '-OPTION(NODEL)-' |
Table 66 and Table 67 lists the environments (DB/DC, DBCTL, and DCCTL) from which the INITIATE command and keywords can be issued.
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 |
|Command |/ Keywords | |DB/DC | |DBCTL | |DCCTL |
---|---|---|---|
|OLREORG | | X | |X | | |
|NAME | |X | |X | | |
|SET | |X | |X | | |
|OPTION | |X | |X | | |
|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.
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.
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:
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.
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.
Table 68 shows the output fields for an INITIATE OLC command. The columns in the table are as follows:
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. |
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.
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.
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:
|
|
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:
|
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:
|
|
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:
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:
|
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):
|
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:
|
B1 | Resource state error (continued). | Error detail (continued):
|
B2 | IMS state error. | IMS state error (32 char). The IMS
state can be one of the following:
|
B2 | IMS state error (continued). | IMS state error (32 char). The IMS
state can be one of the following:
|
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:
If the INITIATE OLC PHASE(PREPARE) command failed on all of the IMSs in the IMSplex, none of them are in an online change state. This QUERY OLC LIBRARY(OLCSTAT) SHOW(MODID) command output shows the same modify id as the QUERY OLC LIBRARY(OLCSTAT) SHOW(MODID) command issued before the INITIATE OLC PHASE(PREPARE) command. If you want to attempt online change again, issue another INITIATE OLC PHASE(PREPARE) command.
If an INITIATE OLC PHASE(COMMIT) command successfully completes commit phase 3 on all the IMSs but fails due to an error such as a command timeout, then no IMS will remain in an online change state. The QUERY MEMBER TYPE(IMS) SHOW(STATUS) command output shows no IMS in an online change state, so no further action is needed. The online change successfully completed.
If an INITIATE OLC PHASE(PREPARE) command failed for all the IMSs in the IMSplex, but RM still has information about the process, then the online change needs to be terminated. This is a very rare case where the command master initiates the online change process with RM, an error occurs, or the online change prepare phase fails on all the IMSs, and the command master in unable to terminate the online change process with RM. RM issues a CSLR2200 message but no CSLR2201 message. The QUERY MEMBER TYPE(IMS) SHOW(STATUS) command output shows no IMS in an online change state. If you try to initiate an online change again with another INITIATE OLC PHASE(PREPARE) command, it is rejected. You must terminate the online change with a TERMINATE OLC command.
If the INITIATE OLC PHASE(PREPARE) command fails and some of the IMSs show a status of online change prepare complete (OLCPREPC), then the prepare phase succeeded on some of the IMSs. You must terminate the online change with the TERMINATE OLC command. The IMSs that have a status of OLCPREPC remain in an online change prepare complete state until you abort the online change.
If the INITIATE OLC PHASE(PREPARE) or INITIATE OLC PHASE(COMMIT) command fails and all of the IMSs are in a prepare complete state (OLCPREPC) and the master shows a global status of online change prepare complete (OLCPREPC), then the prepare succeeded. You can issue INITIATE OLC PHASE(COMMIT) if you want to proceed with the online change. You can issue TERMINATE OLC if you want to abort the online change.
If the INITIATE OLC PHASE(PREPARE) command flavor did not apply to any IMS in the IMSplex, the command is rejected, but all of the IMSs show a status of OLCPREPC. For example, if the IMSplex consists of only DBCTL subsystems, then the INITIATE OLC PHASE(PREPARE) TYPE(FMTLIB) command does not apply to any of the IMSs and is rejected. However, all of the IMSs will show a status of OLCPREPC, indicating they are participating in the online change. If this situation occurs, you must terminate the online change. INITIATE OLC PHASE(COMMIT) will be rejected, since the online change applies to no IMS in the IMSplex.
If an INITIATE OLC PHASE(COMMIT) command fails during commit phase 1, some of the IMSs may be in a prepare complete state (OLCPREPC) and some of the IMSs may be in a commit phase 1 complete state (OLCCMT1C). The commit phase failed before the master updated the OLCSTAT data set, so the online change is not committed. You may correct the problem and try the commit again with the INITIATE OLC PHASE(COMMIT) command. Or, you may decide to abort the online change with the TERMINATE OLC command.
The IMSs that are in an online change state remain in an online change state until you abort the online change or commit the online change.
If an INITIATE OLC PHASE(COMMIT) command fails after commit phase 1 is completed, all of the IMSs are in a commit phase 1 complete state (OLCCMT1C).
If the error occurs before the master updates the OLCSTAT data set, then the online change is not yet successful. You may abort the online change with the TERMINATE OLC command or attempt the commit again with another INITIATE OLC PHASE(COMMIT) command.
If the error occurs after the master updates the OLCSTAT data set, then the online change is successful. You may not abort the online change. You must attempt the commit again with another INITIATE OLC PHASE(COMMIT) command to finish up the online change. The INITIATE OLC PHASE(COMMIT) command finishes the online change by completing commit phase 2.
The IMSs that are in an online change state remain in an online change state until you abort the online change or commit the online change.
You can determine if the OLCSTAT data set has been updated by checking the modify id. Issue the QUERY OLC LIBRARY(OLCSTAT) SHOW(MODID) command. Check if the modify id returned is different from the modify id returned by the INITIATE OLC PHASE(PREPARE) command, or the modify id returned by a QUERY OLC LIBRARY(OLCSTAT) SHOW(MODID) command issued before the INITIATE OLC PHASE(COMMIT) command.
If an INITIATE OLC PHASE(COMMIT) command fails during commit phase 2, some of the IMSs may be in a commit phase 1 complete state (OLCCMT1C) and some may have completed commit phase 2 and be in a commit phase2 complete state (OLCCMT2C). The INITIATE OLC PHASE(COMMIT) command failed after commit phase 1 completed on all of the IMSs and the master updated the OLCSTAT data set. Once the OLCSTAT data set is updated, the online change is considered to be successful and cannot be aborted. You must finish the online change commit phase 2 by issuing the INITIATE OLC PHASE(COMMIT) command again. The INITIATE OLC PHASE(COMMIT) command finishes the online change by completing commit phase 2.
The IMSs that are in an online change state remain in an online change state until you finish the online change with an INITIATE OLC PHASE(COMMIT) command.
If an INITIATE OLC PHASE(COMMIT) command fails during commit phase 2 or commit phase 3, all of the IMSs may end up in a commit phase 2 complete state (OLCCMT2C). The INITIATE OLC PHASE(COMMIT) command failed after commit phase 1 completed on all of the IMSs and the master updated the OLCSTAT data set. Once the OLCSTAT data set is updated, the online change is considered to be successful and can not be aborted. you must finish the online change commit phase 2 and commit phase 3 by issuing the INITIATE OLC PHASE(COMMIT) command again.
The IMSs that are in an online change state remain in an online change state until you finish the online change with an INITIATE OLC PHASE(COMMIT) command.
If an INITIATE OLC PHASE(COMMIT) command fails during commit phase 3, some of the IMSs may be in a commit phase 2 complete state (OLCCMT2C) and some may have completed commit phase 3 and no longer be in an online change state. The INITIATE OLC PHASE(COMMIT) command failed after commit phase 1 completed on all of the IMSs and master updated the OLCSTAT data set. Once the OLCSTAT data set is updated, the online change is considered to be successful and can not be aborted. You must finish the online change commit phase 3 by issuing the INITIATE OLC PHASE(COMMIT) command again, routing it to an IMS that is still in a commit phase 2 complete state. The INITIATE OLC PHASE(COMMIT) command finishes the online change by completing commit phase 3.
The IMSs that are in an online change state remain in an online change state until you finish the online change with an INITIATE OLC PHASE(COMMIT) command.
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.
The following are examples of the 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.
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.
| | |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.
||For the type-1 version of the command, you can specify |only one NAME keyword for each of these commands that you issue.|
| |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.
|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.
|| | ||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: |
|Note: This field does not apply |to the /INITIATE or to the /INIT 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. | |
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.
|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. |
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.
| |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. | |
The following are examples of the 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.
| |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.
| ||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.