CBLDCDAM('OPEN') - Open a logical file

Format

PROCEDURE DIVISION specification

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

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  FILLER       PIC S9(9) COMP.
   02  FILLER       PIC S9(9) COMP.
   02  data-name-H    PIC S9(9) COMP.
   02  FILLER       PIC X(28).
01  unique-name-2.
   02  data-name-E    PIC X(4) VALUE 'OPEN'.
   02  data-name-F    PIC X(1).
   02  data-name-G    PIC X(1).
   02  FILLER       PIC X(1).
   02  FILLER       PIC X(1).
   02  data-name-Z    PIC S9(9) COMP VALUE ZERO.

Description

CBLDCDAM ('OPEN') opens a logical file.

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-E

Specify VALUE 'OPEN' for the request code indicating that the logical file is open.

data-name-F

Specify files or in blocks-based lock.

VALUE 'B': Blocks-based lock

VALUE 'F': Files-based lock

File lock can be specified if:

data-name-G

Specify whether the program is to wait for the resource to be released from lock if a lock error occurs. When VALUE 'F' is specified for data-name-F, the action depends on whether the DAM file to be used is recoverable or not.

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.

If both values are omitted, VALUE 'N' is assumed.

The values which can be specified for data-name-F and data-name-G depend on whether the DAM file to be used is recoverable or not. The following describes the values specified for recoverable and unrecoverable DAM files:

data-name-Z

Specify 0.

Data areas to which values are returned from OpenTP1

data-name-B

A status code of 5 digits is returned.

data-name-H

The file descriptor is returned.

Status codes

Status codeExplanation
00000The file descriptor was specified for data-name-H normally.
01600CBLDCRPC('OPEN ') was not called.
'N' is specified for atomic_update in the user service definition. (This error is returned only when accessing a recoverable DAM file.)
The CBLDCDAM('STRT') function is not called when N is specified for the atomic_update operand in the user service definition. (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 the DAM service API is linked incorrectly.
  • The definition of the resource manager for transaction control object files is incorrect.
DAM file lock is specified from outside the transaction range. (This error is returned only when accessing a recoverable DAM file.)
Files-based lock is specified for the DAM file under lock control for individual global transaction units. (This error is returned only when accessing a recoverable DAM file.)
01601The logical file name specified for data-name-C has not been defined.
01602A lock error occurred.
01605The CBLDCDAM('STRT') function is not called when Y is specified for the atomic_update operand in the user service definition. (This value is returned only when an unrecoverable DAM file is accessed.)
01607The memory became insufficient.
01608The logical file specified for data-name-C is open.
01610The value specified as the logical file name is invalid.
01611The value specified for data-name-F or data-name-G is invalid.
01621The file specified for data-name-C is in logical shutdown state.
01622The file specified for data-name-C is in shutdown state due to an error.
01627The number of open character special files exceeds the specified limit.
01628The access permission for character special files has not been granted.
01629A transaction service error occurred.
(This error is returned only when accessing an unrecoverable DAM file.)
01642A deadlock occurred.
(This error is returned only when accessing an unrecoverable DAM file.)
01643The resource could not be acquired because a timeout occurred since the wait time specified in the lock service definition was exceeded. (This error is returned only when accessing an unrecoverable DAM file.)
01645The number of lock requests exceeds the specified maximum number of concurrent lock requests.
01646The DAM file to be opened is protected by the security facility. No ACL exists for the file.
01690The interface code (data-name-A) is invalid.
01691The request code (data-name-E) is invalid.