set format

[set dam_update_block=maximum-number-of-blocks-to-be-updated]
[set dam_added_file=maximum-logical-file-count-added-online]
[set dam_update_block_over=flush|error]
[set dam_message_level=1|0]
[set dam_tran_process_count=number-of-concurrently-executing-
                            transaction-branches]
[set dam_cache_size|dam_cache_size_fix=buffer-area-size]
[set dam_cache_attribute=free|fixed]
[set dam_io_interval=execution-interval-time]
[set dam_transaction_access=global|branch]
[set dam_io_error_occur=stop|continue]
[set dam_cache_reuse_from=last|first]
[set dam_default_cache_num=default-boundary-for-reusing-cache-blocks]
[set dam_ex_refer_read=none|stay]
[set dam_max_block_size=maximum-block-length]
[set dam_kb_size=1000|1024]
[set watch_time=maximum-response-waiting-time]

command format

[damcache logical-file-name boundary-for-reusing-cache-blocks]
[damchlmt logical-file-name threshold-for-the-number-of-cache-blocks]
{{damfile [-{d|n[-f]}][-c] logical-file-name physical-file-name}}

The DAM service definition defines the execution environment to manage direct access files having the file restoration function.

dam_update_block=maximum-number-of-blocks-to-be-updated~<unsigned integer> ((1-32768)) <<8>>

Specify the maximum number of blocks to be updated.

According to this specification, the DAM service allocates an area of memory sufficient for the DAM service on the shared memory pool (dynamic shared memory) for the system service. If the specified value is too large, the shared memory pool (dynamic shared memory) is affected. Define the value not to affect the pool.

dam_added_file=maximum-logical-file-count-added-online~<unsigned integer> ((1-128)) <<8>>

Specify the maximum number of logical files to be added online.

Logical files can be added up to this specified number during online execution.

dam_update_block_over=flush|error~<<error>>

Specify whether the access function is to return an error if during a transaction, the number of updated blocks exceeds the maximum block count specified with the dam_update_block operand.

flush

Access function continues processing without returning an error. An input/output occurs when the maximum block count is exceeded, hence processing time will increase. Also, the number of collected journals will increase.

error

Access function returns an error.

dam_message_level=1|0~ <<1>>

Specify the level of the messages output by the DAM service.

0

All messages are output.

1

Lock error messages (KFCA01610-W) are not output.

dam_tran_process_count=number-of-concurrently-executing-transaction-branches~<unsigned integer> ((0-8192))

Specify the number of transaction branches to be executed concurrently to access the DAM file. An area is secured as a function of this specified value.

For a value of 1 or greater, the specified number of areas will be secured during on-line startup. If the specified number cannot be secured, online operation proceeds with only the secured areas. Also, the secured areas are released upon termination of the online session.

For a value of 0, areas are secured upon execution of a transaction. The secured areas are released upon completion of the transaction.

If the operand is not specified, areas are secured when the UAP is started. The secured areas are released upon termination of the UAP.

Note that if 0 is specified or if the secured areas are insufficient, processing will be delayed since areas are secured with execution of the transaction.

Take note that a large value will cause shared memory to be compressed. Take the usable memory into consideration when specifying a value.

dam_cache_size|dam_cache_size_fix=buffer-area-size~<unsigned integer> ((10-1000000)) (Unit: kilobytes)

In the dam_cache_size operand or the dam_cache_size_fix operand, specify the size of the buffer area for stacking the blocks that are referenced or updated online when the system starts. The value specified for the dam_cache_size_fix operand takes precedence over the value specified for the dam_cache_size operand.

When you specify dam_cache_size, specify a value greater than the value that is calculated using the following expression for determining the assumed buffer area size.

Expression for determining the assumed buffer area size

Buffer area size = A + B

A: (Mb 64 + 1) x 128 x n x Tr

B: { (A 576) } x 32 + 64

Mb: Either of the following values, whichever is greater, with 8 added

• Block length in a file with the maximum block length among the logical files defined in the DAM service definition (block length specified in the damload command or the dc_dam_create function)
• Maximum block length specified in the dam_max_block_size operand of the DAM service definition

n: Maximum number of updated blocks specified in the dam_update_block operand of the DAM service definition

Tr: Number of transaction branches specified in the dam_tran_process_count operand of the DAM service definition

: Round down the figure after the decimal point.

Note:

When you specify the -f option in the damfile definition command of the DAM service definition to use a DAM file with cacheless access, calculate the buffer area size by specifying for Mb a value obtained by adding 8 to either of the following values, whichever is greater, and specify the calculated value in the dam_cache_size_fix operand.

• Block length in a file with the maximum block length among the non-cacheless access logical files defined in the DAM service definition (block length specified in the damload command or the dc_dam_create function)
• Value specified in the dam_max_block_size operand of the DAM service definition

To specify all DAM files for cacheless access, specify 10 in the dam_cache_size_fix operand.

When you specify 0 for the dam_tran_process_count operand, the system assumes 8 as the number of transaction branches to be executed simultaneously. If you do not specify the dam_tran_process_count operand, the system uses the value specified in the trn_tran_process_count operand in the transaction service definition as the number of transaction branches to be executed simultaneously.

If you omit the dam_cache_size operand or if you specify a value smaller than the value automatically calculated by the DAM service in the buffer area calculation expression, the DAM service secures the buffer area using the value calculated in the expression.

The value calculated in the expression for determining the assumed buffer area size is the maximum buffer area size that is calculated based on the operands specified in the DAM service definition. Therefore, the DAM service may not be able to secure the buffer area size determined in the calculation. In that case, the DAM service secures half of the calculated size until the determined buffer area size can be secured.

If you specify an unspecifiable value in the dam_cache_size operand or the dam_cache_size_fix operand, the KFCA01644-I message will be output.

If the DAM service cannot secure the buffer area size specified in the dam_cache_size or dam_cache_size_fix operand due to an insufficient buffer area, the KFCA01648-E message will be output and the DAM service and the UAP will stop.

Note that if a DAM file that is updated by deferred updating has been specified, in addition to the buffer area size calculated in the expression shown above, the size estimated from the following formula is required:

Formula for estimating the value to be added:

Number of transactions that were executed within the execution interval^# and that remain for lazy write processing x total of the DAM file block sizes updated in the transactions

#

Execution interval time specified in the dam_io_interval operand of the DAM service definition

The difference between the dam_cache_size operand and the dam_cache_size_fix operand is as follows:

When dam_cache_size is specified

When you specify dam_cache_size, the value specified in dam_cache_size or the value calculated in the expression for determining the assumed buffer area size, whichever is greater, is used.

If you do not specify the dam_cache_size operand or if you specify an unspecifiable value in the dam_cache_size operand, the KFCA02530-I message will be output and the value determined by the expression will be used. When you specify the dam_cache_size_fix operand, the value specified in the dam_cache_size_fix operand takes precedence.

When dam_cache_size_fix is specified

The value specified in the dam_cache_size_fix operand takes precedence.

If you do not specify the dam_cache_size_fix operand or if you specify an unspecifiable value in the dam_cache_size_fix operand, the value specified in the dam_cache_size operand will be used if the operand is specified. If the dam_cache_size operand is not specified, the KFCA02530-I message will be output and the value calculated in the expression will be used.

Advantages of specifying dam_cache_size_fix

The value specified in the dam_cache_size operand and the value calculated in the expression for determining the assumed buffer area size are based on the following values:

• Maximum block length in the DAM file specified in the DAM service definition (maximum block length of the file specified in the damfile command definition)
• Number of transactions to be executed simultaneously (value specified in the dam_tran_process_count operand)
• Maximum number of blocks updated in a transaction (value specified in the dam_update_block operand)

In the expression, the above three values are multiplied to determine the buffer area size. Even if the transaction uses only one DAM file with the maximum block length and only one block is updated in the transaction, the above expression is used. The DAM service secures a buffer size that is far greater than the necessary buffer size.

In this case, you can secure an optimum buffer by specifying an optimum buffer area size in the dam_cache_size_fix operand. However, when you use the dam_cache_size_fix operand, be careful with the value you specify. If the value specified in the dam_cache_size_fix operand is smaller than the buffer size that is actually needed, the buffer area becomes insufficient during online processing and the processing cannot continue. If any of the DAM files to be used is specified for deferred update specification, you should consider the number of blocks to be deferred within the execution interval and the total length of the deferred blocks (value specified in the dam_io_interval operand) when you estimate the buffer area size

The following table shows the relationship between the dam_cache_size operand and the dam_cache_size_fix operand, and the values to be used.

Legend:

(1): The value specified in dam_cache_size is used.

(2): The value specified in dam_cache_size_fix is used.

(3): The value calculated in the expression is used and the KFCA02530-I message is output.

If the buffer area becomes insufficient and processing cannot continue, an abort code will be output. Check the abort code and perform countermeasures accordingly. For details about the abort code, see the manual OpenTP1 Messages.

You should also reconsider the buffer area size when you change the system definition or environment, for example when you change the configuration of a DAM file.

The shared memory size required for a resource manager is the cache size specified in the dam_cache_size_fix operand.

dam_cache_attribute=free|fixed~<<free>>

Specify whether to fix the buffer area allocated on shared memory. When specifying this operand, consider the capacity of memory installed and the percentage of the buffer area in the total memory size. Specify the operand independently of the deferred update function.

free

The buffer area is not fixed on memory. If the size of the real memory is small, paging of the shared memory may occur, causing a slower processing speed.

fixed

The buffer area is fixed on memory. The processing speed is not lowered by shared memory paging. If the size of the real memory is small, paging of text or segments on areas other than the shared memory may occur.

fixed can be specified only when the OS is HP-UX or Solaris. Note that even when the OS is solaris, fixed cannot be specified depending on the environment being used in some cases. For details, see the Release Notes.

dam_io_interval=execution-interval-time~<unsigned integer> ((1-60)) <<1>> (Unit: seconds)

Specify the interval of execution of output processes when the deferred update function is used. This specification is unnecessary if the deferred update function is not used.

Too large an interval may cause an insufficient buffer area, making it impossible to write blocks that are to be updated or output in other transactions. The resulting memory shortage can cause a UAP to go down. When specifying the interval, therefore, consider the maximum number of transactions that will terminate within the execution time interval and the number of blocks to be updated or output in each transaction (required buffer size).

dam_transaction_access=global|branch~<<branch>>

Specify the unit of transactions which provides data management and lock management of DAM files.

global

Data management and lock management of files are performed in units of global transactions. When global is specified, the file-based lock cannot be specified when opening a logical file.

branch

Data management and lock management of files are performed in units of transaction branches. For different transaction branches, an access error occurs even for the same global transaction.

dam_io_error_occur=stop|continue~<<continue>>

This specifies the action for the DAM service available if a disk error (I/O error) occurs during the updating of a disk.

The DAM service involves disk updating during the transaction synchronization point processing. Otherwise, disk updating takes place as an extension to the DAM service access function when the transaction uses the halfway update facility. In this case, the action for the DAM service is available if an error occurs during the updating of a disk.

With respect to disk errors during deferred updating or non-recovery file updating, there are no differences depending on specified values. If there is a disk error during deferred updating, the system issues the KFCA01646-E or KFCA01642-I message and continues processing with non-faulty files. If there is a disk error during non-recovery file updating, the system issues the KFCA01646-E or KFCA01642-I message and the dc_dam_rewrite() function or the dc_dam_write() function returns DCDAMER_IOER.

stop

Abnormally terminates the UAP involving DAM access. A critical situation causes the system to stop. The KFCA01622-E or KFCA01646-E message indicates a file has an error. Remove the cause of the error or assign a new different volume. Then execute the damfrc command to perform file recovery.

Here are procedures for file recovery.

1. Executing the damfrc command
   Before you restart OpenTP1, use the damrstr command to restore the backup data and execute the damfrc command. The file is recovered using the journal information up to the point the system went down.
   
2. Restarting OpenTP1
   Restart OpenTP1.
   
3. Releasing the file
   When you restart OpenTP1, the failed file is still shut down due to the error. Execute the damrles command to release the file.
   
4. Settling the transaction
   Execute the damrles command to let you access the file. OpenTP1 provides recovery (settlement) processing to the transaction, which is then completed. This process results in better data integrity.
   Before the execution of the damrles command, the system continues to issue either of the messages KFCA01623-E (file being separated) and KFCA01624-E (file being blocked). The KFCA01623-E and KFCA01624-E inform the user the reason why, recovery of the transaction is impossible.
   

continue

If a disk error occurs during DAM access, the system issues the KFCA01618-E, KFCA01622-E, and KFCA01642-I messages and brings abnormally terminates the UAP.

In the case of a transaction under synchronization point processing, the system issues the KFCA01622-E and KFCA01642-I messages to complete the transaction (commitment settled: The OpenTP1 log is normally terminated and the function's return value is seen in DC_OK). In this case, the transaction has been completed normally, but the file having the error has not reflected the data updated in the transaction.

Because continuing the application processing in this state would result in poor data integrity, take the file having the error offline. Then, use the damrstr and damfrc commands to recover the file logically, use the damadd command to add the corrected file, and use the damrles command to release the file. Terminate the UAP when you separate or recover the file, or add a new file.

dam_cache_reuse_from=last|first~<<last>>

This operand specifies the cache block the DAM service first retrieves for reuse if the transaction that accesses a DAM file requires a new cache block area. When the DAM service updates a cache block, the DAM service connects it to the beginning of the reference cache block chain.

last

The DAM service retrieves cache blocks to be reused, starting from the last cache block in the reference cache block chain managed by the DAM service. That is, when last is specified, the DAM service starts to reuse cache blocks from the oldest cache block connected to the reference cache block chain.

first

The DAM service retrieves cache blocks to be reused, starting from the first cache block in the reference cache block chain managed by the DAM service. That is, when first is specified, the DAM service starts to reuse cache blocks from the latest cache block connected to the reference cache block chain.

Even if you specify last, if the oldest cache block is being accessed by another transaction, the applicable transaction does not retrieve it for reuse when it attempts to retrieve cache blocks to be reused. In this case, the next oldest cache block is retrieved for reuse. The DAM service determines which cache block is the oldest in the cache block chain and, unlike the LRU (Least Recently Used) method, it does not rearrange the cache block chain even if cache blocks are accessed recently. The DAM service retrieves cache blocks that were accessed and are oldest in the cache chain.

dam_default_cache_num=default-boundary-for-reusing-cache-blocks> ~<unsigned integer>((0-4000000))<<0>>

This operand specifies the default boundary for reusing cache blocks. The value specified in this operand is the boundary for logical files if you do not specify the boundary for reusing cache blocks in the damcache command.

dam_ex_refer_read=none|stay ~<<none>>

This operand specifies whether the transaction that accesses a DAM file should leave the blocks to be read with the locked reference specification in the cache buffer area until the transaction is determined.

Note the following when you use this operand:

• Add the number of blocks for which a locked reference read is to be executed to the dam_update_block operand (number of blocks that can be updated by a single transaction) in the DAM service definition.
• When you are using the halfway update facility for transactions, if you make an entry for locked reference using this facility, update the entry, and then update a block (dc_dam_rewrite()), the data in the update target block might be actually updated during a transaction. If the data in the update target block is actually updated, the block may not stay in the cache buffer area until the transaction is terminated. Cache blocks that are not updated will remain until the transaction is determined.
• The entry for locked reference will not be released from the lock until the transaction is concluded.

none

When the DAM service returns the data in the cache block that is read with locked reference specification to the user program, the DAM service treats the cache block as a reusable block. These cache blocks will not be immediately reused if the cache buffer area has free space. Cache blocks may be reused when the free space in the cache buffer area runs short.

Specify none if the DAM block to be accessed has no special purpose.

stay

The DAM service keeps the cache block that is read with locked reference specification in the cache buffer area until the transaction is determined like update specification. To increase the cache hit rate, you should specify stay if you frequently execute locked reference reads for a specific DAM block.

Note the following when you specify stay:

• You need to add the number of blocks to be read for locked reference in the dam_update_block operand specified in the DAM service definition. You should also add the value in the dam_update_block operand to increase the size of the dynamic shared memory for OpenTP1.
• If you do not add the value of the dam_update_block operand, the following may occur:

1. If you are using the halfway update facility for transactions
   If the sum of the number of blocks read for locked reference and update, and the number of updated blocks (dc_dam_write()) in a transaction exceeds the value specified in the dam_update_block operand, the halfway update processing will be executed and data will be actually updated. If there are too many blocks to be read for locked reference, the halfway update processing will be executed many times, updating data frequently.
   
2. If error is specified for the dam_update_block_over operand in the DAM service definition
   If the total of the number of blocks read for locked reference and update, and the number of updated blocks (dc_dam_write()) in a transaction exceeds the value specified in the dam_update_block operand, the executed API will return an error with DCDAMER_JNLOV. If there are too many blocks read for locked reference, the number of error returns with DCDAMER_JNLOV increases.
   

dam_max_block_size=maximum-block-length~<unsigned integer> ((504-32760))^# <<504>> (units: bytes)

#: Specify a value that satisfies the following expression: sector length x n - 8 (n is a positive integer).

Specify the maximum block length in the DAM file in the system. However, a different block length may be used as the maximum block length in some cases. The following table describes the relationship between the conditions that cause such cases and the maximum block length to be employed.

Legend:

a: Value of the dam_max_block_size operand in the DAM service definition

b: Block length in the file that has the largest block length, from among the logical files defined in the DAM service definition

#1: KFCA00216-E and KFCA01644-I are output.

#2: KFCA02565-I is output.

dam_kb_size=1000|1024~<<1000>>

When the size of the buffer area allocated as the shared memory for the DAM service is specified in the dam_cache_size operand of the DAM service definition ($DCDIR/conf/dam) in kilobytes, the value is automatically converted to the number of bytes. In this case, specify whether 1 KB is handled as 1000 bytes or 1024 bytes.

1000

1 KB is handled as 1000 bytes.

1024

1 KB is handled as 1024 bytes.

watch_time=maximum-response-waiting-time~<unsigned integer> ((0-65535)) (Unit: seconds)

Specify the maximum waiting time between sending a service request and receipt of a response when communicating between processes by RPC.

OpenTP1 may suspend termination processing for the length of time specified in this operand. Therefore, if you specify a large value, the termination processing of OpenTP1 may take some time.

If no response is received within the specified time, RPC returns a transmission timeout error.

Specify 0 if the system is to wait for a response. When you specify 0, OpenTP1 may not terminate.

If this operand is omitted, the value specified with the watch_time operand of the system common definition is assumed.

Use the default of the watch_time operand of the system common definition for this operand.

We recommend that you do not change the operand unless special tuning is necessary.

If a value that is much greater or smaller than the default of the watch_time operand of the system common definition is specified, a failure may occur causing OpenTP1 to go down.

Described on the following page.