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.

CBLDCDAM ('OPEN') opens a logical file.

• When accessing a recoverable DAM file:
  Whether to apply file lock or block lock to the logical file is specified. File lock can be specified if:
  
  • The logical file is opened within the transaction range under the condition that lock control for individual transaction branches is specified.
  In the following condition, file lock cannot be specified. Specify block lock:
  
  • The logical file is opened outside the transaction range.
  • Lock control for individual global transaction units is specified.
  If a logical file is closed and is again opened in the same transaction branch, the status before the logical file is closed is inherited.
  
• When accessing an unrecoverable DAM file:
  Since this type of file does not synchronize with transaction processing, there is no restriction for lock.
  

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:

• The recoverable DAM file is opened within the transaction range.
• The unrecoverable DAM file is opened.

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:

• When accessing a recoverable DAM file:
  The value specified for data-name-G can be invalid if a lock error occurs not in CBLDCDAM('OPEN'), but in CBLDCDAM('READ') and CBLDCDAM('WRIT') when accessing a logical file which has already been opened. If a lock error occurs in CBLDCDAM('OPEN'), an error is unconditionally returned with the status code 01602.
  The table below shows the correspondence between the values specified for data-name-F and data-name-G and the specified type of lock when accessing a recoverable DAM file.
  

  data-name-F	data-name-G#	Specified lock
  'F'		Files-based lock
  'B'	'W'	Blocks-based lock, and waiting for release from lock if a lock error occurs
  	'N'	Blocks-based lock, and error return if a lock error occurs

  Legend:

  : Specify a space (' ').

  #: If 'B' is specified for data-name-F and the value for data-name-G is omitted, 'N' is assumed.

• When accessing an unrecoverable DAM file:
  The value specified for data-name-G from lock can be invalid if a lock error occurs. If a lock error occurs in CBLDCDAM('OPEN'), CBLDCDAM('READ') and CBLDCDAM('WRIT'), whether to wait for release from lock or not is determined according to the value of data-name-G. If a lock error occurs when data-name-G is set to 'N' or omitted, an error is returned with the status code 01602.
  The table below shows the correspondence between the values specified for data-name-F and data-name-G and the specified type of lock when accessing an unrecoverable DAM file.
  

  data-name-F	data-name-G#	Specified lock
  'F'	'W'	Files-based lock, and waiting for release from lock if a lock error occurs
  	'N'	Files-based lock, and error return if a lock error occurs
  'B'	'W'	Blocks-based lock, and waiting for release from lock if a lock error occurs
  	'N'	Blocks-based lock, and error return if a lock error occurs

  #: The default is 'N'.

  Regardless of whether the file is recoverable or not, no lock error occurs in CBLDCDAM('READ') and CBLDCDAM('WRIT') when files-based lock is specified for data-name-F. This is because the file is entirely locked. Therefore, whether to wait for release from lock cannot be specified. The value specified for data-name-G in CBLDCDAM('READ') and CBLDCDAM('WRIT') is ignored.

data-name-Z

Specify 0.

data-name-B

A status code of 5 digits is returned.

data-name-H

The file descriptor is returned.