To open a DAM file, use the function dc_dam_open() [CBLDCDAM ('OPEN')] in which the logical file name is specified. When the DAM file is opened, the file descriptor is returned as the name for identifying the file. For processing after the file is opened, specify this file descriptor in the function to access the file (e.g., file input, update, or output). To close the DAM file, use the function dc_dam_close() [CBLDCDAM('CLOS')] in which the file descriptor is specified. Shut down the file descriptor in the UAP even for processing after the file is opened.

A file descriptor becomes valid in the following cases:

• When the file is opened within the transaction processing range
  The file descriptor remains valid until one of the following events occurs:
  
  • Logical file is closed
  • Transaction synchronization point is acquired
  • UAP process is terminated
• When the file is opened outside the transaction processing range
  The file descriptor remains valid until one of the following events occurs:
  
  • Logical file is closed
  • UAP process is terminated

Use the logical file name to logically shut down the DAM file, release the DAM file from the shutdown state, or reference the status of the DAM file during processing.

Consecutive blocks can be input/output collectively. When inputting/outputting a DAM file, specify an access block range as a structure in the corresponding function. The block range must be specified with the relative block number. More than one structure can be specified.

To reference a DAM file block, enter the block by using the function dc_dam_read() [CBLDCDAM('READ')]. At this time, you can also specify whether to allow another transaction to reference/update the block.

To update a DAM file block, enter the block by using the function dc_dam_read(), then call the function dc_dam_rewrite() [CBLDCDAM ('REWT')] to update the block.

Call the function dc_dam_write() [CBLDCDAM('WRIT')] when you want to overwrite a block without entering a block from a DAM file.

If a logical conflict is found during processing for a DAM file block, the UAP can call the function dc_dam_hold() [CBLDCDAM('HOLD')] to shut down the DAM file so that another UAP cannot access the DAM file. The UAP can also call the function dc_dam_release() [CBLDCDAM ('RLES')] to release the DAM file from the shutdown state.

The figure below shows the procedure for accessing DAM files in online mode.

Figure 4-2 Access to DAM files in online mode

If an error occurs during access from a transaction process to a DAM file, call the function abort() from the UAP in order to terminate the transaction process abnormally.

Depending on the function that accessed the file previously, an access to a block 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 within the same transaction or from a different transaction. Tables 4-1 and 4-2 list functions which can access DAM file blocks if particular functions were previously called.

Table 4-1 Functions able to access the same block in one transaction (recoverable DAM files)

Previously called function	Function to be called	Results or error return value
No function for accessing a DAM file has been called in the transaction	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)	Y
	dc_dam_read (input for update)	Y
	dc_dam_rewrite (update)	Y
	dc_dam_rewrite (update cancellation)	Y
	dc_dam_write (output)	DCDAMER_SEQER (01605)
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-2 Functions able to access the same block in different transaction (recoverable DAM files)

Previously called function	Function to be called	Results or error return value
No function for accessing a DAM file has been called in the transaction	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)	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_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)	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 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)	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)#

Legend:

Y: No error

#

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

DAM service functions return with a DCDAMER_PROTO error ("01600" in the case of COBOL) for the following reasons. The reason varies with the function called:

1. The function dc_rpc_open() (CBLDCRPC('OPEN ') in the case of COBOL) has not been called.
2. For recoverable DAM files, atomic_update=N is specified in the user service definition.
3. The UAP is not correctly linked as follows:
   
   • The library (-ltdam) to be used for access to a TAM file through the DAM service API is incorrectly linked.
   • The transaction control object file is incorrectly registered with the resource manager.
4. The function dc_dam_start() (CBLDCDAM('STRT') in the case of COBOL) has not been called when the atomic_update = N in the user service definition (for unrecoverable DAM files).

The status of a DAM file in use can be referenced in online mode. Call the function dc_dam_status() [CBLDCDAM('STAT')] to reference the status of a DAM file. This function allows referencing of the following information:

• Number of logical file blocks
• Length of a logical file block
• Name of the physical file associated with a logical file
• Current status of a logical file (whether the file is shut down or not)
• Logical file attributes specified in the DAM service definition
• Logical file security attributes specified in the DAM service definition

(a) Note on using the function dc_dam_status()

When the function dc_dam_status() is called, the DAM service locks the file to acquire the information. Therefore, frequent use of this function may cause lock waits and reduced throughput. The status of a DAM file should be referenced in online mode as little as possible.