OpenTP1 Version 7 Programming Reference COBOL Language
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' | 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 |
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:
|
|
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. |
All Rights Reserved. Copyright (C) 2006, 2010, Hitachi, Ltd.