Like DAM files, TAM files store user data in direct-organization files. The table access method, however, provides high-speed access to TAM files. A drawback is that such tables require more memory than required for DAM files.

When memory is abundant, you can configure a high-performance OpenTP1 file system using more TAM files. When memory is scarce, use DAM files. The same functions used for DAM file I/O can be used for TAM files also. So when memory is added, user data can be moved from DAM files to TAM files without changing the UAPs that have been used. Using the same functions also enables moving part of the user data to TAM files and leaving the rest of the user data in DAM files. For details about tree format and hash format, see 4.4.2(2) Internal functioning of a TAM table.

Table 4-10 lists some special features of TAM tables and files.

Table 4-10 Special features of TAM tables and files

Item	Feature
File structure	Direct organization file (an OpenTP1 file).
Record format	Fixed length, non-blocked format.
File access	A block of data can be referenced and updated by the table access methods using key values. There are three types of files: reference-only files, updatable files that prohibit addition and deletion, and updatable files that allow addition and deletion.
Relation to transaction	A record tentatively updated during transaction processing is actually updated in memory at the commit operation on a transaction. If the transaction is rolled back, the tentatively updated contents of the record are discarded. The record actually updated in memory is passed to a TAM file. OpenTP1 regularly writes only the records that were actually updated in memory to TAM files.
File backup and restore	The TAM file management command tambkup can backup a TAM file to another file, and the command tamrstr can restore the file. Also, the most recent contents of a TAM file can be recovered by using the backup file and the recovery journals after the backup was obtained. Recovery of a TAM file uses the TAM FRC facility.
Table addition	The TAM file management command tamadd can add a TAM table into an online system during OpenTP1 operation. The physical file for the TAM table must be made before executing tamadd. An added TAM table has an initial shutdown status. Use the command tamrles to release the shutdown.
File deletion	The TAM file management command tamhold can logically shut down a TAM table during system operation. You can then use the command tamrm to take the shutdown TAM table off the system without stopping the system. You can use the command tamdel to delete a TAM file, corresponding to a TAM table, from OpenTP1.

If plenty of memory is available, you can configure a high-performance system using TAM files. If memory is limited, use DAM files instead.

The functions used for DAM file I/O can also access TAM tables. So when more memory is added, you can move user data from the DAM files to TAM files without needing to change your existing UAPs. Alternatively, you can move some user data to TAM files, and leave some in DAM files.

This subsection describes the internal working of tree-format and hash-format TAM tables in OpenTP1. This subsection is not necessary for understanding the benefits of TAM tables, and readers can skip this material unless they have a particular interest in it.

In a tree-format TAM file, records are managed in a tree structure according to whether the value of each record is larger or smaller than the intermediate key value of the tree root. Because records are located and accessed by comparing the key values in the tree one-by-one, record retrieval takes longer than with hash-format TAM files.

In a hash-format TAM file, OpenTP1 locates and accesses a record via a number called the hash value. OpenTP1 uses an internal hash function to generate a hash value (a random number) from a key value.

The manner in which a key value is specified in a UAP when accessing a TAM table differs for tree format and hash format.

Table 4-11 shows the differences.

Table 4-11 Processing when a UAP specifies a key value for TAM table access

Specification in UAP	TAM table made from tree-format TAM file	TAM table made from hash-format TAM file
To retrieve one record: key-value = n	The record with the specified key value is retrieved. If such a record is not found, an error is returned.	Same as tree-format
To retrieve more than one record in a TAM table made from a tree-format TAM file: key-value < n key-value > n key-value n key-value n	The first record with the nearest key value to the specified key value is retrieved.	An error is returned.
To retrieve the first record in a TAM table made from a hash-format TAM file#	An error is returned.	The first record of the TAM table is retrieved ignoring the key value.
To retrieve the next (NEXT specification) record in a TAM table made from a hash-format TAM table#	An error is returned.	The record next to the one with the specified key value is retrieved.

#

For a TAM table made from a hash file, all the records in a TAM table can be searched by the combination of the first record retrieval and the NEXT retrieval; however, this all-record search can be performed only when the records contain key values. If the key values are removed from the records, the user cannot know the key value to be specified for the NEXT retrieval. For further details, see the manual OpenTP1 Operation.

For a hash-format TAM table, you can specify how much of the total record space to use as the hash area as an argument of the tamcre command when creating the TAM file. With a larger hash area, record retrieval is faster because there is less duplication of hash values and the list needs to be searched less often. However, when the list area decreases and the list gets full, any further duplication of hash values will prevent further records from being added even if the hash area has free space, resulting in poor memory efficiency. With a smaller hash area, duplication of hash values increases and the list has to be searched more often. This makes record retrieval slower, although memory usage is more efficient.

Figure 4-19 compares TAM tables that use large or small hash areas.

Figure 4-19 TAM tables that use large and small hash areas

To create a TAM file:

1. Create the OpenTP1 file system.
2. Use the TAM file management command tamcre to create the new TAM file.

If you want to store initial data in a TAM file at the time the TAM file is created, first store the initial data in a file, then specify the filename in the argument of tamcre. OpenTP1 will copy the initial data from the file to the TAM file. The file to store the initial data of a TAM file is called a TAM data file.

An access mode is the TAM table attribute that restricts UAP access to a record. By setting the appropriate access mode, you can differentiate use of TAM files according to their purposes, and enable record management of TAM tables.

In the TAM service definition, you can specify the access mode for a TAM table that is to be installed in an online system at the same time that OpenTP1 starts. For a TAM table that is to be added online during OpenTP1 operation, you can specify the access mode in the -a option of the TAM file management command tamadd that adds the TAM table.

Depending on how a UAP accesses the TAM table records, TAM tables can be classified into three types. A reference-only TAM table allows records to be referenced only: no record can be added, deleted, or updated during online processing. A TAM table that is updatable but prohibits addition and deletion allows updating of records during online processing but prohibits adding and deleting of records. A TAM table that is updatable but permits addition and deletion permits adding, deleting, and updating records during online processing.

OpenTP1 loads the TAM table stored in the TAM file into memory at a user-specified time called the loading opportunity. For a TAM table that is to be installed in the online system when OpenTP1 starts, you must define the loading opportunity in the TAM service definition. For a TAM table that is to be added to an online system during OpenTP1 operation, you must specify the loading opportunity in a parameter of the command tamadd that adds the TAM table.

A TAM table loaded by the command tamload is unloaded by the command tamunload. The TAM file loaded when OpenTP1 started or when it was added to the online system is automatically unloaded at the termination of OpenTP1. Also, a TAM file loaded by a function (dc_tam_read()) issued from a UAP is automatically unloaded when the function dc_tam_close() is issued to close the TAM file. Table 4-12 shows the loading opportunities and unloading methods for TAM tables.

Table 4-12 Loading opportunities and unloading methods for TAM files

Time TAM table is installed in an online system	Loading opportunity (one of the three opportunities is selected)	Unloading method#3
At the start of OpenTP1#1	When the TAM file service starts with OpenTP1	Automatically at TAM termination
	When the tamload command to load the table is entered	By command
At the start of OpenTP1#1	When the TAM table is opened by the dc_tam_open() function issued from a UAP	Automatically at the close of table
During OpenTP1 operation#2	When the TAM table is cataloged in the online system	Automatically at TAM termination
	When the tamload command to load the table is entered	By command
	When the TAM table is opened by the dc_tam_open() function issued from a UAP	Automatically at the close of table

#1

The loading opportunity is specified in the TAM service definition.

#2

The loading opportunity is specified in an option of the command tamadd, which adds a TAM table.

#3

The TAM table is unloaded at the termination of the TAM file service regardless of the loading opportunity.

OpenTP1 can lock TAM tables with table-based locks or record-based locks. When a TAM table or record has already been locked by another UAP, you can use a parameter of a function (dc_tam_open() or dc_tam_read()) to specify whether or not to wait until the lock is released. In the lock service definition, you can specify how long to wait for the lock release; this time is called the lock monitoring time. If the lock is not released before the lock monitoring time expires, an error is returned. For TAM tables, a lock takes effect only within each global transaction.

When more than one UAP can access both a TAM table and a DAM file, a deadlock might occur among the UAPs. If a deadlock occurs, OpenTP1 uses the UAP priority specified in the user service definition to recover from the deadlock. See 3.9.1(5) Deadlocks in TAM and DAM files for details about deadlocks.

This section describes how TAM and DAM lock functions are affected by deadlocks.

When two or more UAPs lock multiple resources in different sequences, an undesirable situation called a deadlock might occur. For example, in one form of deadlock, one UAP might lock resource A and wait for resource B to be released while another UAP might be locking resource B and waiting for resource A to be released. Figure 4-20 illustrates a deadlock.

Figure 4-20 Example of a deadlock

OpenTP1 detects deadlocks differently depending on whether the UAPs are on the same or different nodes. When UAPs are running on the same node, OpenTP1 automatically checks at regular intervals to detect deadlocks. When UAPs are running on different nodes, however, OpenTP1 cannot directly detect a deadlock so OpenTP1 checks whether any UAP has exceeded the specified time-limit for waiting for a resource. In the lck_wait_timeout operand in the lock service definition, you can specify the time-limit for waiting for a resource.

You can back up a TAM file during an OpenTP1 job. This is an online backup. Execute the tambkup command with the -o option to back up a TAM file during online processing. Without the -o option specified, a TAM file is backed up offline. This is how you back up offline:

1. Execute the tamhold command.
   The logical file is logically shut down.
   
2. Execute the tamrm command.
   The logically shut down logical file is separated from online processing.
   
3. Execute the tambkup command without the -o option.
   The TAM file is backed up.
   

1. Recovering a TAM file using files that were backed up online reduces the number of unload journal files to be used for recovery. This reduces the time required for recovering a TAM file compared to the time it takes using files that were backed up offline.

You can use standard output to the backup destination of a TAM file and standard input to the input file to be restored. Using standard input/output can redirect a command. If you use standard input/output, specify the -s option in the tambkup and tamrstr commands, then execute them.