When a UAP in C language is used, use the function dc_tam_open() to open a TAM table.^# Call the function dc_tam_open() for each UAP.

A TAM table can be opened both inside and outside the transaction range. However, if a TAM table is opened before a transaction is started, lock cannot be specified for the table. See 4.2.6 Lock for TAM tables for details on lock for TAM files.

To close a TAM table, specify the table descriptor in the corresponding function.^# Keep the table descriptor in the UAP because the table descriptor is used for processing after the table is opened.

#

When the COBOL language is used for UAP coding, there is no need to open and close the TAM table. The TAM table is opened when it is accessed. The TAM table is closed when the transaction is completed.

To input a TAM table record for reference or update processing, call the function dc_tam_read() [CBLDCTAM('FxxR')('FxxU')('VxxR')('VxxU')]. At this time, whether to permit reference or update processing from another global transaction can be specified.

To update a TAM table record, input the record with the function dc_tam_read(), then call the function dc_tam_rewrite() [CBLDCTAM('MFY ')('MFYS')('STR ')('WFY ')('WFYS')('YTR ')]. (Update on the assumption of input)

To overwrite an existing record or add a new record instead of inputting a record from the TAM table, call the function dc_tam_write() [CBLDCTAM('MFY ')('MFYS')('STR ')('WFY ')('WFYS')('YTR ')].

To delete a record from the TAM table, call the function dc_tam_delete() [CBLDCTAM('ERS ')('ERSR')('BRS ')('BRSR')]. The record to be deleted can be saved in the buffer of any address. Specify the save destination address in the function dc_tam_delete().

If beginnings of the buffer area for the function dc_tam_read() or dc_tam_delete() and the data area for the function dc_tam_rewrite() or dc_tam_write() are specified on 4-byte boundaries, higher-speed access can be achieved than when such specifications are not given.

Multiple key values (records) can be input/output collectively. When inputting/outputting a TAM table, specify an access key value as a structure in the corresponding function. More than one structure can be specified.

When a record is input from a TAM table, the retrieval type to be specified depends on the index type.

With the hash format

First retrieval and NEXT retrieval are available. These retrieval methods enable you to retrieve all records. Call the first dc_tam_read() (with the first record specified), then input the first record. The records following the key value are input in the NEXT retrieval sequence specified in the dc_tam_read().

You can use the all-record retrieval method to delete all records from a TAM table. To delete all records from a TAM table:

1. Use first retrieval to acquire the first record.
2. Use NEXT retrieval with the first record specified as the key, to acquire the next record.
3. Delete the first record.
4. Use NEXT retrieval with the currently acquired record specified as the key, to acquire the next record.
5. Delete the record that you specified as the key in step 4.
6. Repeat steps 4 and 5 until there is no next record.
7. When there is no next record, delete the record that you specified as the key in the last NEXT retrieval.

This method requires you to specify a key indicating the start position for retrieval. Thus the system does not search the empty hash area extending from the start to the position immediately preceding the specified key. This makes for an efficient retrieval process.

The following method uses a large proportion of the CPU's capacity, so the response may be delayed.

1. Use first retrieval to acquire the first record.
2. Delete the first record.
3. Repeat steps 1 and 2 until there are no more records.

First retrieval searches the hash area from the start. Each time you execute retrieval, this method searches the record from the start, including the hash area that became empty when you deleted the records in the previous processes. It is therefore an inefficient method and the response may be delayed.

With the tree format

Retrieval of =, <=, >=, <, and > is available for the specified key value. Input the record corresponding to the key value. To input the records of multiple keys in a range, specify =, <=, >=, <, and > so that records satisfying the conditions can be input subsequently.

Use the function dc_tam_close() to close TAM tables.

If a TAM table was opened in the transaction range, close the TAM table in the transaction. If the transaction was terminated without the close function called, OpenTP1 closes the TAM table.

If a TAM table was opened outside the transaction range, close the TAM table outside the transaction. If the function dc_tam_close() is called in the transaction, the function returns with an error.

The figure below shows the procedures for accessing TAM tables.

Figure 4-7 Access to TAM tables

Use the function dc_tam_get_inf() [CBLDCTAM('GST ')] to acquire the status of a TAM table in online mode. The function dc_tam_get_inf() can be called both inside and outside the transaction range. The function dc_tam_get_inf() returns the following statuses of the TAM table:

• Open status
• Close status
• Logical shutdown status
• Shutdown status due to an error

The function dc_tam_get_inf() returns the open status when the UAP that called the function dc_tam_get_inf() has not opened the TAM table, but another UAP has opened the specified TAM table.

Use the function dc_tam_status() [CBLDCTAM('INFO')] to acquire the information of a TAM table in online mode. The function dc_tam_status() can be called both inside and outside the transaction range. The function dc_tam_status() returns the following information of the TAM table:

• TAM file name
• TAM table status
• Number of records in use
• Maximum number of records
• Index type
• Access type
• Loading opportunity
• TAM record length
• Key length
• Key start position
• Security attribute