OpenTP1 Version 7 Programming Reference COBOL Language

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

CBLDCDAM('READ') - Input a logical file block

Format

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).

Description

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

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

Data areas whose values are set in the UAP

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:

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' [Figure] Input for reference, lock not used#3
'M' [Figure] '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:
[Figure]: 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 area to which a value is returned from OpenTP1

data-name-B

A status code of 5 digits is returned.

Status codes

Status code Explanation
00000 All blocks were input normally.
01600 CBLDCRPC('OPEN ') was not called.
A block is input for update processing or a locked block is input for reference processing outside the transaction range. (This error is returned only when accessing a recoverable DAM file.)
'N' is specified for atomic_update in the user service definition. (This error is returned only when accessing a recoverable DAM file.)
CBLDCDAM('STRT') was not called. (This error is returned only when accessing an unrecoverable DAM file.)
The UAP is incorrectly linked as follows:
  • The library (-1tdam) to be used for access to a TAM file using the DAM service API is linked incorrectly.
  • The definition of the resource manager for transaction control object files is incorrect.
01602 A lock error occurred.
01603 The file descriptor specified for data-name-H is not the one which was acquired by opening the file normally.
The DAM file is not open.
01604 The specified input buffer is too small to contain all blocks.
01606 The relative block number is invalid.
01607 The memory became insufficient.
01609 The value specified for data-name-D is smaller than 1.
01611 The value specified for data-name-G or L is invalid.
01613 The number of block updates exceeded the maximum number of blocks that can be updated during one transaction according to the DAM service definition.
01618 The version of the DAM library linked to the UAP does not allow the UAP to operate with the current DAM service.
01620 An input error occurred.
01621 The specified file is in logical shutdown state.
01622 The specified file is in shutdown state due to an error.
01628 The DAM file to be accessed is protected by the security facility. The UAP attempting to input a logical file block has no access permission.
01629 A transaction service error occurred. (This error is returned only when accessing a recoverable DAM file.)
01642 A deadlock occurred.
01643 The resource could not be acquired because a timeout occurred (the wait time specified in the lock service definition was exceeded).
01645 The number of lock requests exceeds the specified maximum number of concurrent lock requests.
01648 The number of blocks exceeded the number of blocks accessible for an unrecoverable DAM file. (This error is returned only when accessing an unrecoverable DAM file.)
01690 The interface code (data-name-A) is invalid.
01691 The request code (data-name-F) is invalid.