2.40 pdhold (Shut down RDAREAs)

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

(1) Function

The pdhold command shuts down specified RDAREAs. If a specified RDAREA is in use, the command shuts it down when its utilization is completed.

Shutdown without specifying any options other than -r and -q is called command shutdown.

(2) Executor

HiRDB administrator

(3) Format

pdhold -r {RDAREA-name[,RDAREA-name]...|ALL} [-q generation-number]
       [{-c|-i|-b [-w] [-u]|-s}][-W execution-monitoring-interval]

(4) Options

(a) -r {RDAREA-name[,RDAREA-name]...|ALL}
RDAREA-name ~<identifier> ((1-30))
Specifies the names of RDAREAs to be shut down. A shutdown achieved by specifying the -r option is called command shutdown.
ALL
Specifies that all RDAREAs are to be shut down. The following table describes the RDAREAs that are shut down depending on the combination of the -q and other options:
Other option-q option omitted-q option specified
-bAll RDAREAs except list RDAREAs and temporary table RDAREAsRDAREAs of the specified generation in the inner replica group
-sWhen the -s option is specified, the -q option cannot be omitted.
OtherAll RDAREAs except the master directory RDAREA
Rules:
  1. For the rules for specifying RDAREAs, see 1.5.2 Specification of RDAREAs in operation commands and utilities.
  2. If you specify the -b option, you can also specify a master directory RDAREA; otherwise, you cannot specify a master directory RDAREA. Note also that when you specify the -b option, you cannot specify a list RDAREAs or a temporary table RDAREA.
  3. If specifying a user RDAREA or user LOB RDAREA, make sure that the corresponding data dictionary RDAREA is in one of the following statuses:
    [Figure]Open and shutdown release status
    [Figure]Open and shutdown status placed by the pdhold command
  4. When specifying both data dictionary and user RDAREAs or both data dictionary and user LOB RDAREAs, be sure to specify the data dictionary RDAREAs last.
  5. If you are using the inner replica facility, you can also specify the original and replica RDAREA names. In this case, you can specify only user RDAREAs and user LOB RDAREAs.
(b) -q generation-number ~<unsigned integer> ((0-10))

Specifies a replica RDAREA generation number.

If you specify this option, make sure that the original RDAREA name is specified in the -r option. An error results if you specify an original RDAREA whose replicas have all been deleted or if you specify an RDAREA without a replica RDAREA.

(c) -c

Specifies that the RDAREA is to be shut down and then closed. This is called closed command shutdown.

If this option is omitted, HiRDB shuts down only the specified RDAREAs.

(d) -i

Specifies that the RDAREAs that have been shut down are to be made available to users for referencing. This is called reference-possible shutdown.

If you omit this option, you cannot reference the RDAREAs shut down.

(e) -b [-w] [-u]

Specifies that the RDAREAs are to be placed in backup hold status.

The backup-hold status enables a backup copy to be made even in online mode. RDAREAs are placed in backup hold at the following times:

There are four different backup-hold statuses:

  1. Reference-possible backup-hold (-b specified)
  2. Reference-possible backup-hold (update WAIT mode) (-b,-w specified)
  3. Updatable backup-hold (-b, -u specified)
  4. Updatable backup-hold (WAIT mode) (-b, -w, -u specified)

Statuses 1 and 2 above are called committing a database.

The following explains each backup-hold status:

Reference-possible backup-hold
If an updating transaction can result in an error until the shutdown status is released, place the RDAREA on reference-possible backup-hold.
Notes
  1. For an RDAREA in the reference-possible backup-hold status, no deadlock occurs with an updating transaction.
  2. You can use the backup copy obtained in this status to restore the database to the point where the backup was made without having to use the system log. Using the system log existing immediately before the RDAREA was placed in the backup-hold status, you can restore the database to the point where the error occurred.
  3. You can reference an RDAREA on reference-possible backup-hold, but an attempt to update the RDAREA results in an SQL error (-920) unless the shutdown status is released. If an updating transaction in no-log mode results in an error, all updated RDAREAs, if any, are placed in shutdown status.
Reference-possible backup-hold (update WAIT mode)
If an updating transaction can be placed on hold until the shutdown status is released, place the RDAREA on reference-possible backup-hold (update WAIT mode).
Notes
  1. You can use the backup copy obtained in this status to restore the database to the point where the backup was made without having to use the system log. Using the system log existing immediately before the RDAREA was placed on backup-hold, you can restore the database to the point of error occurrence.
  2. You can reference an RDAREA on reference-possible backup-hold (update WAIT mode), but an attempt to update the RDAREA results in the hold status unless the RDAREA is released from the backup-hold status. Therefore, the value of the pd_lck_wait_timeout operand in the system definitions and the value of PDCWAITTIME in the client environment definitions must be at least the period of time the backup-hold status is in effect. If timeout occurs, the updating transaction results in an SQL error (-770).
  3. If you place an RDAREA on reference-possible backup-hold (update WAIT mode), deadlock may occur with an updating transaction. By specifying pd_deadlock_priority_use=Y in the system definition and a deadlock priority value in the pd_command_deadlock_priority operand, you can specify whether the updating transaction or the operation command is to take control in the event of deadlock.
  4. If deadlock occurs, the backup-hold status placed by the pdhold command is released and the same backup-hold processing is repeated. You can use the backup copy obtained in this status to restore the database to the point where the backup was made. This retry processing is repeated up to five times. If deadlock occurs on the fifth retry, the system releases all the backup-hold statuses placed by the pdhold command and terminates the processing with an error.
  5. If an updating transaction in no-log mode terminates with an error due to timeout or deadlock, all updated RDAREAs, if any, are placed in shutdown status.
Updatable backup-hold
If you want to immediately place an RDAREA in backup-hold status and access it in this status, place the RDAREA in the updatable backup-hold status. If another command is executing, you can execute the pdhold command to place an RDAREA in updatable backup hold status after that command has terminated.
Notes
  1. You can reference and update an RDAREA in the updatable backup-hold status.
  2. For an RDAREA on updatable backup-hold, an applicable page's physical log is output when the update buffer takes effect on the database, unless the shutdown status is released. Therefore, note the following:
    (a) Check to see if there is enough space in the system log file.
    (b) If updating a large amount of data, do not place the RDAREA on updatable backup-hold (a large amount of plug-in index data is also updated).
    (c) Upon completion of backup processing, immediately release the RDAREA from the updatable backup-hold status.
  3. Even during the execution of updating transaction, the pdhold command can place an RDAREA on updatable backup-hold.
  4. To restore the database using the backup copy obtained in this status, you need the system log acquired after the backup processing and the previous synchronization point. However, if an updating transaction was executed in the pre-update log acquisition or no-log mode after the previous synchronization point, you cannot restore the database with this backup copy.
  5. Because physical logs are output when you update a shared RDAREA in the updatable backup-hold mode, more log information is output than when a shared RDAREA in a mode other than the updatable backup-hold mode is updated. If you acquire backups of a shared RDAREA in the updatable backup-hold mode, you should consider not executing update jobs at all, or at the least you should minimize the amount of data to be updated.
Updatable backup-hold (WAIT mode)
If an RDAREA can be placed in backup-hold status after completion of an updating transaction and you want to access the RDAREA in this status, place the RDAREA in the updatable backup-hold status (WAIT mode).
Notes
  1. To restore the database using a backup copy obtained in this status, you do not need the system log if no warning message (KFPH00157-W) was output when the RDAREA was released from the backup-hold status. If a warning message was output, you need the system log existing after the previous synchronization point. Using the system log existing immediately before the RDAREA was placed in backup-hold status, you can restore the database to the point of error occurrence, whether or not a warning message was output. If the backup copy was made with pdcopy specifying -M s, you need the system log existing after the previous synchronization point, whether or not a warning message was output.
  2. If you place an RDAREA on updatable backup-hold (WAIT mode), you can reference and update the RDAREA.
  3. For an RDAREA on updatable backup-hold (WAIT mode), an applicable page's physical log is output when the update buffer takes effect on the database unless the shutdown status is released. Therefore, note the following:
    (a) Check to see if there is enough space in the system log file.
    (b) If updating a large amount of data, do not place the RDAREA on updatable backup-hold (a large amount of plug-in index data is also updated).
    (c) Upon completion of backup processing, immediately release the RDAREA from the updatable backup-hold status.
  4. If updating transaction processing is underway, the pdhold command to place an RDAREA on updatable backup-hold (WAIT mode) is placed on hold until the transaction processing is completed.
  5. If an RDAREA is on updatable backup-hold, an updating transaction in pre-update log acquisition or no-log mode for this RDAREA is placed on hold until the RDAREA is released from the backup-hold status. Therefore, the value of the pd_lck_wait_timeout operand in the system definitions and the value of PDCWAITTIME in the client environment definitions must be at least the period of time the backup-hold status is in effect. If timeout occurs, the updating transaction in pre-update log acquisition or no-log mode results in an error.
  6. If you place an RDAREA on updatable backup-hold (WAIT mode), deadlock may occur with an updating transaction in the pre-update log acquisition or no-log mode. By specifying pd_deadlock_priority_use=Y in the system definition and a deadlock priority value in the pd_command_deadlock_priority operand, you can specify whether the updating transaction or the operation command is to take control in the event of deadlock.
  7. If deadlock occurs, the backup-hold status placed by the pdhold command is released and the same backup-hold processing is repeated. You can use the backup copy obtained in this status to restore the database to the point where the backup was made. This retry processing is repeated up to five times. If deadlock occurs on the fifth retry, the system releases all the backup-hold status placed by the pdhold command and terminates the processing with an error.
  8. If an updating transaction in pre-update log acquisition or no-log mode terminates with an error due to timeout or deadlock, all updated RDAREAs, if any, are placed in shutdown status.
  9. Because physical logs are output when you update a shared RDAREA in the updatable backup-hold mode, more log information is output than when a shared RDAREA in a mode other than the updatable backup-hold mode is updated. If you acquire backups of a shared RDAREA in the updatable backup-hold mode, you should consider not executing update jobs at all, or at the least you should minimize the amount of data to be updated.
-w
Specifies that the RDAREAs are to be placed on reference-possible backup-hold (update WAIT mode) or updatable backup-hold (WAIT mode).
If you place the RDAREAs on reference-possible backup-hold (update WAIT mode), an updating transaction is placed on hold. If you place the RDAREAs on updatable backup-hold (WAIT mode), an updating transaction in pre-update log acquisition or no-log mode is placed on hold.
-u
Specifies that the RDAREAs are to be placed on updatable backup-hold.
You can reference and update an RDAREA on updatable backup-hold. However, an attempt to update a UAP or utility in no-log mode is placed on hold until the shutdown status is released. If you omit this option, the system places the specified RDAREAs on reference-possible backup-hold.
Rules of backup-hold
  1. While an RDAREA is in the backup-hold status, you cannot execute pdmod (to extend, reinitialize, or change the attributes of an RDAREA), pdload, or pdrorg (to reload) on the RDAREA.
  2. The status of an RDAREA on reference-possible backup-hold (update WAIT mode) or updatable backup-hold is not inherited during a rerun.
  3. If you place an RDAREA on updatable backup-hold during operation in the no-log mode, be sure to use the pdlogswap -d sys -w command to swap the system log files and validate the synchronization point dump beforehand. Otherwise, you need to use pdrstr to specify a range of recovery in the event of an error.
  4. If you terminate or restart HiRDB while making a backup copy in the updatable backup-hold status, the backup copy obtained cannot be guaranteed. In this case, obtain a backup copy again.
  5. For an RDAREA on reference-possible backup-hold (update WAIT mode), deadlock may occur between the pdhold command and an updating transaction. For an RDAREA on updatable backup-hold, deadlock may occur between the pdhold command and an updating transaction in the no-log mode. In the event of deadlock, if the RDAREA is already placed on reference-possible backup-hold (update WAIT mode) or updatable backup-hold, execute the pdrels command to release the RDAREA from the shutdown status and then re-execute the pdhold command. If the RDAREA has not been placed on reference-possible backup-hold (update WAIT mode) or updatable backup-hold, re-execute the pdhold command after a while.
  6. If update buffer contents become effective for an RDAREA while it is on updatable backup-hold (WAIT mode) status, a warning message (KFPH00157-W) is issued when the backup-hold status is released. If this warning message has not been issued, you can restore data to the point where the backup was made without using the system log. However, if this message has been issued, you need the system log obtained since the previous synchronization point. Whether or not the warning message has been issued, if you use the system log obtained immediately before the backup shutdown, you can restore data to the point where the error occurred. If you have acquired the backup using pdcopy with -M s specified, you need the system log obtained since the previous synchronization point whether or not the warning message has been issued.
  7. If the pdhold command that has been issued to place an RDAREA in backup hold status is placed in wait status by another command, the timeout specified in the pd_lck_wait_timeout operand in the system definition does not apply to this pdhold command. The command is kept in wait status until the RDAREA is released from the other command. You can terminate a pdhold command that is in wait status by executing the pdcancel command to end the single server process or back-end server process.
  8. You cannot place in backup hold status an RDAREA that has been placed temporarily in reference-possible shutdown status from online reorganization hold status. To determine whether or not an RDAREA is in online reorganization hold status, use the pdls -d org command.
(f) -s

Specifies that the RDAREAs are to be placed in synchronization shutdown status.

Synchronization shutdown is used when the inner replica facility is used. RDAREAs are placed in synchronization shutdown status, for example, when data in an RDAREA is to be copied as the data in another generation of RDAREA within the same inner replica group (for re-pairing paired volumes).

When an RDAREA is placed in synchronization shutdown status, the buffers for the corresponding RDAREA are discarded and the referencing and updating transactions are placed in wait status.

Rules
  1. If an RDAREA is placed in synchronization shutdown status, conformity is lost in the contents of the RDAREA because the update buffer for that RDAREA is discarded without being applied to the database. If there is an update buffer, inconsistent information is written into the RDAREA. You cannot release this synchronization shutdown status until data is copied from another RDAREA to the corresponding RDAREA within the same inner replica group to achieve data conformity.
  2. An error results if you specify this option, and the following RDAREAs are specified in the -r option:
    • RDAREAs for which replica definition is not supported (for details about RDAREAs for which replica definition is supported, see the HiRDB Version 9 Staticizer Option Description and User's Guide).
    • Original RDAREAs all of whose replica RDAREAs have been deleted, or RDAREAs that do not have replica RDAREAs
  3. If you specify this option and multiple RDAREAs are specified in the -r option, the command executes the processing in the batch mode for each server. If an error occurs during processing, the command ignores the processing at the server containing the erroneous RDAREA, and resumes processing at the other servers.
  4. While synchronization shutdown is in effect, you cannot execute pdmod (to extend or delete RDAREAs or change their attributes), pdload, pdrorg, or pdcopy.
  5. Once an RDAREA is placed in synchronization shutdown status, it is also locked in the same manner as with reference-possible backup hold (update WAIT mode). Therefore, the values of the pd_lck_wait_timeout operand in the system definition and PDCWAITTIME in the client environment definition must be no less than the duration of the synchronization shutdown. If a timeout occurs, a referencing or updating transaction results in an SQL error (-770).
  6. If an RDAREA is placed in synchronization shutdown status, 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 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. If the operation command results in an error due to deadlock, re-execute the pdhold command after a specific period of time. If the pdhold -s command with multiple RDAREAs specified results in an error, synchronization shutdown processing is ignored for all the RDAREAs.
  7. If an updating transaction running in the no-log mode terminates with an error due to a timeout or deadlock and if there is an RDAREA that has already been updated by the transaction, that RDAREA will be placed in no-log shutdown status.
  8. To perform the synchronized shutdown of multiple related RDAREAs, such as those containing a table and its index, use only one pdhold command.
  9. If the pdhold -s command is executed, the RDAREAs are forcibly released from memory. If this happens, update data in in-memory data buffers is not applied to the RDAREAs.
(g) -W execution-monitoring-interval ~<unsigned integer> ((0 to 3600))

Specifies (in minutes) the monitoring interval when the execution time of the pdhold 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.

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

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

(5) Rules

  1. You can execute the pdhold command only while HiRDB is active.
  2. Execute the pdhold command at the server machine containing the single server or the server machine where the system manager is located.
  3. The pdhold command locks RDAREAs in the EX mode or in the PR mode if the -i or -b option is specified. Therefore, if another transaction is accessing the specified RDAREA, the pdhold command is placed on hold until the transaction terminates. If the -i or -b option is specified, the pdhold command is placed on hold only if an updating transaction is accessing a specified RDAREA. The table below shows the relationship between an RDAREA's shutdown status and the transaction.

    Table 2-7 Relationship between RDAREA's shutdown status and transaction

    RDAREA shutdown statusTransaction
    Reference#1Update#2Update (no log)#3
    Command shutdownWaitWaitWait
    ErrorErrorError
    Reference-possible shutdownNo wait#4WaitWait
    No waitErrorError
    Reference-possible backup holdNo wait#4WaitWait
    No waitErrorError
    Reference-possible backup hold (update WAIT mode)No wait#4WaitWait
    No waitWaitWait
    Updatable backup-holdNo waitNo waitNo wait
    No waitNo waitWait
    Updatable backup-hold (WAIT mode)No wait#4WaitWait
    No waitNo waitWait
    Synchronization shutdownWaitWaitWait
    WaitWaitWait
    Note
    The upper row indicates the case in which a transaction locks the RDAREA first. The lower row indicates the case in which the pdhold command locks the RDAREA first. For example, if a referencing UAP locks the RDAREA first, an attempt to place the RDAREA in the command shutdown status using the pdhold command places the command on hold. If the pdhold command (command shutdown) locks the RDAREA first, an attempt to execute a UAP to update this RDAREA results in an error.
    #1
    Reference transaction refers to a transaction that executes an SQL statement that applies an SR or PR lock to an RDAREA. For example, the SELECT statement with WITH SHARE specified is a reference transaction because it applies an SR lock.
    #2
    Update transaction refers to a transaction that executes an SQL statement that applies an SU, PU, or EX lock to an RDAREA. For example, the SELECT statement with WITH EXCLUSIVE specified is an update transaction because it applies an SU lock.
    #3
    This indicates a transaction in the no-log mode for which NO is specified for PDDBLOG in the client environment definition.
    #4
    If an updating access occurs between a referencing access and the time the command is entered, any subsequent accesses will be placed in wait status.
  4. The table below shows the handling of a transaction in shutdown processing, where in shutdown processing means ACCEPT-HOLD (the RDAREA status obtained as the execution result by the pddbls command):

    Table 2-8 Handling of a transaction in shutdown processing

    Status in shutdown processingReferencing transactionUpdating transaction
    Command shutdownErrorError
    Reference-possible shutdownWaitError
    Reference-possible backup holdWaitError
    Reference-possible backup hold (update WAIT mode)WaitWait
    Updatable backup-holdNo wait#No wait#
    Updatable backup-hold (WAIT mode)WaitWait
    Synchronization shutdownWaitWait
    #: The transaction is not placed in wait status because updatable backup-hold status does not lock RDAREAs.
  5. An RDAREA containing a falsification prevented table that is in reload-not-completed data status cannot be placed into reference-possible shutdown status (-i specified) or backup hold status (-b specified). Using pdrorg to reload data to a falsification prevented table releases the table from reload-not-completed data status. After the reload-not-completed data status is released, place the table in reference-possible shutdown status or backup hold status.
  6. If the pdhold command is executed on a shared RDAREA, all back-end servers are locked. If there can be multiple concurrent accesses to the corresponding RDAREA, global deadlock may occur, resulting in a timeout. If global deadlock has occurred, re-execute the pdhold command.
  7. When RDAREA automatic extension has been applied to an RDAREA, placing the RDAREA in updatable backup-hold status or updatable backup-hold (WAIT mode) status suppresses the automatic extension of the RDAREA. To release RDAREA automatic extension from the suppression, execute the pdrels command to release the updatable backup hold or the updatable backup hold (WAIT mode).
  8. When RDAREA automatic extension has been applied to an RDAREA, before placing the RDAREA in updatable backup-hold status or updatable backup-hold (WAIT mode) status, use the database condition analysis utility to check that there is enough unused area. If there is not enough unused area, execute the free page release utility.
  9. The following table describes HiRDB processing when the pdhold command is executed on in-memory RDAREAs.

    Table 2-9 HiRDB processing when the pdhold command is executed on in-memory RDAREAs

    Type of pdhold commandHiRDB processing during pdhold command execution
    pdhold -b (reference-possible backup hold)Synchronizes the in-memory data buffer and the in-memory RDAREAs (resulting in database synchronous status)
    The in-memory RDAREAs are placed in the shutdown status determined by the specified options.
    pdhold -b -w (reference-possible backup hold (update WAIT mode))
    pdhold -c
    pdhold -s (inner replica facility synchronization shutdown)The RDAREAs are forcibly released from memory. If this happens, update data in the in-memory data buffer is not applied to the RDAREAs.
    In this case, the RDAREAs are placed in synchronization shutdown status.
    pdhold -b -u (reference-possible backup hold)The pdhold command results in an error.
    pdhold -b -u -w (reference-possible backup hold (WAIT mode))
    pdholdDoes not synchronize the in-memory data buffer and the in-memory RDAREAs.
    The in-memory RDAREAs are placed in the shutdown status determined by the specified options.
    pdhold -i

(6) Notes

  1. You can use the pddbls command to check the result of the pdhold command.
  2. The following shows the pdhold command's return codes:
    0: Normal termination
    4: Warning termination (some RDAREA processing terminated with an error)
    8: Abnormal termination
    12: Abnormal termination (an event occurred that prevented output of an error message)
    If the error 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.
  3. If hybrid is selected as the processing method for Real Time SAN Replication and any of the options listed below is specified during execution of the pdhold command, a database synchronization wait for the remote site occurs. This may result in an overhead of 2 seconds or more for each RDAREA specified in the -r option.
    • -c (closed, command shutdown)
    • -s (synchronization shutdown)
    If database synchronization wait for the remote site fails, you must restore the database at the remote site. For details about error handling when Real Time SAN Replication is used, see the HiRDB Version 9 Disaster Recovery System Configuration and Operation Guide.