10.3.2 Options

Organization of this subsection
(1) -k operation-mode
(2) -t [authorization-identifier. ]table-identifier
(3) -i index-creation-method
(4) -l log-acquisition-method
(5) -u authorization-identifier
(6) -c commit-unit
(7) -n [batch-input/output-local-buffer-sectors-count],[random-access-local-buffer-sectors-count]
(8) -m progress-message-output-interval
(9) control-information-filename

(1) -k operation-mode

[Figure]<<share>>

Specifies pdrbal's operation mode.

share
Allows other users to reference and update the table during execution of pdrbal (shared mode). Use this mode when executing pdrbal without terminating online applications for the table.
exclusive
Does not allow other users to reference or update the table during execution of pdrbal (exclusive mode). Use this mode when executing pdrbal by terminating all online applications for the table.

(2) -t [authorization-identifier. ]table-identifier

Specifies the name of the rebalancing table being processed by the rebalancing utility.

When the authorization identifier is omitted, the system assumes the authorization identifier of the user who established the connection with HiRDB.

Rules
  1. You cannot specify either of the following tables:
    • View tables
    • Foreign tables
    • Non-rebalancing tables (partitioned by a HASH function (HASHA to HASHF))
  2. If an 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 need to enclose the entire identifier in single quotation marks (').
  3. Table 10-2 shows whether or not pdrbal can be executed on a rebalancing table containing an abstract data type.

    Table 10-2 Whether or not pdrbal can be executed on a rebalancing table containing an abstract data type

    Contents of abstract data typeExecution of pdrbal
    User-defined abstract data typeN
    Abstract data type provided by plug-inWith BLOB attributeY*
    No BLOB attributeY
Y: Executable.
N: Not executable.
* With some plug-ins, pdrbal is executable only when a constructor reverse creation function for database reorganization is specified.

(3) -i index-creation-method

[Figure]<<c>>

Specifies the index creation method.

In the shared mode, this operand, if specified, is ignored (in which case s is assumed).

c
Indicates the batch index mode. When this mode is specified, the utility rebalances row data and then creates an index in batch mode.
Criterion:
Specify this option if you want to rebalance row data in the exclusive mode and then create an index for the row data at high speed. Note that if you specify the execstop statement, the utility creates an index in the batch mode after the data has been moved; therefore, you may not be able to stop pdrbal until index creation for the moved data has been completed.
s
Indicates the index update mode. In this mode, the utility updates indexes each time row data is moved.
Criterion:
Specify this option if only a small amount of row data is rebalanced in the exclusive mode or it is impossible to allocate an index information file or work directory for sorting. Also specify this option if you want to make sure that pdrbal stops within the execution time specified in the execstop statement.
Note
  1. When -i c is specified, the command creates as many index information files as the number of indexes [Figure]number of added table storage RDAREAs. Because these files are opened simultaneously, the maximum number of files permitted per process may be exceeded. If this is the case, increase the pd_max_open_fds operand value in the system definition. If the value of the pd_max_open_fds operand is exceeded, check and, if necessary, revise the number of table partitions per server and the number of defined indexes or specify -i s.
  2. If the index and idxwork statements are omitted, the system outputs the index information file to the /tmp directory using the following naming convention:
    /tmp/INDEX-index-name-index-storage-RDAREA-name-unique-character-string
    If pdrbal terminates abnormally, this file is not deleted. If you re-execute pdrbal, another index information file is created under a different name. Because this may result in a space shortage in the /tmp directory, you should delete unneeded index information files with the OS's rm command.

(4) -l log-acquisition-method

[Figure]<<a>>

Specifies the database update log acquisition method during the execution of pdrbal.

If you have specified the exclusive mode, be sure to specify the -l option. This option is ignored in the shared mode (in which case a is assumed).

a
Indicates the log acquisition mode in which the system acquires database update log information required for rollback and rollforward.
Criteria:
Specify this option if only a small amount of row data is rebalanced or if you do not want to make backup copies before and after the execution of pdrbal.
When pdrbal is executed in the log acquisition mode, there is no need to make backup copies before and after the execution of pdrbal, but the performance is lower than in the no-log mode.
n
Indicates the no-log mode. The system does not collect database update log information.
Criteria:
Specify this option when a large amount of row data is to be rebalanced.
When pdrbal is executed in the no-log mode, the execution time is shorter than in the log acquisition mode. However, you need to make a backup copy before executing pdrbal to protect against possible abnormal termination. Because the system does not collect database update log information, you also need to make a backup copy after the execution of pdrbal.
If pdrbal terminates abnormally, the table storage RDAREAs are placed in error shutdown status. In this case, you need to restore the RDAREAs from their backup copy made prior to the execution of pdrbal.
Rules
  1. If the RDAREAs can be restored from a previous backup copy, there is no need to make a backup copy prior to the execution of pdrbal.
  2. In the no-log mode, the system outputs the following amount of ENQ log per server instead of the database update log:
    ENQ log = (p + q + r) [Figure] T
    p: Number of table storage RDAREAs
    q: Number of LOB column (LOB attribute) storage RDAREAs
    r: Number of index storage RDAREAs
    T: Amount of transaction log (see the -c option)
  3. For details about how to operate in no-log mode, see the HiRDB Version 8 System Operation Guide.
  4. If the execstop statement is specified to execute pdrbal in multiple segments, you need to make a backup copy each time pdrbal is executed.
  5. If you use Real Time SAN Replication based on the log-only synchronous method, and if you execute pdrbal with -l n specified at the transaction execution site, you must perform the preparations for log application. For details about the preparations for log application, see the manual HiRDB Version 8 Disaster Recovery System Configuration and Operation Guide.

(5) -u authorization-identifier

Specifies the authorization identifier of the user executing pdrbal.

For the default for this option, see Default value as follows.

If this option is specified, the system displays a message requesting an entry of a password. If no password is required, enter null in response to the message.

The system establishes connection with HiRDB using the specified authorization identifier and checks execution privileges.

Criterion
Specify this option to execute pdrbal using a different authorization identifier than the one specified in the PDUSER environment variable.
Default value
When this option is omitted, the system assumes the authorization identifier and password as follows:
  1. The system assumes the value of the PDUSER environment variable during the execution of pdrbal. Be sure to specify PDUSER if you are executing the utility in the background with & attached by the shell, or in a remote shell environment when a password cannot be entered.Following are examples of the PDUSER environment variable:
    Specifying a password:
    setenv PDUSER '"authorization-identifier"/"password"'
    Not specifying a password:
    setenv PDUSER '"authorization-identifier"'
  2. If the PDUSER environment variable is not specified, the system assumes the login window's user name. Enter the password when a message is displayed requesting password entry. If no password is required, enter null in response to the message.
Rules
  1. Do not specify this option if you are executing the utility in the background with & attached by the shell, or in a remote shell environment where a password cannot be entered.
  2. If you enclose an authorization identifier in double quotation marks, the system treats it as case sensitive; otherwise, the system treats it as in all uppercase letters. If you use the Bourne shell (sh), C shell (csh), or Korn shell (ksh), you need to enclose the authorization identifier in single quotation marks (').

(6) -c commit-unit

[Figure]<unsigned integer> ((1-1000000)) <<shared mode: 10, exclusive mode: 100000>>

Specifies the number of rows to be moved before a commit point is reached when rearranging row data during a rebalance operation.

If 0 is specified, the utility does not limit the number of rows that can be moved per transaction (the utility moves rows, treating processing through the end of rebalancing or up to the time specified in the execstop statement as one transaction).

With a HiRDB/Parallel Server, a commit may be reached before the specified number of rows depending on the number of rows stored in each RDAREA.

Recommended value
In the shared mode, pdrbal locks both source and target RDAREAs when moving data. This means that the source and target RDAREAs are not accessible until pdrbal stops moving data (until a commit point is reached). Therefore, in the shared mode, you can reduce the lock release wait time by specifying a small value for the commit unit.
If UAP processing is more important than the rebalance operation, specify a small value; if the rebalance operation is more important than UAP processing, specify a large value.
If an index has been defined for the target table in the exclusive and no-log mode, you can improve performance by specifying 0 as the commit unit (an improvement in performance can be expected because the global buffer updated by index maintenance at the time of commit is flushed only once, thereby also reducing the number of commits). However, the number of locked resources increases according to the increase in the number of rows to be processed, because the processing is performed by a single transaction. Also, the interval during which no synchronization point dump is collected becomes longer.
Notes
  1. If there are comparatively many transactions for online applications, you should specify a value of 100 or less.
  2. If a small value is specified for the commit unit, the rebalance processing requires a long time. As the number of commit points increases, the amount of output transaction log increases. A transaction log is always output regardless of the specification of the -l option, and its amount can be determined by the following formula:

    Amount of transaction log
           = (1328 + 176 [Figure] 3) [Figure] (a [Figure] b + 1024 [Figure] c) (bytes)

    a: Number of data items being rebalanced
    b: Value of -c option
    c: Number of table storage RDAREAs
    Each time a commit point is reached, the system outputs this amount of transaction log to each server's system log file. Each server means each and every front-end server and back-end server that contains the table storage RDAREAs. If the table has an abstract data type, transaction log is also output to the dictionary server.
  3. If you specify a large value for the commit unit, a synchronization point dump cannot be collected for a long period of time. If an error occurs when executing the utility concurrently with another UAP, the time required for restart processing increases.
  4. You can specify 0 as the commit unit only in the exclusive and no-log mode; otherwise, 0 cannot be specified.

(7) -n [batch-input/output-local-buffer-sectors-count],[random-access-local-buffer-sectors-count]

Specifies that rebalancing is to be executed in the exclusive mode using a local buffer. By specifying this option, you can use a local buffer to access the database, thereby reducing the number of input/output operations by batch input/output operations.

When this option is omitted, the utility uses the global buffer to input/output one page at a time.

batch-input/output-local-buffer-sectors-count[Figure]<unsigned integer> ((2-4096))
Specifies the number of batch input/output local buffer sectors. The batch input/output local buffer is used for data pages.
We recommend that you specify a value in the range 16-32 as the number of batch input/output local buffer sectors. The guideline is 64 kilobytes/page length.
random-access-local-buffer-sectors-count[Figure]<unsigned integer> ((4-125000))
Specifies the number of random access local buffer sectors. The random access local buffer is used for index pages.

You should change the combination of the number of batch input/output local buffer sectors and the number of random access local buffer sectors according to the table definition. Table 10-3 shows the recommended -n option value.

Table 10-3 Recommended -n option specification (pdrbal)

Table typeColumn definitionSpecification of -n option
FIX table or non-FIX tableAll columns are NULL-n random-access-local-buffer-sectors-count
Non-FIX tableA variable-length data type column is defined-n random-access-local-buffer-sectors-count
An abstract data type column is defined
A BINARY column is defined
FIX table or non-FIX tableOther-n batch-input/output-local-buffer-sectors-count
About the buffers used by pdrbal
When the -n option is omitted, the utility uses the global buffer. In such a case, the transaction performance of a UAP that uses the global buffer drops because a large amount of global buffer space is used during rebalancing. When the -n option is specified, such buffer contention is eliminated. Figure 10-5 shows the relationship between pdrbal and buffers.

Figure 10-5 Relationship between pdrbal and buffers

[Figure]
Explanation:
When only the global buffer is used (-n option is omitted), buffer contention occurs between pdrbal and the UAP.
When both local and global buffers are used (-n option is specified), no buffer contention occurs between pdrbal and the UAP. However, during rebalancing of a table with LOB columns, the utility uses the global buffer even if the -n option is specified.
Rules
  1. When this option is omitted, the utility assumes a value of 1 and uses the global buffer. Therefore, batch I/O operations do not take place.
  2. If this option is specified for a rebalancing table partitioned by the FIX hash partitioning method, the system allocates a buffer with a size of pages specified for each hash group; therefore, more memory is used than for a rebalancing table partitioned by the flexible hash partitioning method. A hash group is one of the 1024 groups created by HiRDB based on the result of hashing the partitioning key. The utility allocates RDAREA segments to each of these groups and stores data during the rebalance operation.
  3. When this option is omitted (in which case the global buffer is used), at least the following number of buffer sectors is needed to achieve reasonable performance:

    Number of buffer sectors per RDAREA
      = 1024 [Figure] number of RDAREAs containing rebalancing table
        [Figure] 2 + 3

(8) -m progress-message-output-interval

[Figure]<unsigned integer> ((1-1000)) <<10>>

Specifies in units of 10,000 lines an interval at which a message is displayed indicating the progress of the current process.

Progress messages are output for each RDAREA.

(9) control-information-filename

[Figure]<pathname>

Specifies the name of the control information file that contains the control statements of pdrbal.

Table 10-4 lists the control statements that can be specified in the control information file. For details about each control statement, see Sections 10.3.3 index statement (specification of index information file information) to 10.3.10.

Table 10-4 Control statements specifiable in the control information file

Control statement (description)Operation mode (-k option)
Shared mode
(share)
Exclusive mode
(exclusive)
index statement
(Specification of index information file information)
[Figure]Y
idxwork statement
(Specification of index information file directory)
[Figure]Y
sort statement
(Specification of sort work directory information)
[Figure]Y
execstop statement
(Specification of pdrbal execution time information)
YY
unld_func statement
(Specification of constructor parameter reverse creation function)
Y*Y*
reld_func statement
(Specification of constructor function)
Y*Y*
report statement
(Specification of execution result file)
YY
option statement
(Specification of optional functions)
YY
Y: Specifiable.
[Figure]: Not specifiable.
* With some plug-ins, specification is required. For details, see the applicable plug-in documentation.

The following rules apply to the files and directories that are specified in the control statements:

  1. You must grant access privileges to the HiRDB administrator in advance. When some control statements or operands are omitted, the system assumes that the applicable file is to be created in the /tmp or /usr/tmp directory; therefore, you must also grant access privileges to the /tmp or /usr/tmp directory.