dc_dam_read - Input a logical file block

The function dc_dam_read() inputs a block (which is in the specified range) for reference or update processing from the specified logical file

For recoverable DAM files
Lock is enabled in units (files or blocks) as specified when the logical file was opened. The function dc_dam_read() can be called from a process out of the transaction range. In this case, however, the function can be used only for reference and lock cannot be specified.
When multiple blocks are specified at a time, an error returned if even one of the blocks causes an error. In this case, the blocks are not input to the input buffer. All the blocks for which an input request was made are released lock at this time.
Lock which is enabled for a block input for reference processing is released in the following case:
After the block is input for reference processing, an input request for update processing is made for the same block. Then, an input error occurs during the update processing.
Even if block update during a transaction is specified (dam_update_block_over=flush in the DAM service definition), an error is returned with DCDAMER_JNLOV in the following case:
- DAM file blocks are not updated in one transaction branch (dc_dam_rewrite()). The function dc_dam_read() (block input for update processing) is called. Eventually, the number of blocks exceeds the maximum number of blocks collectively updated (the value specified for dam_update_block of the DAM service definition).
When inputting a block of a recoverable DAM file, call the function dc_dam_read() from the transaction range.
For unrecoverable DAM files
There is no limit on the condition to call the function dc_dam_read() when a block of an unrecoverable DAM file is input.
For an unrecoverable DAM file, if the function dc_dam_read() for update is called more times than specified in dam_update_block in the DAM service definition, the function returns with the error value DCDAMER_ACSOV.

When inputting a logical file block, specify the file descriptor which is the return value of the function dc_dam_open().

damfd

Specify the file descriptor of the file containing a block to be input.

keyptr

Specify the address of the structure (DAM key) that indicates the block reference/update range. For the structure, specify the block range with the first relative block number and the last relative block number. The structure format is as shown below.

struct DC_DAMKEY {
                  int fstblkno;
                  int endblkno;
                 };

fstblkno
Specify the first relative block number of the block to be referenced or updated.
endblkno
Specify the last relative block number of the block to be referenced or updated. If 0 is specified, only the block of the relative block number specified for fstblkno is input.

keyno

Specify the number of structures (number of structure arrays) to be set for keyptr.

bufadr

Specify the address of the input buffer.

bufsize

Specify the length of the input buffer. The length must be equal to or greater than (input block length x number of blocks). You can specify a value in the range from 504 to 2147483647.

flags

Specify the type of request (reference request or update request) in the following format:

{DCDAM_REFERENCE|DCDAM_MODIFY}
[|{DCDAM_EXCLUSIVE|DCDAM_NOEXCLUSIVE}]
[|{DCDAM_WAIT|DCDAM_NOWAIT}]

Flag 1
Specify the purpose (reference or update) of the input request given by the function dc_dam_read():
DCDAM_REFERENCE: Input request for reference
DCDAM_MODIFY: Input request for update
Flag 2
Specify whether to apply lock if the input request is for reference. If DCDAM_EXCLUSIVE is specified, lock will remain until processing reaches the synchronization point.
To access a recoverable DAM file for reference from outside the transaction, lock cannot be specified.
If flag 2 is omitted, DCDAM_NOEXCLUSIVE is assumed.
If the function dc_dam_read() is called without lock application, the block could be updated by another UAP during the processing of the function dc_dam_read(). In this case, the details input to the block by the function dc_dam_read() depend on the update processing status on the other UAP. Therefore, to reference the latest block contents, be sure to specify DCDAM_EXCLUSIVE.
If the input request is for update, flag 2 cannot be given no explicit value (always DCDAM_EXCLUSIVE).
DCDAM_EXCLUSIVE: Lock is enabled.
DCDAM_NOEXCLUSIVE: Lock is not enabled.
Flag 3
Specify whether the function is to wait for the resource to be released from lock if a lock error occurs. This item cannot be specified together with DCDAM_NOEXCLUSIVE. If file-based lock is specified as the type of lock in the function dc_dam_open() in which the file descriptor is specified for damfd, the value specified for this option is meaningless.
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.

If both items are omitted, the subsequent processing is as follows:

If DCDAM_WAIT is specified in the function dc_dam_open(), the function waits for the resource to be released from lock.
If DCDAM_NOWAIT is specified in the function dc_dam_open() or it is omitted, the function returns with an error.

The table below shows the correspondence between flag values specified for flags and the specified type of lock.

Flag 1	Flag 2^#1	Flag 3^#2	Lock Specified for Flags
REFERENCE	EXCLUSIVE	WAIT	Input for reference, lock used, and waiting for release from lock if a lock error occurs
	EXCLUSIVE	NOWAIT	Input for reference, lock used, and error return if a lock error occurs
	NOEXCLUSIVE	N/A	Input for reference, and lock not used^#3
MODIFY	N/A	WAIT	Input for update, and waiting for release from lock if a lock error occurs
MODIFY	N/A	NOWAIT	Input for update, and error return if a lock error occurs

Legend:: N/A: Cannot be specified.

#1: The default is NOEXCLUSIVE.

#2: The default is the type of lock specified in the function dc_dam_open().

#3: For a recoverable DAM file, the function dc_dam_read() can be called from a process out of the transaction range only if flag 1 is given the value DCDAM_REFERENCE and flag 2 is given the value DCDAM_NOEXCLUSIVE or is omitted. If the function dc_dam_read() is called with other values specified for the flags from outside the transaction range, it returns with a DCDAMER_PROTO error.

Return value	Return value (numeric)	Explanation
DC_OK	0	All blocks were input normally.
DCDAMER_PROTO	-1600	The function dc_rpc_open() is not called.
		The purpose of input is updating or lock-specified reference outside the transaction range. (This value is returned only when a recoverable DAM file is accessed.)
		N is specified for atomic_update in the user service definition. (This value is returned only when a recoverable DAM file is accessed.)
		The function dc_dam_start() is not called. (This value is returned only when an unrecoverable DAM file is accessed.)
		The UAP is incorrectly linked as follows: The library (-1tdam) to be used for access to a TAM file using a DAM service function is linked incorrectly. The definition of the resource manager for transaction control object files is incorrect.
DCDAMER_EXCER	-1602	A lock error occurred.
DCDAMER_BADF	-1603	The file descriptor specified for damfd is not the one which was acquired by opening the file normally, or the specified file is not open.
DCDAMER_BUFER	-1604	The specified input buffer is too small to contain all blocks.
DCDAMER_BUFER	-1604	The value specified for the input buffer length is outside the range of values that can be specified.
DCDAMER_BNOER	-1606	The relative block number is invalid.
DCDAMER_NOMEM	-1607	The memory became insufficient.
DCDAMER_PARAM_KEYNO	-1609	The value specified for keyno is smaller than 1.
DCDAMER_PARAM_FLAGS	-1611	The value specified for flags is invalid.
DCDAMER_VERSION	-1618	The version of the DAM library linked to the UAP does not allow the UAP to operate with the current DAM service.
DCDAMER_JNLOV	-1613	The number of block updates exceeded the maximum number of blocks that can be updated during one transaction according to the DAM service definition. (Returned only when a recoverable DAM file is accessed.)
DCDAMER_IOER	-1620	An input error occurred.
DCDAMER_LHOLD	-1621	The file of the file descriptor specified for damfd is in logical shutdown state.
DCDAMER_OHOLD	-1622	The file with the file descriptor specified for damfd is in shutdown state due to an error.
DCDAMER_ACCESS	-1628	A DAM file to be accessed is protected with the security facility. The UAP that called the function dc_dam_read() has no access permission.
DCDAMER_TMERR	-1629	An error occurred in the transaction service. (This value is returned only when a recoverable DAM file is accessed.)
DCDAMER_DLOCK	-1642	A deadlock occurred.
DCDAMER_TIMOUT	-1643	The resource could not be acquired because a timeout occurred (the wait time specified in the lock service definition was exceeded).
DCDAMER_LCKOV	-1645	The number of lock requests exceeds the specified maximum number of concurrent lock requests.
DCDAMER_ACSOV	-1648	The maximum number of blocks for access to unrecoverable DAM files is exceeded. (This value is returned only when an unrecoverable DAM file is accessed.)