OpenTP1 Version 7 Programming Reference COBOL Language

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

CBLDCTAM('FxxR'/'FxxU'/'VxxR'/'VxxU') - Input a TAM table record

Format

PROCEDURE DIVISION specification

CALL 'CBLDCTAM' USING  unique-name-1 unique-name-2
                       unique-name-3 unique-name-4

DATA DIVISION specification

01  unique-name-1.
    02  data-name-A    PIC X(4).
    02  data-name-B    PIC X(5).
    02  FILLER        PIC X(3).
    02  data-name-C    PIC X(32).
    02  FILLER        PIC X(68).
    02  data-name-D    PIC S9(4) COMP.
    02  FILLER        PIC X(398).
    02  data-name-J    PIC S9(9) COMP.
    02  FILLER        PIC X(392).
01  unique-name-2.
    02  data-name-E    PIC X(4).
    02  data-name-F    PIC X(1).
    02  FILLER        PIC X(2).
    02  data-name-I    PIC X(1).
01  unique-name-3.
    02  data-name-G    PIC X(m).
01  unique-name-4.
    02  data-name-H    PIC X(n).

Description

According to the search type specified for data-name-E, CBLDCTAM('FxxR'/'FxxU'/'VxxR'/'VxxU') inputs a TAM table record for reference or update processing. Table 2-1 shows the relationship between search types and index types.

Table 2-2 Relationship between search types and index types

Search type Outline of search processing
Index type: hash format Index type: tree format
'key-value='search The record having the specified key value is searched for.
If the record having the specified key value is not found, an error is returned.
The record having the specified key value is searched for.
If the record having the specified key value is not found, an error is returned.
'key-value<='search An error is returned. The record having a key value equal to or greater than the specified key value is searched for.
'key-value<'search An error is returned. The record having a key value greater than the specified key value is searched for.
'key-value>='search An error is returned. The record having a key value equal to or smaller than the specified key value is searched for.
'key-value>'search An error is returned. The record having a key value smaller than the specified key value is searched for.
First record search# The first record that was hashed in correspondence with the key value is searched for. The key value specified for data-name-G is ignored. An error is returned.
NEXT search# The next record that was hashed in correspondence with the key value is searched for. An error is returned.

#: All the records in the TAM table can be searched for by using the first record search and NEXT search in the following conditions:
The hash format is specified as the index type.
When a TAM table file is created, a key value is assigned to the data part (the -s option not specified in the tamcre command).

If lock is specified with input for reference processing, lock in tables and lock in records are enabled with lock for reference processing. If a TAM table open under lock in records is input for update processing, lock in tables is enabled with lock for reference processing, and lock in records is enabled with lock for update processing.

However, if table nonlock mode is specified as the access-time table lock mode in the TAM service definition, tables whose access type is reference or update without addition or deletion, their lock cannot be enabled.

If the program that inputs TAM table record returns with an error, all the resources specified in this program are released, and the status before this program was called is regained. However, if a record which was acquired under lock for reference processing before this program was called is input for update processing, lock for update processing is enabled. (Lock for reference processing is not regained.) If an error is returned, the buffer contents cannot be ensured.

Data areas whose values are set in the UAP

data-name-A

Specify the TAM ID. The TAM service does not reference this value.

data-name-C

Specify the name of the TAM table of the record to be input. The name can be specified with up to 32 characters. If the specified name comprises less than 32 characters, pad the remaining portion with space.

data-name-D

Specify a buffer length if the input record is 32767 bytes or less. The buffer length must be equal to or greater than the record length. The setting here is valid only when VALUE 'Fxxx' is specified for data-name-E.

data-name-J

Specify a buffer length if the input record is 32768 bytes or more. The buffer length must be equal to or greater than the record length. The setting here is valid only when VALUE 'Vxxx' is specified for data-name-E.

data-name-E

Specify one of the following request codes:

VALUE 'FCHR', VALUE 'VCHR': Search for key-value= for reference (hash/tree format).

VALUE 'FGER', VALUE 'VGER': Search for key-value<= for reference (tree format).

VALUE 'FGTR', VALUE 'VGTR': Search for key-value< for reference (tree format).

VALUE 'FLER', VALUE 'VLER': Search for key-value>= for reference (tree format).

VALUE 'FLTR', VALUE 'VLTR': Search for key-value> for reference (tree format).

VALUE 'FTPR', VALUE 'VTPR': Search for the specified key value from the first record for reference (hash format).

VALUE 'FNXR', VALUE 'VNXR': Search for the specified key value from the next record for reference (hash/tree format).

VALUE 'FCHU', VALUE 'VCHU': Search for key-value= for updating (hash/tree format).

VALUE 'FGEU', VALUE 'VGEU': Search for key-value<= for updating (tree format).

VALUE 'FGTU', VALUE 'VGTU': Search for key-value< for updating (tree format).

VALUE 'FLEU', VALUE 'VLEU': Search for key-value>= for updating (tree format).

VALUE 'FLTU', VALUE 'VLTU': Search for key-value> for updating (tree format).

VALUE 'FTPU', VALUE 'VTPU': Search for the specified key value from the first record for updating (hash format).

VALUE 'FNXU', VALUE 'VNXU': Search for the specified key value from the next record for updating (hash/tree format).

data-name-F

If a record is input for reference processing, specify a lock enabled/disabled type.

VALUE '[Figure]': Lock is enabled. (Lock is reset at the synchronization point.)

VALUE 'D': Lock is enabled. (Lock is reset when this CALL statement terminates.)

VALUE 'N': Lock is disabled.

data-name-G

Specify the key value with the length of the key area of the record to be searched for.

data-name-H

Specify the data area (buffer) to which the record is input.

data-name-I

Specify whether to wait for release from lock with one of the following values. The value specified for data-name-I is valid when 2 is specified for tam_cbl_level in the TAM service definition.

VALUE 'W': Wait for release from lock

VALUE 'N': Error return without waiting for release from lock

If 0 or 1 is specified for tam_cbl_level in the TAM service definition, specifying a value for data-name-I is unnecessary.

Data areas whose values are returned from OpenTP1

data-name-B

A status code of 5 digits is returned.

data-name-H

The input record is returned.

Status codes

Status code Explanation
00000 The TAM table record was input normally.
01701 The TAM table name specified for data-name-C is invalid.
01702 The key value specified for data-name-G is invalid.
01704 The value specified for data-name-H is invalid.
01705 The buffer length specified for data-name-D or J is too short.
01708 The value specified for data-name-E, F or I is invalid.
01709 The table specified for data-name-C is not a TAM table.
01710 The TAM table has not been defined.
01720 The TAM service is being terminated.
01721 The sequence of accessing the TAM table is invalid.
The resource manager registration of the object file for control of transactions having a linkage with the UAP is invalid. Alternatively, there is no linkage between the object file for control of transactions and the UAP.
atomic_update=N (nontransaction attribute) is specified in the user service definition of the UAP which called CBLDCTAM.
01723 The TAM table was deleted.
01724 The TAM table was not loaded.
01727 The TAM table is in logical descriptor state.
01728 The TAM table is in descriptor state due to an error.
01729 Execution is impossible with the index type of the TAM table specified for creation of a TAM table file.
01730 Execution is impossible in the access mode of the TAM table specified in the TAM service definition.
01731 A record satisfying the search conditions specified for data-name-E is not found.
01736 A lock error occurred. If you specified 0 in the tam_cbl_level operand of the TAM service definition, or if you specified 2 in the tam_cbl_level operand and set W in data-name-I, the resource could not be acquired because the wait time specified in the lock service definition reached timeout.
01737 A deadlock occurred.
01760 The version of the TAM library linked to the UAP does not allow the UAP to operate with the current TAM table.
01761 The version of the TAM library linked to the UAP does not allow the UAP to operate with the current OpenTP1 file service.
01762 The version of the TAM library linked to the UAP does not allow the UAP to operate with the current TAM service.
01764 The record has been damaged.
01765 The number of transactions exceeds the maximum number of transactions which can be managed by the TAM service.
01766 The number of open character special files exceeds the specified limit.
01767 The access permission for special files has not been granted.
01768 The access permission for TAM files has not been granted.
01769 The memory became insufficient.
01770 An input/output error occurred.
01771 A transaction service error occurred.
01772 The opening TAM file is protected by the security facility. No ACL exists for the file.
01773 The accessing TAM file is protected by the security facility. The UAP attempting to input a record from the TAM table has no access permission.