11.3.2 Options

Organization of this subsection
(1) -k target-resource
(2) -t {[authorization-identifier.]table-identifier|[authorization-identifier.]all}
(3) -r RDAREA-name
(4) -c target
(5) -m commit-interval
(6) -u authorization-identifier
(7) -w concurrently-executed-transaction-settlement-wait-time
(8) -X response-monitoring-time-for-server-to-server-communication
(9) -q generation-number
(10) -j
(11) -o
(12) -x
(13) -p
(14) -n lock-retries-count
(15) -s server-name
(16) control-information-file-name

(1) -k target-resource

Specifies the type of resource (table or index) whose used free pages are to be released.

table:
Specifies that a table is to be processed.
index:
Specifies that indexes are to be processed.

(2) -t {[authorization-identifier.]table-identifier|[authorization-identifier.]all}

[Figure]<identifier>

Specifies the name of the table whose used free pages are to be released.

If you omit the authorization identifier, the utility assumes the user name used to connect to HiRDB.

If you specify all, the utility processes all tables or indexes that belong to the schema whose name is the specified authorization identifier. In this case, you cannot specify the idxname statement.

(3) -r RDAREA-name

[Figure]<identifier>

Specifies the name of the RDAREA that is to be processed (among the RDAREAs storing the table specified with the -t option).

You can specify this option only when -k table is specified. If you specify -k index, specify the idxname statement.

You can specify only a user RDAREA. Batch specification of RDAREA names is not permitted.

(4) -c target

[Figure]<<user>>

Specifies the type of RDAREA that is to be the target of this processing (user RDAREA or data dictionary RDAREA).

user:
Specifies that a user RDAREA is to be processed.
dic:
Specifies that a data dictionary RDAREA is to be processed.

(5) -m commit-interval

[Figure]<unsigned integer> ((0-100000)) <<1000>>

Specifies the transaction settlement interval for the used free page release processing, expressed as the number of pages released. When the number of released pages per RDAREA for the table or index reaches the specified value, the transaction is settled. The utility executes only page compaction on the released pages, including pages that could not become used free pages.

If you specify 0, the transaction settles when all used free pages in the corresponding RDAREA have been released.

By specifying a large value, you can reduce the amount of transaction log information. However, pdreclaim becomes a long-running transaction, losing the timing of synchronization point validation.

(6) -u authorization-identifier

Specifies the authorization identifier of the user who executes pdreclaim.

For details about the authorization identifier, see 8.9.2(10) -u authorization-identifier.

(7) -w concurrently-executed-transaction-settlement-wait-time

[Figure]<unsigned integer> ((0-3600)) <<0>>

Specifies a wait time for pdreclaim (in seconds). When a UAP or another utility accesses a table or index while its free pages or free segments are being released, pdreclaim is placed in lock-release wait status or in transaction settlement wait status. This option specifies that wait time.

pdreclaim is placed in this wait status in the following situations:

Table 11-4 shows the relationship between the -w option specification and pdreclaim's wait time.

Table 11-4 Relationship between -w option specification and pdreclaim's wait time

ProcessingSpecification of -w optionTransaction settlement wait timeLock-release wait time per resource
Releasing free pages in a tableYes[Figure]-w option value
No[Figure]Waits indefinitely until the lock status is released
Releasing free pages in an indexYes-w option value-w option value
NoWaits indefinitely until the other transaction is settledWaits indefinitely until the lock status is released
Releasing free segments in a tableYes[Figure]-w option value
No[Figure]Waits indefinitely until the lock status is released
Releasing free segments in an indexYes[Figure]-w option value
No[Figure]Waits indefinitely until the lock status is released
Legend:
[Figure]: Not applicable because it has nothing to do with the transaction settlement wait status
Rules
  1. If the UAP's transaction is not settled within the specified amount of time after pdreclaim is placed in the wait status, pdreclaim cancels processing with return code 4. If the lock-release wait status is not released, pdreclaim cancels processing with return code 8.
  2. If the -w option is omitted or 0 is specified in the -w option, pdreclaim waits without monitoring until the UAP's transaction is settled or the lock is released.

(8) -X response-monitoring-time-for-server-to-server-communication

[Figure]<unsigned integer> ((1-65535)) <<300>>

If an error, such as a communication error, occurs at the server where the command was executed, the command may stop responding and the application may stop. To detect errors, pdreclaim enables you to monitor a response time during communication for dictionary manipulation that is performed by the command.

You set in the -X option the response monitoring time during dictionary manipulation (in seconds). If the execution time during dictionary manipulation exceeds the value set in the -X option, pdreclaim treats it as a dictionary access error and cancels processing with return code 8.

Criteria
  • If you want to detect an error in less time than 300 seconds in the event of a no-response from the server due to a communication error or unit down, specify a smaller value than 300 in the -X option.
  • If the system switchover facility is used, the command may keep waiting for a response even though system switchover has been completed. In such a case, you can terminate the command immediately by reducing the monitoring time.
  • The specified monitoring time may result in a timeout if a response from the dictionary is delayed and if the utility's preprocessing is not completed within 300 seconds, which is the default value of the -X option. This can happen when many applications and utilities are executing concurrently. In such an environment, specify a value greater than 300 in the -X option.

(9) -q generation-number

[Figure]<unsigned integer> ((0-10))

When the inner replica facility is used, this option specifies the generation number of the target RDAREA.

Specify the generation number as follows:

0: Processes the original RDAREA.
1 to 10: Processes the replica RDAREA with the specified generation number.
Criteria
Specify this option to process an RDAREA other than the current RDAREA using the inner replica facility.
Rules
  1. When the inner replica facility is not used, this option is disabled.
  2. When this option is omitted, the current RDAREA is assumed.
  3. If a replica RDAREA is to be processed, specify the name of the original RDAREA in the -r option and the target generation number in the -q option.
  4. pdreclaim checks the target RDAREA to determine whether its generation number matches the specification. Table 11-5 shows the RDAREAs whose generations are checked by pdreclaim.

    Table 11-5 RDAREAs subject to generation checking by pdreclaim

    Type of processingTarget RDAREASpecification of option or in control information file
    For storing a tableFor storing an index
    Releasing used free pages in tableIn units of tablesY[Figure]-k table
    In units of RDAREAsY[Figure]-k table -r RDAREA-name
    Releasing used free pages in indexIn units of indexesYY-k index
    In units of serversYY-k index
    idxname statement (with server specified)
    In units of RDAREAsYY-k index
    idxname statement (with rdarea specified)
Legend:
Y: Checked
[Figure]: Not checked

(10) -j

Specifies that if there is a used free segment and all its pages become unused, the used free segment is to be released (to create an unused segment).

Criteria
When you specify the -j option, the table or index being processed becomes inaccessible. Therefore, use this option as explained below:
  1. During daytime online operation, execute pdreclaim without specifying -j.
  2. During nighttime batch operation, execute pdreclaim with -j specified.
Rules
When you specify the -j option, the released unused segments become available to any table or index, whether or not it has been using the segments. However, if you specify -k table or -k index, the table storage RDAREA or index storage RDAREA is placed in the EX lock mode, in which case pdreclaim can no longer be concurrently executable with a UAP.

(11) -o

Specifies that free pages are to be released in the table, but that page compaction is not to be executed.

When page compaction is executed to release free space in a page that resulted from updating and deleting rows, database update log information (FJ) is output and its volume is proportional to the amount of free space in the page that is released. You specify the -o option in order to reduce the volume of this log output. You specify this option even when the purpose is to release free pages whose usage rate is 0%. This specification can reduce pdreclaim's execution time.

(12) -x

Specifies that page compaction is to be executed in order to release remaining entries in a unique index when free index pages are released. By executing page compaction, you can maintain online performance and avoid lock-release wait and deadlock.

When page compaction is executed to release remaining entries, database update log information (FJ) is output and its volume is proportional to the amount of key space that is released.

Note that page compaction is executed only when the index to be released is a unique index. For any other type of index, the -x option is ignored.

Criteria
Specifying the -x option results in overhead for page compaction. If you want to reduce the volume of the database update log information (FJ) or if performance is more important, do not specify the -x option.

(13) -p

Specifies that the update buffer is to be applied to the database at the point of commit. If you specify the -p option when you execute the utility at the same time as you execute a UAP, you can reduce the workload of synchronization point processing, thereby reducing the effects on the performance of other transactions. Note that the performance of pdreclaim is lower than when the -p option is omitted.

Specify the -m option to set the commit interval in such a manner that a commit is acquired before a synchronization point dump is acquired.

There is a relationship between the pdreclaim processing and the pd_max_commit_write_reclaim_no operand value in the system common definition. Table 11-6 describes the pdreclaim processing when the pd_max_commit_write_reclaim_no operand and the -p option are specified.

Table 11-6 pdreclaim processing when the pd_max_commit_write_reclaim_no operand and the -p option are specified

pd_max_commit_write_reclaim_no operand specificationpdreclaim processing when the -p option is specified
Specified0pdreclaim terminates with an error.
Other than 0There can be as many concurrent executions per server of the pdreclaim utility with the -p option specified as the value specified in the pd_max_commit_write_reclaim_no operand. Any excess pdreclaim utility executions terminate with an error.
Omittedv7compatible or v6compatible is specified in the pd_sysdef_default_option operandpdreclaim terminates with an error.
OtherThere can be up to 10 concurrent executions per server of the pdreclaim utility with the -p option specified. Any excess pdreclaim utility executions terminate with an error.

(14) -n lock-retries-count

[Figure]<unsigned integer> ((0-3600)) <<0>>

Specifies the maximum number of lock acquisition requests to be released in the case of releasing free segments. Because the -n option is applicable only when free segments are released, you must also specify the -j option when you specify the -n option.

The following describes release of lock acquisition requests in order to release free segments.

If you specify the -j option to release free segments, the target RDAREA is placed in the EX lock mode. If an attempt is made to release free segments in an RDAREA that is being processed by another transaction, the processing may be placed in lock-release wait status.

If another transaction acquires a lock on the RDAREA while the free segment release processing is in lock-release wait status, the first transaction that acquired a lock on the RDAREA and the free segment release processing are both placed in wait status until the lock is released.

When the -n option is specified, the lock acquisition request for the free segment release processing is released when the time specified in the -w option has elapsed, thereby giving preferences to the other transactions' lock-release wait status. The free segment release processing waits for lock release for the amount of time specified in the -w option. Therefore, if you specify the -n option, you must also specify the -w option.

If free segments are not released, the lock acquisition request for free segment release processing is cancelled and then issued again.

Figure 11-7 shows the relationship between the lock acquisition request and the lock-release wait queue.

Figure 11-7 Relationship between lock acquisition request and lock-release wait queue

[Figure]

When the -n option is specified, the utility waits for lock release for as long as the amount of time obtained from -w option value x -n option value. If this value exceeds the pdreclaim execution monitoring time specified in the exectime operand in the option statement, pdreclaim displays the KFPL11111-E message while waiting for lock release and terminates itself forcibly. It is important that you specify an appropriate value in the -n option, taking into account the following:

Relationship between the -n option and the pdreclaim execution monitoring time
A + B + C < D x 60
Legend:
A: Transaction settlement wait time (-w option value)
B: Lock-release wait time for the free segment release processing (-w option value x -n option value)
C: Execution time for free segment release processing
D: pdreclaim execution monitoring time specified in the exectime operand of the option statement

(15) -s server-name

[Figure]<identifier>

This option is applicable to a HiRDB/Parallel Server only (it is ignored if specified for a HiRDB/Single Server).

Specifies the name of the back-end server that is to manage execution of pdreclaim.

Criteria
When this option is omitted, one of the back-end servers is selected automatically; therefore, normally there is no need to specify this option.
Specify this option if you execute many pdreclaim commands concurrently and the number of utility processes per server (0mrorg) is 32 or greater. You can determine the value of 0mrorg by checking the result of the pdls -d prc command for the number of process IDs (0mrorg).

(16) control-information-file-name

[Figure]<path name>

Specifies the name of the control information file that contains the control statements for pdreclaim.

You can specify the following control statements in the control information file; for details about each control statement, see Sections 11.3.3 and 11.3.4: