Locking DAM files

Suppose that, when a DAM file is being updated, an interrupt for updating the same file comes from another UAP. Two updates would then be reflected on the same logical file and would cause inconsistencies in the file. To avoid this, the function to access a file can contain a specification for locking the file. Through this lock control, data consistency can be assured on DAM files even when they are accessed from more than one UAP.

Transaction range for access to DAM files (recoverable DAM files)
When DAM files are accessed, they can be locked for each transaction branch. This could cause the following situation: Access from multiple transaction branches belonging to one global transaction to the same block or file could cause a lock error. To avoid this, it is also possible to lock files for each global transaction. To use this type of locking, the DAM service definition for the DAM files must include the specification that the files be accessed from each global transaction.
When locking for each global transaction is in effect, access from a transaction branch to a DAM file will not be parallel, but sequential. This could lower the transaction performance. If DAM files are to be accessed in parallel from each transaction branch, locking for each global transaction must not be specified.

Organization of this subsection: (1) Lock modes; (2) Lock units (recoverable DAM files); (3) Specification of waiting for a resource to be released from lock; (4) Lock in online mode and offline mode

(1) Lock modes

Lock conditions for accessing DAM files are called lock modes. The following lock modes are available:

Lock for reference (shared mode PR Protected Retrieve):: The UAP can only reference files with lock specified. Other transactions are permitted only to reference the files.

Lock for update (exclusive mode EX EXclusive):: The UAP can reference and update files with lock specified. Other transactions are not permitted to reference or update the files.

(2) Lock units (recoverable DAM files)

Lock can be specified in units of blocks or files when a DAM file is accessed in online mode as explained below.

(a) Block-based locks

Lock is enabled in blocks. When a block is referenced, the lock of the shared mode is enabled. When a block is updated or output, the lock of the exclusive mode is enabled. The specification of lock for reference can be disabled by specifying no lock in the option (other UAPs allowed to reference/update blocks). The specification of the acquired lock is reset when the transaction processing that specified processing for the DAM file terminates normally.

(b) File-based lock

Each logical file can be locked. If locking of a logical file is specified, the entire file will be locked during the period from the time the file is opened to the time the transaction process terminates normally.

File-based lock can be specified in the following condition:

Locking for each transaction branch is specified and the logical file was opened within the transaction range.

File-based lock cannot be specified in the following cases. Use block-based lock.

The logical file was opened outside the transaction range.
Locking for each global transaction was specified.

(3) Specification of waiting for a resource to be released from lock

dc_dam_open()
If an attempt is made to input data from or output data to a block which is locked by another transaction (lock error), the function for this access will return with an error or wait until the block is unlocked. This can be specified in the argument to the function dc_dam_open() for opening the DAM file.
If a DAM file is opened under file-based locks, waiting for release from lock (lock wait type) cannot be specified.
If a lock error occurs when a file is opened by using the function dc_dam_open(), the function unconditionally returns with the error.
dc_dam_read() and dc_dam_write()
The functions dc_dam_read() and dc_dam_write() can specify whether, when a lock error occurs, it will return or wait until the resource is unlocked. If this specification is omitted, the value specified in the function dc_dam_open() is assumed.
If wait until unlocking is specified and a deadlock or timeout occurs, deadlock information will be output after the function waiting for an unlocked resource returns with an error. If the function returns with a deadlock or timeout error, acquire the synchronization point of the transaction and free all the acquired resources.

(4) Lock in online mode and offline mode

A DAM file being used in online mode cannot be accessed in offline mode. To access a DAM file, being used in online mode, in offline mode, use the damhold and damrm command to switch the online mode to the offline mode. Then, use the damadd command to switch the DAM file back into the online mode.