OpenTP1 Version 7 Programming Reference COBOL Language

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

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 code Explanation
00000 The file descriptor was specified for data-name-H normally.
01600 CBLDCRPC('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.)
01601 The logical file name specified for data-name-C has not been defined.
01602 A lock error occurred.
01605 The 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.)
01607 The memory became insufficient.
01608 The logical file specified for data-name-C is open.
01610 The value specified as the logical file name is invalid.
01611 The value specified for data-name-F or data-name-G is invalid.
01621 The file specified for data-name-C is in logical shutdown state.
01622 The file specified for data-name-C is in shutdown state due to an error.
01627 The number of open character special files exceeds the specified limit.
01628 The access permission for character special files has not been granted.
01629 A transaction service error occurred.
(This error is returned only when accessing an unrecoverable DAM file.)
01642 A deadlock occurred.
(This error is returned only when accessing an unrecoverable DAM file.)
01643 The 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.)
01645 The number of lock requests exceeds the specified maximum number of concurrent lock requests.
01646 The DAM file to be opened is protected by the security facility. No ACL exists for the file.
01690 The interface code (data-name-A) is invalid.
01691 The request code (data-name-E) is invalid.