~<<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.

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
   • Non-rebalancing tables (partitioned by a HASH function (HASHA to HASHF))
2. An authorization identifier or a table identifier enclosed within double quotation marks (") is treated as case sensitive. An authorization identifier or a table identifier that is not enclosed within double quotation marks (") is treated as 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. The table below shows whether pdrbal can be executed on a rebalancing table containing an abstract data type.
   

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

   Contents of abstract data type		Execution of pdrbal
   User-defined abstract data type		N
   Abstract data type provided by plug-in	With BLOB attribute	Y#
   	No BLOB attribute	Y

   Y: Executable.

   N: Not executable.

   #: With some plug-ins, pdrbal is executable only when a constructor reverse creation function for database reorganization is specified.

   
   

~<<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 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.
   

~<<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) T
   p: Number of table storage RDAREAs
   q: Number of LOB column (LOB attribute) storage RDAREAs
   r: Number of index storage RDAREAs
   T: Number of transactions (see the -c option)
   
3. For details about how to operate in no-log mode, see the HiRDB Version 9 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 execute pdrbal with -l n specified at the transaction execution site while you are using Real Time SAN Replication based on the log-only synchronous method, you must perform the preparations for log application. For details about the preparations for log application, see the HiRDB Version 9 Disaster Recovery System Configuration and Operation Guide.

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.utilityFollowing 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 (').

~<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).

In a HiRDB parallel server configuration, 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 = (1,328 + 176 3) T

   T: (a b + 1,024 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.

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 ~<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.

For the number of batch input/output local buffer sectors, we recommend that you specify a value in the range from 16 to 32. Determine the maximum value to specify by using the formula 184 kilobytes page length.

random-access-local-buffer-sectors-count ~<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. The table below shows the recommended -n option value.

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

Table type	Column definition	Specification of -n option
FIX table or non-FIX table	All columns are NULL	-n random-access-local-buffer-sectors-count
Non-FIX table	A 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 table	Other	-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. The figure below shows the relationship between pdrbal and buffers.

Figure 10-5 Relationship between pdrbal and buffers

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 1,024 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  number of RDAREAs containing rebalancing table
         2 + 3

progress-message-output-interval ~<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.

When you specify lvl2 in the -m option, this message is also output to the work file for troubleshooting information.

information-message-output-suppression-level ~<<lvl0>>

Specifies an option for suppression of output of information messages to the standard output at the terminal that executed the utility, the syslogfile, and the message log file. Even when message output to all three (the standard output, the syslogfile, and the message log file) is suppressed, troubleshooting information is output to a work file. The table below shows the available options and the message output destinations.

Table 10-6 Option values and message output destinations

Option value	Description	Output destination
		Standard output	syslogfile and message log file	Work file
lvl0	Output is not suppressed	Y	Y	N
lvl1	Output to the standard output is suppressed	N	Y	N
lvl2	Output to the standard output, syslogfile, and message log file is suppressed	N	N	Y

Legend:

Y: Messages are output

N: Messages are not output

Messages are output to a work file for troubleshooting purposes (to check the utility operation). We recommend that you normally specify lvl1 if there is no need to check the messages.

Work file

When you specify lvl2 in the -m option, a work file is created for each server each time the utility is executed. Therefore, we recommend that you specify a directory in the pd_tmp_directory operand so that the work files will be deleted periodically by HiRDB with the pdcspool command. The table below shows the work file output destinations.

Table 10-7 Work file output destinations

pd_tmp_directory operand in the system definition	TMPDIR environment variable	Work file output destination
Specified	--	Directory specified in the pd_tmp_directory operand
Omitted	Specified	Directory specified in the TMPDIR environment variable
	Omitted	/tmp directory

Legend:

--: Not applicable

If output of information messages to the work file fails due to a file open error or an I/O error, an error message is displayed but processing continues.

HiRDB creates work files automatically. The file names are always in the format PDRBAL-aa-bb. The following explains the file names:

• PDRBAL: Fixed prefix indicating that the message was output by pdrbal.
• aa: Process's server name.
• bb: File creation time and process ID.

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

~<pathname>

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

The table below lists the control statements that can be specified in the control information file. For details about each control statement, see 10.3.3 index statement (specification of index information file information) through 10.3.10 option statement (specification of optional functions). Note that comments cannot be specified in a control information file.

Table 10-8 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)	--	Y
idxwork statement (Specification of index information file directory)	--	Y
sort statement (Specification of sort work directory information)	--	Y
execstop statement (Specification of pdrbal execution time information)	Y	Y
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)	Y	Y
option statement (Specification of optional functions)	Y	Y

Y: Specifiable.

--: 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.