ANSI C, C++

#include <dcdam.h>
int dc_dam_open (char *lfname, DCLONG flags)

K&R C

#include <dcdam.h>
int dc_dam_open (lfname, flags)
char     *lfname;
DCLONG   flags;

The function dc_dam_open() opens a logical file.

• For recoverable DAM files
  Whether to apply file-based or block-based lock is specified for the logical file. File-based lock can be applied when:
  
  • The logical file is opened within the transaction range under the condition that lock control for individual transaction branches is specified.
  In the following conditions, file-based lock cannot be applied. Use block-based lock:
  
• The logical file is opened outside the transaction range.
• Lock control for individual global transactions is specified.
  If a logical file is closed by the function dc_dam_close() and is again opened in the same transaction branch, the status before the function dc_dam_close() is called is inherited.
  
• For unrecoverable DAM files
  Since the transaction is not synchronized, no lock is needed.
  

lfname

Within 1 to 8 bytes, specify the name of a logical file to be opened.

flags

Specify the following items in the format below:

• File-based lock or blocks
• Whether the function is to wait for the resource to be released from lock if a lock error occurs.
  

  {DCDAM_FILE_EXCLUSIVE|DCDAM_BLOCK_EXCLUSIVE [|DCDAM_WAIT|DCDAM_NOWAIT|]}

• Flag 1
  Specify files-based lock or blocks.
  DCDAM_FILE_EXCLUSIVE: Files-based lock
  DCDAM_BLOCK_EXCLUSIVE: Blocks-based lock
  
• Flag 2
  Specify whether the function is to wait for the resource to be released from lock if an lock error occurs in the function,
  DCDAM_WAIT: The function waits for the resource to be released from lock.
  DCDAM_NOWAIT: The function does not wait for the resource to be released from lock, and returns with an error.
  The default is DCDAM_NOWAIT.
  

The value specified for flags depends on whether the DAM file is recoverable.

• For recoverable DAM files
  DCDAM_WAIT (flag 2) is specified if a lock error occurs in the function dc_dam_read() or dc_dam_write(). It is not specified if a lock error occurs in the function dc_dam_open(). If a lock error occurs in the function dc_dam_open(), the function unconditionally returns with the error value DCDAMER_EXCER.
  The table below shows the correspondence between the value specified for flags and the type of lock when a recoverable DAM file is accessed.
  

  Flag 1	Flag 2#	Lock Specified for Flags
  FILE_EXCLUSIVE	--	Files-based lock
  BLOCK_EXCLUSIVE	WAIT	Blocks-based lock, and waiting for release from lock if a lock error occurs
  	NOWAIT	Blocks-based lock, and error return if a lock error occurs

  Legend:

  --: Cannot be specified.

  #: The default is NOWAIT.

  
  
• For unrecoverable DAM files
  DCDAM_WAIT (flag 2) is specified if a lock error occurs. If a lock error occurs in the function dc_dam_open(), dc_dam_read(), or dc_dam_write, whether to wait for lock to be released is determined according to the value specified for flag 2. When DCDAM_NOWAIT is specified for flag 2 or omitted and if a lock error occurs, the function returns with the error value DCDAMER_EXCER.
  The table below shows the correspondence between the value specified for flags and the type of lock when an unrecoverable DAM file is accessed.
  

  Flag 1	Flag 2#	Lock Specified for Flags
  FILE_EXCLUSIVE	WAIT	Files-based lock, and waiting for release from lock if a lock error occurs
  	NOWAIT	Files-based lock, and error return if a lock error occurs
  BLOCK_EXCLUSIVE	WAIT	Blocks-based lock, and waiting for release from lock if a lock error occurs
  	NOWAIT	Blocks-based lock, and error return if a lock error occurs

  #: The default is NOWAIT.

  
  

When files-based lock is specified for flag 1, no lock error occurs in the function dc_dam_read() or dc_dam_write() because all files are locked regardless of recoverable or unrecoverable files. Therefore, whether to wait for release from lock cannot be specified. The lock release wait type specified for the argument of the function dc_dam_read() or dc_dam_write() is ignored.