PROCEDURE DIVISION specification

CALL  'CBLDCDAM'  USING  unique-name-1  unique-name-2
                         unique-name-n

DATA DIVISION specification

01  unique-name-1.
    02  data-name-A    PIC X(8) VALUE 'DCDAMSVC'.
    02  data-name-B    PIC X(5).
    02  FILLER        PIC X(3).
    02  data-name-C    PIC X(8).
    02  data-name-D    PIC S9(9) COMP.
    02  data-name-E    PIC S9(9) COMP.
    02  data-name-H    PIC S9(9) COMP.
    02  FILLER        PIC X(28).
01  unique-name-2.
    02  data-name-F    PIC X(4) VALUE 'READ'.
    02  data-name-G    PIC X(1).
    02  data-name-L    PIC X(1).
    02  data-name-M    PIC X(1).
    02  FILLER        PIC X(1).
    02  data-name-Z    PIC S9(9) COMP VALUE ZERO.
    02  unique-name-3.
        03  data-name-I    PIC S9(9) COMP.
        03  data-name-J    PIC S9(9) COMP.
    02  unique-name-4.
        03  data-name-I    PIC S9(9) COMP.
        03  data-name-J    PIC S9(9) COMP.
          :
          :
    02  unique-name-m.
        03  data-name-I    PIC S9(9) COMP.
        03  data-name-J    PIC S9(9) COMP.
01  unique-name-n.
    02  data-name-K    PIC X(n).

CBLDCDAM('READ') inputs a block (which is in the specified range) for reference or update processing from the specified logical file.

• When accessing a recoverable DAM file:
  Blocks-based lock is enabled as specified when the logical file was opened. The block of a logical file can be input from a process out of the transaction range. In this case, however, the statement can be used only for reference and lock cannot be specified. When an request is made to input multiple blocks by specifying the block numbers, 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 from 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 the status code 01613 in the following case:
  
  • DAM file blocks are not updated (REWRITE) in one transaction branch. The block input for update processing (READ) 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).
  Call CBLDCDAM('READ') within the transaction range to input a recoverable DAM file block.
  
• When accessing an unrecoverable DAM file:
  When an unrecoverable DAM file block is input, there is no restriction for conditions to call CBLDCDAM('READ').
  If unrecoverable DAM file blocks exceeding the value specified for dam_update_block in the DAM service definition are input for update processing, an error is returned with the status code 01648.
  

When inputting a logical file block, specify the file descriptor returned from CBLDCDAM('OPEN').

data-name-A

Specify VALUE 'DCDAMSVC' for the interface code used with the DAM file.

data-name-C

Specify a logical file name with up to 8 characters. If the specified logical file name comprises less than 8 characters, pad the remaining portion with space.

data-name-D

Specify the number of blocks from unique-name-3 to unique-name-m (number of sets of data-name-I and data-name-J).

data-name-E

Specify the length of the input buffer. The buffer length must be equal to or greater than (number of blocks to be input x block length to be input).

'Number of blocks to be input' is the sum of blocks specified with the number of blocks from unique-name-3 to unique-name-m (number of sets of data-name-I and data-name-J).

data-name-H

Specify the file descriptor returned when the logical file was opened.

data-name-F

Specify VALUE 'READ' for the request code indicating the input of a logical file block.

data-name-G

Specify an input request type with VALUE 'R' or VALUE 'M'.

VALUE 'R': Input request for reference

VALUE 'M': Input request for update

data-name-L

Specify whether to apply lock if the input request is for reference. If 'E' is specified, lock will remain until processing reaches the synchronization point.

If a block is input from an unlocked logical file, the block could be updated by another transaction during the input processing. In this case, the details input to the block depend on the update processing status of the other transaction. Therefore, to reference the latest block contents, be sure to specify 'E'.

If the input request is for update, set a blank here; any other value will be ignored.

VALUE 'E': Lock is enabled.

VALUE 'N': Lock is not enabled.

Lock cannot be applied when accessing a recoverable DAM file outside the transaction for reference processing.

If VALUE 'M' is specified for data-name-G, specify space (' ') for data-name-L.

data-name-M

Specify whether the program is to wait for the resource to be released from lock if a lock error occurs. If VALUE 'N' is specified for data-name-L, specify space (' ') for data-name-M.

VALUE 'W': The program waits for the resource to be released from lock.

VALUE 'N': The program does not wait for the resource to be released from lock, and returns with an error.

VALUE SPACE : Processing is done according to the value specified for data-name-G of CBLDCDAM('OPEN').

If VALUE SPACE is specified or no value is specified, the subsequent processing is as follows:

• If VALUE 'W' is specified for data-name-G of CBLDCDAM('OPEN'), the program waits for the resource to be released from lock.
• If VALUE 'N' is specified for data-name-G of CBLDCDAM('OPEN') or if no value is specified, the program does not wait for the resource to be released from lock, and returns with an error.

However, if files-based lock is specified as the lock type in CBLDCDAM('OPEN') with the file descriptor specified for data-name-H, the value specified for data-name-M is meaningless.

The table below shows the correspondence between the values specified for data names G, L, and M and the specified type of lock.

data-name-G	data-name-L#1	data-name-M#2	Specified lock type
'R'	'E'	'W'	Input for reference, lock used, and waiting for release from lock if a lock error occurs
		'N'	Input for reference, lock used, and error return if a lock error occurs
	'N'		Input for reference, lock not used#3
'M'		'W'	Input for update, and waiting for release from lock if a lock error occurs
		'N'	Input for update, and error return if a lock error occurs

Legend:

: Specify space (' ').

#1: If 'R' is specified for data-name-G and the value for the data-name-L is omitted, 'N' is assumed.

#2: If space (' ') is specified for data-name-M in the following situation, the value specified for opening the logical file (waiting for release from lock or error return) is assumed:

If 'R' is specified for data-name-G and 'E' is specified for data-name-L

If 'M' is specified for data-name-G

#3: When accessing a recoverable DAM file, the statement for input a logical file block can be called from a process out of the transaction range only if 'R' is specified for data-name-G and 'N' is specified for data-name-L. If the statement for input a logical file block is called with the other values specified, it returns with an error, giving the status code 01600.

data-name-I

Specify the first relative block number of the block to be accessed.

data-name-J

Specify the last relative block number of the block to be accessed. If 0 is specified, only the relative block number specified for data-name-I is input.

data-name-K

Specify an input data area.

data-name-Z

Specify 0.

data-name-B

A status code of 5 digits is returned.