2.84 pdorbegin (Commit a database for online reorganization)

Organization of this section
(1) Function
(2) Executor
(3) Format
(4) Options
(5) Rules
(6) Notes

(1) Function

The pdorbegin command places specified original RDAREAs and replica RDAREAs of a specified generation in the replica group in online reorganization hold status.

When a table is specified, the command processes all RDAREAs related to that table and places each original RDAREA and the specified generation of replica RDAREAs in the replica group in online reorganization hold status. For details about related RDAREAs, see 2.98 pdrdrefls (Display information about related RDAREAs). To also process the related areas in the constraint definition, specify the -c option. For details, see the description of the -c option.

Once you execute the pdorbegin command, any transaction that accesses an RDAREA in the replica group that contains the specified original RDAREA is placed in wait status until the pdorchg command has executed.

To release online reorganization hold status, specify the -u option.

You can execute the pdorbegin command only when HiRDB Staticizer Option has been installed and the pd_max_reflect_process_count and pd_inner_replica_control operands have both been specified in the system definition.

(2) Executor

HiRDB administrator

(3) Format

(a) Format 1 (for placing RDAREAs in online reorganization hold status and releasing them from this status):

 pdorbegin {-r original-RDAREA-name[,original-RDAREA-name]...

            |-t [authorization-identifier.]table-identifier

                [-s server-name[,server-name]...][-c constraint-type]}

          [-q generation-number ] [-w lock-release-wait-time] [-e] [-u] [-W execution-monitoring-interval]

(b) Format 2 (for releasing a shared RDAREA or a shared table from online reorganization hold status (applicable to a HiRDB parallel server configuration only)):

 pdorbegin {-r original-RDAREA-name[,original-RDAREA-name]...

            |-t [authorization-identifier.]table-identifier[-c constraint-type]}

          [-s server-name[,server-name]...]

          [-q generation-number ] [-w lock-release-wait-time] -u [-W execution-monitoring-interval]

(4) Options

(a) -r original-RDAREA-name[,original-RDAREA-name]... ~<identifier> ((1-30))

Specifies the names of RDAREAs that are to be placed in online reorganization hold status.

Rules
  1. For the rules for specifying RDAREAs, see 1.5.2 Specification of RDAREAs in operation commands and utilities.
  2. Specify RDAREAs for which replica definition is supported. An error results if replica definition is not supported for a specified RDAREA. For details about the RDAREAs for which replica definition is supported, see the HiRDB Version 9 Staticizer Option Description and User's Guide.
  3. An error results if all replica RDAREAs have been deleted or there is no replica RDAREA for a specified RDAREA. If a batch specification is used that includes an original RDAREA whose replica RDAREAs have all been deleted or an RDAREA without a replica RDAREA, the command ignores the batch specification and resumes processing.
  4. When a batch specification is used, the command ignores any original RDAREA whose replica RDAREAs have all been deleted and any RDAREA without a replica RDAREA and continues processing.
(b) -t [authorization-identifier.]table-identifier

~<identifier> ((authorization identifier: 1-30, table identifier: 1-30))

Specifies the name of a table that is to be placed in online reorganization hold status.

The command processes the RDAREAs related to the specified table and places each original RDAREA and the specified generation of replica RDAREAs in the replica group in online reorganization hold status.

Rules
  1. When the -t option is specified, the number of RDAREAs storing the specified table must not exceed 4,096. If the maximum number of RDAREAs is exceeded, the KFPH27051-E message is issued. If the total number of RDAREAs exceeds 4,097, execute the pdorbegin command with the -r option specified for each RDAREA.
  2. When the authorization identifier is omitted, the pdorbegin command assumes the authorization identifier set in the PDUSER environment variable at the time of execution. If the PDUSER environment variable has not been set or a simple authentication keyword is specified in both the authorization identifier and password in the PDUSER environment variable#, the command assumes the user name specified in the logon window. The following table shows the authorization identifier that takes effect depending on the specifiation of the -t option and the PDUSER environment variable:
    Authorization identifier in the -t optionPDUSER environment variable settingAuthorization identifier that takes effect
    Specified--Authorization identifier specified in the -t option
    Omittedauthorization-identifier[/password]Authorization identifier specified in the PDUSER environment variable
    Not specifiedUser name specified in the login window
    Simple authentication keywords were specified in both the authorization identifier and the password
    #
    The PDUSER environment variable setting is used regardless of whether the facility for simple authentication of OS login users is enabled (pd_os_authenticate operand value in the system common definition). For details about the simple authentication keywords, see Facility for simple authentication of OS login users in the HiRDB Version 9 System Operation Guide.

  3. If the authorization identifier or table identifier is enclosed in double quotation marks ("), the command treats it as being case sensitive. If it is not enclosed in double quotation marks ("), the command treats it as in all uppercase letters. If you are using sh (Bourne shell), csh (C shell), or ksh (Korn shell), you must enclose the entire identifier in single quotation marks (').
  4. An error results if any of the following tables is specified:
    • Viewed tables
    • Data dictionary tables
    • Temporary tables
(c) -s server-name[,server-name]... ~<identifier> ((1-8))

Specifies servers for which the processing is to be performed. The following guidelines apply to specifying the -s option:

Rules
  1. When this option is omitted, the command processes all servers that contain the RDAREAs to be processed.
  2. If a shared RDAREA is to be placed in online reorganization hold status, specify the -s option together with the -u option because all back-end servers must be processed in the batch mode. When the -u option is omitted, specifying the -s option results in an error.
  3. You can specify a maximum of 128 server names. Specifying more than 128 server names results in an error.
(d) -q generation-number ~<unsigned integer> ((1-10)) <<1>>

Specifies the generation number of the replica RDAREAs in the replica group that are to be placed in online reorganization hold status.

You cannot specify 0, which is the generation number of original RDAREAs.

(e) -w lock-release-wait-time ~<unsigned integer> ((0-3600))

Specifies the lock-release wait time in seconds for the online reorganization hold.

When this option is omitted, the command assumes the value of the pd_lck_wait_timeout operand in the system definition. If the value of the pd_lck_wait_timeout operand is 0 in the system definition, the command assumes 3,600.

(f) -u

Specifies that online reorganization hold is to be released. When this option is specified, the -r and -t options must also be specified.

When the processing target includes a shared RDAREA, processing is performed at all back-end servers in the batch mode. If it is not possible to release all the target RDAREAs from online reorganization hold status, an error results. If the shared RDAREA needs to be released from online reorganization hold status for each server for reasons such as a specific back-end server being inactive, you can specify the -s option to release the online reorganization hold.

When you release online reorganization hold, you must specify the same resources as when the processing target was placed in online reorganization hold status (otherwise, an error occurs). The following table shows the relationships between the options specified when the processing target was placed in online reorganization hold status and the options that are specified when it is released from online reorganization hold status:

pdorbegin command options when online reorganization hold is releasedpdorbegin command options when the processing target was placed in online reorganization hold status
-r RDAREA-t table-t table -c ref
-r RDAREA -uY#NN
-t table -uNYN
-t table -c refNNY
Legend:
Y: Can be executed
N: Cannot be executed (results in an error)
#: If multiple RDAREAs were placed in online reorganization hold status, you must specify all those RDAREAs when they are released from online reorganization hold status. However, if the RDAREAs cannot be released from online reorganization hold status because an error (such as a failure) was detected that resulted in a command error, specify only those RDAREAs that are not affected by the failure and execute the command with the -u option specified to release those RDAREAs from online reorganization hold status. After the failure has been recovered, execute the command with the -u option specified to release the remaining RDAREAs from online reorganization hold status.
(g) -c constraint-type

Specifies that the associated RDAREAs in the constraint definition are also to be placed in online reorganization hold status. When you specify this option, you must also specify the -t option. Specifying this option without specifying the -t option results in an error.

ref
Specifies that RDAREAs associated with referential constraints are also to be placed in online reorganization hold status. This refers to RDAREAs that contain a referencing table or a referenced table that must be handled together with generation numbers. For details about how to handle referential constraints, see the manual HiRDB Version 9 Installation and Design Guide.
(h) -e

Specifies that only the updated columns are to be applied during reflection processing for online reorganization when the pdorend command is executed. For notes about the -e option specification, see the manual HiRDB Version 9 Staticizer Option Description and User's Guide.

(i) -W execution-monitoring-interval ~<unsigned integer> ((0 to 3600))

Specifies (in minutes) the monitoring interval when the execution time of the pdorbegin command is to be monitored. For guidelines on the value to specify and details about the resulting operation, see the description of the pd_cmd_exec_time operand in the system common definition in the manual HiRDB Version 9 System Definition.

When 0 is specified in this option, the command's execution time is not monitored.

When this option is omitted, the value of the pd_cmd_exec_time operand in the system common definition takes effect.

(5) Rules

  1. The pdorbegin command can be executed only while HiRDB is active.
  2. The pdorbegin command must be executed at the server machine that contains the single server or where the system manager is located.
  3. When you execute the pdorbegin command, the data dictionary RDAREA must be in one of the following statuses:
    • Open and shutdown release status
    • Open and command shutdown status
  4. The pdorbegin command processing depends on option specifications, as described below:
    • When the -r option is specified
      The pdorbegin command processes the specified original RDAREAs for each server. If the command is unable to place all the specified original RDAREAs and the specified generation of replica RDAREAs in the replica group in online reorganization hold status, processing for the corresponding server results in an error and the command processes the next server.
    • When the -t option is specified
      The related RDAREAs for the specified table are processed, and each original RDAREA and the specified generation of replica RDAREAs in the replica group are placed in online reorganization hold status. Because all applicable servers are processed in the batch mode, all servers are placed in the same status.
  5. If the server with a specified original RDAREA contains an RDAREA that has already been placed in online reorganization hold status, the pdorbegin command results in an error.
  6. Whether or not the pdorbegin command is executable depends on the status of the original RDAREA. For details, see C.1 RDAREA status transitions. A replica RDAREA must be in command shutdown and closed status.
  7. The pdorbegin command results in an error if a reflection status management table has not been created by the pdorcreate command or a reflection status management table has been created for an original RDAREA specified in the -r option.
  8. If the column recovery restriction specified during table definition is not ALL and the -r option specifies a user LOB RDAREA that contains that table (LOB column), execution of the command for the server containing that user LOB RDAREA will result in an error.
  9. When the processing target includes a shared RDAREA, processing is performed at all back-end servers in the batch mode. Therefore, an error occurs if the command is unable to place all the specified original RDAREAs and the specified generation of replica RDAREAs in the replica group in online reorganization hold status.
  10. When the pdorbegin command is executed, deadlock may occur for a referencing or updating transaction. By specifying pd_deadlock_priority_use=Y in the system definition and a deadlock priority value for the operation command in the pd_command_deadlock_priority operand, you can specify whether the referencing or updating transaction or the operation command is to take control in the event of deadlock. To make the pdorbegin command result in an error, specify a larger deadlock priority value for the operation command. In this case, re-execute the pdorbegin command after a specific period of time because the pdorbegin command results in an error after releasing all the locks that were placed by the command. To give precedence to the pdorbegin command and make the referencing or updating transaction result in an error, specify a smaller deadlock priority value for the operation command.
  11. If the server contains both shared and non-shared RDAREAs that are in online reorganization hold status and you specify the -s option to release online reorganization hold, you must execute the processing for the shared RDAREAs separately from the processing for the non-shared RDAREAs. If an attempt is made to execute the processing for both at the same time, an error results.
  12. Whether the pdorbegin command can be executed and the execution range depend on the processing target (table or RDAREAs) and the combination of options (-t, -r, -s, -u, and -c), as described below:
    Processing targetOptionWhether or not executableExecution rangeCommand execution format
    -t-r-s-u-c
    TableNon-partitioned table (including shared tables for a HiRDB single server configuration)S--------YAll related RDAREAs#2Format 1
    S----S--Y
    S--S----Y#1RDAREAs related to the specified back-end server#2
    S--SS--Y#1
    S------SYAll related RDAREAs#3
    S----SSY
    S--S--SY#1All RDAREAs related to the specified back-end server#3
    S--SSSY#1
    Row-partitioned tableS--------YAll related RDAREAs#2
    S----S--Y
    S--S----Y#1RDAREAs related to the specified back-end server#2
    S--SS--Y#1
    S------SYAll related RDAREAs#3
    S----SSY
    S--S--SY#1All RDAREAs related to the specified back-end server#3
    S--SSSY#1
    Shared table (applicable to a HiRDB parallel server configuration only)S--------YRDAREAs related to all back-end servers#2
    S----S--YFormat 2
    S--S----NNot applicableFormat 1
    S--SS--YRDAREAs related to the specified back-end server#2Format 2
    S------SYRDAREAs related to all back-end servers#3Format 1
    S----SSYFormat 2
    S--S--SNNot applicableFormat 1
    S--SSSYRDAREAs related to the specified back-end server#3Format 2
    RDAREANon-shared RDAREA only--S------YOnly the specified RDAREAsFormat 1
    --S--S--Y
    --SS----NNot applicable
    --SSS--N
    --S----SN
    Shared RDAREA only--S------YAll back-end servers
    --S--S--YFormat 2
    --SS----NNot applicableFormat 1
    --SSS--YSpecified back-end serversFormat 2
    --S----SNNot applicableFormat 1
    Both non-shared and shared RDAREAs--S------YAll back-end servers
    --S--S--YFormat 2
    --SS----NNot applicableFormat 1
    --SSS--NFormat 2
    --S----SNFormat 1
    Legend:
    S: Option is specified
    --: Option is omitted
    Y: Can be executed
    N: Cannot be executed
    #1: If the specified back-end server does not match the back-end server that contains the related RDAREAs, an error occurs.
    #2: Relation to the constraint definition is not included.
    #3: Relation to the constraint definition is included.

(6) Notes

  1. The result of the pdorbegin command can be checked with the pdls -d org command or on the basis of the return code. The return codes are as follows:
    0: Normal termination
    4: Warning termination (processing was successful at some servers)
    8: Abnormal termination
    12: Abnormal termination (an event occurred that prevented the command from displaying an error message)
    If the return code is 12, check the error message in the syslogfile at the host where the single server or dictionary server is located, eliminate the cause of the error, and then re-execute the command. If no error message has been output to the syslogfile, contact the customer engineer.
  2. The online reorganization hold is inherited when HiRDB is restarted.
  3. The pdorbegin command places the specified RDAREAs in the EX lock mode. If a specified RDAREA is being accessed by another transaction, the pdorbegin command is placed in wait status until that transaction terminates. Once execution of pdorbegin command begins, all transactions for the specified RDAREAs are placed in wait status due to a lock on the replica group configuration until the pdorchg command is completed.
  4. When the -t option is specified, the pdrdrefls command executes internally. Therefore, when the -t option is specified, a message from the pdrdrefls command may be displayed.
  5. If hybrid is selected as the processing method for Real Time SAN Replication, executing the pdorbegin command results in a database synchronization wait for the remote site. This may result in an overhead of 2 seconds or more for each RDAREA specified in the -r option. If the database synchronization wait for the remote site fails, you must recover the remote site's database. For details about the error handling when Real Time SAN Replication is used, see the manual HiRDB Version 9 Disaster Recovery System Configuration and Operation Guide.