OpenTP1 Version 7 Programming Guide

[Contents][Index][Back][Next]

4.1.8 Access to unrecoverable DAM files

You can create a DAM file which does not guarantee consistency management or error recovery through transactions. This DAM file is called an unrecoverable DAM file. Unrecoverable DAM file blocks can be updated using the functions dc_dam_write() and dc_dam_rewrite() instead of transaction processing.

Organization of this subsection
(1) Definition of unrecoverable DAM files
(2) Access to unrecoverable DAM files
(3) Action to be taken in case of file access error
(4) Relationship between functions for accessing unrecoverable DAM files
(5) Locking unrecoverable DAM files
(6) Comparison between recoverable and unrecoverable DAM files

(1) Definition of unrecoverable DAM files

To define an unrecoverable DAM file, specify the definition command damfile with the -n option in the DAM service definition.

(2) Access to unrecoverable DAM files

Before accessing a file, call the function dc_dam_start() [CBLDCDAM ('STRT')]. When completing the file access, call the function dc_dam_end() [CBLDCDAM ('END ')]. When the function dc_dam_start() is called, the function dc_dam_end() must be called after the file access is terminated.

An unrecoverable DAM file is accessed using a DAM service function. An unrecoverable DAM file can be accessed just like a recoverable DAM file.

The file descriptor returned when a file is opened remains valid until one of the following events occurs:

(3) Action to be taken in case of file access error

Even if an error occurs during the access to an unrecoverable DAM file, the file data error cannot be recovered.

The figure below shows the procedure for accessing an unrecoverable DAM file.

Figure 4-5 Procedure for accessing unrecoverable DAM file

[Figure]

(4) Relationship between functions for accessing unrecoverable DAM files

Depending on the function that accessed the file previously, an access to a block even from the same UAP process may cause return with an error. The result of access (normal return or error return) varies depending on whether the function for the access is called from the same UAP or from a different UAP. Tables 4-3 and 4-4 list functions which can access DAM file blocks if particular functions were previously called.

Table 4-3 Functions able to access the same block in one UAP (unrecoverable DAM files)

Previously called function Function to be called Results or error return value
No function for accessing a DAM file has been called after the function dc_dam_start() was called c_dam_read (input for reference) Y
dc_dam_read (input for reference, lock specified) Y
c_dam_read (input for update) Y
c_dam_rewrite (update) DCDAMER_SEQER (01605)
dc_dam_rewrite (update cancellation) DCDAMER_SEQER (01605)
dc_dam_write (output) Y
dc_dam_read (input for reference) dc_dam_read (input for reference) Y
dc_dam_read (input for reference, lock specified) Y
dc_dam_read (input for update) Y
dc_dam_rewrite (update) DCDAMER_SEQER (01605)
dc_dam_rewrite (update cancellation) DCDAMER_SEQER (01605)
dc_dam_write (output) Y
dc_dam_read (input for reference, lock specified) dc_dam_read (input for reference) Y
dc_dam_read (input for reference, lock specified) Y
dc_dam_read (input for update) Y
dc_dam_rewrite (update) DCDAMER_SEQER (01605)
dc_dam_rewrite (update cancellation) DCDAMER_SEQER (01605)
dc_dam_write (output) Y
dc_dam_read (input for update) dc_dam_read (input for reference) Y
dc_dam_read (input for reference, lock specified) Y
dc_dam_read (input for update) Y
dc_dam_rewrite (update) Y
dc_dam_rewrite (update cancellation) Y
dc_dam_write (output) Y
dc_dam_rewrite (update) dc_dam_read (input for reference) Y
dc_dam_read (input for reference, lock specified) Y
dc_dam_read (input for update) Y
dc_dam_rewrite (update) DCDAMER_SEQER (01605)
dc_dam_rewrite (update cancellation) DCDAMER_SEQER (01605)
dc_dam_write (output) Y
dc_dam_rewrite (update cancellation) dc_dam_read (input for reference) Y
dc_dam_read (input for reference, lock specified) Y
dc_dam_read (input for update) Y
dc_dam_rewrite (update) DCDAMER_SEQER (01605)
dc_dam_rewrite (update cancellation) DCDAMER_SEQER (01605)
dc_dam_write (output) Y
dc_dam_write (output) dc_dam_read (input for reference) Y
dc_dam_read (input for reference, lock specified) Y
dc_dam_read (input for update) Y
dc_dam_rewrite (update) DCDAMER_SEQER (01605)
dc_dam_rewrite (update cancellation) DCDAMER_SEQER (01605)
dc_dam_write (output) Y

Legend:
Y: No error

Table 4-4 Functions able to access the same block in different UAP (unrecoverable DAM files)

Previously called function Function to be called Results or error return value
No function for accessing a DAM file has been called after the function dc_dam_start() was called dc_dam_read (input for reference) Y
dc_dam_read (input for reference, lock specified) Y
dc_dam_read (input for update) Y
dc_dam_rewrite (update) DCDAMER_SEQER (01605)
dc_dam_rewrite (update cancellation) DCDAMER_SEQER (01605)
dc_dam_write (output) Y
dc_dam_read (input for reference) dc_dam_read (input for reference) Y
dc_dam_read (input for reference, lock specified) Y
dc_dam_read (input for update) Y
dc_dam_rewrite (update) DCDAMER_SEQER (01605)
dc_dam_rewrite (update cancellation) DCDAMER_SEQER (01605)
dc_dam_write (output) Y
dc_dam_read (input for reference, lock specified) dc_dam_read (input for reference) Y
dc_dam_read (input for reference, lock specified) Y
dc_dam_read (input for update) Y
dc_dam_rewrite (update) DCDAMER_SEQER (01605)
dc_dam_rewrite (update cancellation) DCDAMER_SEQER (01605)
dc_dam_write (output) Y
dc_dam_read (input for update) dc_dam_read (input for reference) Y
dc_dam_read (input for reference, lock specified) DCDAMER_EXCER (01602)#
dc_dam_read (input for update) DCDAMER_EXCER (01602)#
dc_dam_rewrite (update) DCDAMER_SEQER (01605)
dc_dam_rewrite (update cancellation) DCDAMER_SEQER (01605)
dc_dam_write (output) DCDAMER_EXCER (01602)#
dc_dam_rewrite
(update)
dc_dam_read (input for reference) Y
dc_dam_read (input for reference, lock specified) Y
dc_dam_read (input for update) Y
dc_dam_rewrite (update) DCDAMER_SEQER (01605)
dc_dam_rewrite (update cancellation) DCDAMER_SEQER (01605)
dc_dam_write (output) Y
dc_dam_rewrite (update cancellation) dc_dam_read (input for reference) Y
dc_dam_read (input for reference, lock specified) Y
dc_dam_read (input for update) Y
dc_dam_rewrite (update) DCDAMER_SEQER (01605)
dc_dam_rewrite (update cancellation) DCDAMER_SEQER (01605)
dc_dam_write (output) Y
dc_dam_write (output) dc_dam_read (input for reference) Y
dc_dam_read (input for reference lock specified) Y
dc_dam_read (input for update) Y
dc_dam_rewrite (update) DCDAMER_SEQER (01605)
dc_dam_rewrite (update cancellation) DCDAMER_SEQER (01605)
dc_dam_write (output) Y

Legend:
Y: No error

#
Waits until released from the lock state if DCDAM_WAIT is set in flags.

(5) Locking unrecoverable DAM files

As in the case of recoverable DAM files, unrecoverable DAM files can also be locked. The following gives an explanation of locking unrecoverable DAM files. For comparison between recoverable and unrecoverable DAM files, see Item (6) in 4.1.8 Access to unrecoverable DAM files.

(a) Unrecoverable DAM file locking range

Unrecoverable DAM files can be accessed regardless of the transaction processing range.

(b) Lock modes

The lock modes for unrecoverable DAM files are the same as for recoverable DAM files. For details, see (1) in 4.1.7 Locking DAM files.

(c) Lock units

The lock units for unrecoverable DAM files are the same as for recoverable DAM files. For details, see (2) in 4.1.7 Locking DAM files.

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

The specification of waiting for a resource to be released from lock in the case of unrecoverable DAM files is the same as in the case of recoverable DAM files except for the following point:

(6) Comparison between recoverable and unrecoverable DAM files

The following explains the comparison between recoverable and unrecoverable DAM files. Table 4-5 lists the differences in file access. Table 4-6 lists the differences in the locking range upon file access.

Table 4-5 Differences in access to recoverable and unrecoverable DAM files

DAM service function Conditions for calling function DAM file types and access positions
Recoverable DAM file Unrecoverable DAM file
Outside transaction processing range Within transaction processing range
dc_dam_open File-based lock, lock wait N Y Y
File-based lock, immediate return N Y Y
Block-based locks, lock wait Y Y Y
Block-based locks, immediate return Y Y Y
dc_dam_close Open a file within the transaction processing range Y Y Y
Open a file outside the transaction processing range -- N Y
dc_dam_read Input for reference, no lock Y Y Y
Input for reference, lock specified N Y Y
Input for update, lock specified N Y Y
dc_dam_rewrite Output for update N Y Y
Update cancellation N Y Y
dc_dam_write No condition N Y Y

Legend:
Y: Can be used for DAM files.
N: Returns with an error if called for DAM files.
--: Cannot be used for DAM files.

Table 4-6 Differences in locking range upon access to recoverable and unrecoverable DAM files

Lock unit# and function to be called Lock mode Recoverable DAM file Unrecoverable DAM file
File-based lock dc_dam_open EX
  • Locked until termination of synchronization point processing

  • Locked until termination of processing through dc_dam_close() or dc_dam_end()
Block-based locks dc_dam_read (reference) PR
  • Locked until termination of synchronization point processing

  • Locked until termination of processing through dc_dam_read()
dc_dam_read (update) EX
  • Locked until termination of synchronization point processing
  • Locked until termination of processing through dc_dam_rewrite() (cancellation)

  • Locked until termination of processing through dc_dam_rewrite() (update or cancellation)
dc_dam_write EX
  • Locked until termination of synchronization point processing

  • Locked until termination of processing through dc_dam_write()

#
This lock unit means that specified in the function dc_dam_open(). When file-based lock is specified in this function, the lock units specified in the functions dc_dam_read() and dc_dam_write() are invalid.