The pdbufmod command adds, deletes, or changes a global buffer during HiRDB operation.

The change made by pdbufmod is not inherited after the normal termination of unit or server. Therefore, you need to apply this change using the pdbuffer operand in the system definition before the next normal start of HiRDB. The pdchgconf command lets you change the system definitions without having to terminate HiRDB.

You can use the pdbufmod command if HiRDB Advanced High Availability has been installed.

HiRDB administrator

pdbufmod -k change-type -a global-buffer-name [{-r RDAREA-name[,RDAREA-name]...|-b RDAREA-name[,RDAREA-name]... |-o|-i authorization-identifier.index-identifier}] [-n buffer-sectors-count [-l buffer-size]] [-m maximum-concurrent-prefetch-operations-count] [-p maximum-batch-input-pages-count] [-w updated-output-page-rate-during-deferred-write-trigger] [-y update-buffer-sectors-count-for-deferred-write-trigger-event] [-W execution-monitoring-interval]

(a) -k change-type

Specifies the type of change to be made.

add:

Specifies that a new global buffer is to be added or another global buffer is to be added to the existing global buffers.

To add a new global buffer, make sure that the -n option is specified. If you are adding a new global buffer specifying the -r, -b, or -i option, the RDAREA or index to be specified must be defined beforehand.

If the existing shared memory segment does not have enough space, the new global buffer is created in a new shared memory segment.

del:

Specifies that a global buffer is to be deleted or specific RDAREAs are to be deleted from the global buffer.

To delete specific RDAREAs, specify the RDAREAs in the -r or -b option.

You must place the RDAREAs allocated to a global buffer to be deleted or the RDAREAs to be deleted from a global buffer in shutdown and closed status beforehand.

A global buffer allocated to in-memory RDAREAs cannot be deleted. To delete such a global buffer, first release the RDAREAs from memory, and then delete the global buffer.

upd:

Specifies that the global buffer definition is to be changed. The global buffer definition items include the buffer sectors count, buffer size, maximum number of concurrent prefetch operations, maximum number of batch input pages, updated output page rate during deferred write trigger, and update buffer sectors count during deferred write trigger.

Once the global buffer definition is changed, the contents of the global buffer cache are discarded.

If the change made to the global buffer definition results in an increase in the memory size for the global buffer and there is not enough space in the existing shared memory segment, the command creates the global buffer with the definitions in a new shared memory segment.

The following table shows the relationship between the change type and other options:

Other option	-k change-type
	add	del	upd
-a	M	M	M
-r	O	O	N
-b	O	O	N
-o	O#1	N	N
-i	O#1	N	N
-n	O#1, #2	N	O
-l	O#1	N	O
-m	O#1	N	O
-p	O#1	N	O
-w	O#1	N	O
-y	O#1	N	O

Legend:

M: Mandatory

O: Optional

N: Not specifiable

#1: You can specify this operand when a new global buffer is to be added.

#2: To add a new global buffer, make sure that this operand is specified.

(b) -a global-buffer-name ~<identifier> ((1-16))

Specifies the name of the global buffer to be added, deleted, or changed.

If you are specifying -k add (to add an RDAREA to an existing global buffer), -k del, or -k upd, specify the name of a global buffer that has already been defined. If you are specifying -k add (to add a new global buffer), specify a global buffer name that is unique in the server.

An in-memory data buffer cannot be specified in this option.

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

Specifies the names of the RDAREAs that are to be allocated to the global buffer or that are to be deleted from the global buffer.

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 number of buffer sectors with the -n option and also specify multiple RDAREAs for a single global buffer, the largest page size in the RDAREAs becomes the buffer size. Therefore, we recommend that you allocate RDAREAs with the same page size to a global buffer. If any of the RDAREAs with identical page size contains a table that serves a different purpose or to which frequent random or sequential access is made, that RDAREA should be allocate to a separate global buffer in order to improve buffering efficiency.
3. To specify a user RDAREA, the data dictionary RDAREA must be in one of the following statuses:
   Open and shutdown release status
   Open and command shutdown status
   

(d) -b RDAREA-name[,RDAREA-name]... ~<identifier> ((1-30))

Specifies the names of LOB RDAREAs that are to be allocated to the global buffer or that are to be deleted from the global buffer.

Effective specification method

Specify the following LOB RDAREAs:

• LOB RDAREA that stores a plug-in index
• LOB RDAREA with a small amount of data that is accessed frequently

We recommend that you allocate a single LOB RDAREA to a single LOB global buffer.

Rules

1. For the rules for specifying RDAREAs, see 1.5.2 Specification of RDAREAs in operation commands and utilities
2. You can specify data dictionary LOB RDAREAs, user LOB RDAREAs, and registry LOB RDAREAs. An error results if any other type of RDAREA is specified.
3. If you specify the -b option, you cannot specify the -m, -p, or -w option.
4. If you have not allocated the global buffer (when the -o option is specified), you must specify the LOB RDAREA specified in the -r option also in the -b option.
5. If you specify a user LOB RDAREA, the data dictionary RDAREA must be in one of the following statuses:
   - Open and shutdown release status
   - Open and command shutdown status
   

(e) -o

Specifies that a global buffer is to be allocated to all RDAREAs that are not specified with the -r option. You can specify the -o option only once. If this option is specified more than once, the first option specified takes effect.

(f) -i authorization-identifier.index-identifier

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

index-identifier: ~<identifier> ((1-30))

Specifies the name of the index (authorization-identifier.index-identifier) to which an index global buffer is to be allocated.

Effective specification method

Specify an index that is used frequently. By allocating a global buffer to a frequently-used index, you can reduce the number of input/output operations because the percentage of index pages made resident in memory increases.

This effect is especially large if you allocate an index defined for a cluster or unique key to a global buffer. Note that the index identifier of a cluster key is determined by HiRDB. After defining a table, search the dictionary table (INDEX_NAME column of SQL_INDEXES table) to obtain the index identifier.

Allocating all indexes to index global buffers degrades the overall utilization factor of global buffers. Therefore, carefully select the appropriate indexes for allocation of global buffers, taking memory size into consideration.

Rules

1. If an authorization identifier or an index identifier is enclosed between double quotation marks ("), it is treated as being case sensitive; otherwise, they are treated as being in all uppercase letters. Note also that if an index identifier contains a space, the entire identifier must be enclosed between double quotation marks ("). If you are using sh (Bourne shell), csh (C shell), or ksh (Korn shell), you must enclose the entire identifier between single quotation marks (').
2. If you specify authorization-identifier.index-identifier, the data dictionary RDAREA must be in one of the following statuses:
   - Open and shutdown release status
   - Open and command shutdown status
   

(g) -n buffer-sectors-count

In 32-bit mode: ~<unsigned integer> ((4-460000))

In 64-bit mode: ~<unsigned integer> ((4-1073741824))

Specifies the number of global buffer sectors.

Guidelines for specification value

• Specifying a value that is greater than necessary reduces the number of input/output operations, but it increases overhead for searching the buffer.
• A global buffer is allocated in shared memory. If its size is larger than necessary, frequent paging occurs when other memory is used, thereby adversely affecting the performance.
• Depending on the timing of synchronization point acquisition and the percentage of update pages in the global buffer, output operations may concentrate on the database. Therefore, you also need to take into account the balance of input/output operations.
• If there are too may buffer sectors, allocation of shared memory may fail.
• Determine the number of global buffer sectors based on the following table:
  

  Condition		Determining the number of global buffer sectors
  Global buffer with the -r or -o option specified	HiRDB single server configuration	Number of concurrent SQL processing requests number of pages used per SQL statement (about 3 to 6)
  	HiRDB parallel server configuration	Number of concurrently executable users average number of tables accessed concurrently per transaction 3 n#1
  Global buffer with the -b option specified		Total number of LOB RDAREAs percentage of residency#2(%)
  Global buffer with the -i option specified		Number of pages containing index percentage of residency#3(%)

#1: The buffer hit rate cannot be improved by the number of buffer sectors obtained based on n=1. Therefore, determine the appropriate buffer space as a coefficient (buffer hit rate).

#2: Although the desired percentage of residency is 1 (100%), determine this value taking into account some factors, such as the memory capacity and the frequency of data access. For details about the total number of pages in a user LOB RDAREA and a register RDAREA, see the HiRDB Version 9 Installation and Design Guide.

#3: Although the desired percentage of residency is 1 (100%), determine this value taking into account such factors as the memory size and the importance of the index. For details about the total number of pages in an index, see the HiRDB Version 9 Installation and Design Guide.

• Set this value in such a manner that the buffer hit rate becomes 80% or higher for applications using HiRDB. You can check the buffer hit rate with the following methods:
  - Update buffer hit rate and reference buffer hit rate provided by the statistics analysis utility (statistical information on global buffers).
  - pdbufls command's header name HIT
  

(h) -l buffer-size ~<unsigned integer> ((even number in the range 4-30))

Specifies the size of the global buffer in kilobytes. Specify this option together with the -n option.

Guidelines for specification value

Normally, you will omit this option, in which case the command assumes the maximum page size of the RDAREAs allocated to this global buffer as the buffer size. In the following cases, however, consider specifying a value:

• If you intend to add an RDAREA whose page length will be greater than this value or you will increase the page length of an RDAREA by initializing it in the future, we recommend that you specify a sufficiently large value in this option. However, if you can terminate HiRDB, there is no need to specify such a large value because the maximum page length will be assumed for the buffer the next time HiRDB starts.

Rules

1. If this option's value is less than the maximum RDAREA page size, the command assumes the maximum RDAREA page size as the buffer size.
2. If you specify an odd number in this option, the command adds 1 to the specified value in determining the buffer size.

(i) -m maximum-concurrent-prefetch-operations-count ~<unsigned integer> ((0-95000)) <<0>>

Specifies the maximum number of prefetch operations that can be executed concurrently. When a character special file is used to search a large amount of data, the prefetch facility can reduce the input/output time.

If you specify 0 in this option or omit this option, the prefetch facility will not be used. To use the prefetch facility, you must specify 1 or a greater value.

Guidelines for specification value

This option specifies the number of concurrently executable SQL statements to which the prefetch facility is applied in tables that are contained in the RDAREAs allocated to the global buffer. The prefetch facility is applied to the following SQL statements, where a value of 2 is used as the execution count for 3:

1. SELECT, UPDATE, and DELETE statements that do not use an index (excluding the = and IN conditions)
2. SELECT, UPDATE, and DELETE statements that perform searches in ascending order^# using an index (excluding the = and IN conditions)
3. SELECT, UPDATE, and DELETE statements that perform searches in ascending order^# using a cluster key (excluding the = and IN conditions)

#: For a multicolumn index, the searches are conducted in the order specified in the index definition.

Rules

If you use the prefetch facility, you need to re-estimate the shared memory size because a buffer dedicated to batch input is allocated from the shared memory separately from the global buffers.

For details about the formulas for determining the size of shared memory required for the prefetch facility and global buffers, see the HiRDB Version 9 Installation and Design Guide.

(j) -p maximum-batch-input-pages-count ~<unsigned integer> ((2-256)) <<32>>

Specifies the maximum number of batch input pages for the prefetch facility. This specification is applicable only when 1 or a greater value is specified in the -m option.

Guidelines for specification value

Based on the shared memory size and cost performance, specify the value that satisfies the following condition:

 
a  b = 64 to 128 (kilobytes)
 
a: Page length of the RDAREA containing the data or index of the table that is subject to prefetch processing
b: Maximum number of batch input pages

(k) -w updated-output-page-rate-during-deferred-write-trigger

~<unsigned integer> ((0-100)) <<20>>

Specifies the percentage of updated output pages during deferred write trigger. For details about deferred write trigger, see the HiRDB Version 9 Installation and Design Guide.

If this operand's value is 0, the system does not output pages updated by deferred write trigger.

Guidelines for specification value

• Determine the appropriate value by checking the relevant information, such as the number of input/output operations per global buffer and the hit rate for updated pages, using the statistics analysis utility. If the hit rate for updated pages is high for a global buffer, specify a low output rate for this global buffer; if the hit rage is low, specify a high output rate.
• If the specified value is too large, update processing occurs frequently, resulting in frequent input/output operations. The number of pages to be written in the database also increases during delayed write processing, thereby adversely affecting throughput. On the other hand, if the specified value is too small, the number of pages to be written in the database increases during a synchronization point dump. Therefore, reduce the number of times the same pages are written in the database between synchronization point dumps.
• Specify a value of 0 if all pages are in the global buffer and the same pages are frequently updated by multiple transactions. This can reduce the total number of pages that are written in the database between the synchronization points.

(l) -y update-buffer-sectors-count-for-deferred-write-trigger-event

~<unsigned integer> ((2-2147483647))

Specifies the number of update buffer sectors for when deferred write processing is to be executed. When the number of update buffer sectors reaches the specified value, the deferred write trigger writes updated pages to the disk.

If the -y option is omitted, the number of update buffer sectors for the deferred write trigger event depends on the combination of the pd_dbbuff_rate_updpage and pdbuffer -y operands, as shown below:

pd_dbbuff_rate_updpage operand specification	pdbuffer -y operand specification	Number of update buffer sectors for deferred write trigger event
Specified	Specified	pdbuffer -y operand value
	Omitted	Number of global buffer sectors pd_dbbuff_rate_updpage operand value
Omitted	Specified	pdbuffer -y operand value
	Omitted	Determined by HiRDB

Specification guidelines

Normally, you omit this operand. There may be times when deferred write processing is not completed within the synchronization point interval. In such a case, you may want to reduce the writing time by reducing the number of updated buffers and accepting a slight reduction in the updated buffer hit rate; you do this by specifying this operand. Assume 50% (the initial value set by HiRDB) as the specification guideline, and determine the operand value by referring to the section Tuning the synchronization point processing time when deferred write processing is used in the manual HiRDB Version 9 System Operation Guide.

Rules

If the value specified in this option is greater than the number of global buffer sectors, the number of global buffer sectors is used.

Notes

If the value of the -y option is too small, there is an increase in the frequency of deferred write processing, resulting in an increase in workload. For this reason, it is important to specify an appropriate value based on the specification guidelines.

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

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

1. The pdbufmod command can be executed only while HiRDB is active.
2. The pdbufmod command must be executed at the server machine that contains the single server or where the system manager is located.
3. When the pdbufmod command is executed, the system locks the related RDAREAs and their RDAREA status in the EX mode. Any other transaction or utility accessing these RDAREAs is placed in the wait status.
4. You cannot execute the pdbufmod command in the following cases:
   
   • The rapid system switchover facility or standby-less system switchover facility is being used.
   • pd_dbbuff_modify=Y is not specified in the system definition.
5. You cannot execute more than one pdbufmod command at the same time.
6. The maximum number of global buffer sectors that can be defined and the maximum number of new shared memory segments that can be added are determined by the values of the pd_max_add_dbbuff_no and pd_max_add_dbbuff_shm_no operands in the system definition.

1. Deletion of shared memory segments that is accompanied by deletion of a global buffer may be delayed depending on the command's termination timing. To immediately delete them, execute the pdpfresh command.
2. If the unit is terminated or HiRDB is terminated forcibly while the pdbufmod command is executing, use the pdbufls -k def command after the restart to make sure that the previous operation has been completed. If it has not been completed, re-execute the pdbufmod command.
3. The following shows the pdbufmod command's return codes:
   0: Normal termination
   4: Warning termination (some server processing terminated abnormally)
   8: Abnormal termination
   12: Abnormal termination (an event occurred that prevented output of an error message)
   If the return code is 12, check the error message in syslogfile at the host where the single server or dictionary server is located, eliminate the cause of the error, and then re-execute the pdbufmod command. If no error message has been output to syslogfile, contact the customer engineer.
   

Example 1:

This example adds the global buffer gbuf01 and then allocates the added RDAREA RDAREA1 to this global buffer.

pdbufmod -k add .................1 -a gbuf01 ..............2 -r RDAREA1 .............3 -n 1000 ................4

Explanation

1. Specifies that a global buffer is to be added.
2. Name of the global buffer to be added
3. RDAREA to be allocated
4. Number of sectors for the global buffer

Example 2:

This example deletes the global buffer gbuf01 to which no RDAREA has been allocated.

pdbufmod -k del .................1 -a gbuf01 ..............2

Explanation

1. Specifies that a global buffer is to be deleted.
2. Name of the global buffer to be deleted

Example 3:

This example changes the number of sectors for the global buffer gbuf01 from 1,000 to 2,000.

pdbufmod -k upd .................1 -a gbuf01 ..............2 -n 2000 ................3

Explanation

1. Specifies that a global buffer definition is to be changed.
2. Name of the global buffer whose definition is to be changed
3. Number of buffer sectors after change