Invoke Alternate Index (IA)

Command title

Invoke Alternate Definition

Description

This command opens an Alternate Index table by generating a new Index for the data of an open table.

COBOL syntax

MOVE 'IA'                   TO xxxx-COMMAND.
CALL 'TBLBASE' USING        TB-PARM
                            xxxx-COMMAND-AREA
                            [DATA-TABLE-NAME
                            [ALT-DEFINITION]].

C syntax

memcpy( tbCommArea.tbCommand, "IA", 2 );
TBLBASE( &tbParm, &tbCommArea, pDataTableName,
         &tbAltDefinition );

Parameters

DATA-TABLE-NAME (optional) —the name of the Data Table

ALT-DEFINITION (optional)

Explanation

The Invoke Alternate command is primarily used for generating temporary Alternate Indexes. While the IA can also open a permanent Alternate Index, the recommended way to create a permanent Alternate Index is to use the CA command, and then subsequently use the OR or OW commands to open the Alternate Index.

To create a temporary Alternate Index, create the definition for the Alternate Index with the ALT-DEFINITION and DATA-TABLE-NAME parameter. If these parameters are not supplied, the library concatenation list will be searched for an existing Alternate Index based on the table name in the xxxx-COMMAND-AREA.

An IA command will only work if the Data Table is already open for read or write. This command does not work with a linked table. See Linked tables and TB-PARM.

Return value

Error 0080 subcode 1 or subcode 2 may occur because the Data Table is not open or accessible in the TSR.

Error code 0083 is returned if the Data Table is defined with Index=True. Some releases of Version 6 may have returned 0. Error code 0083 is the correct response.

Other possible ERRORs 0015, 0016, 0017, 0021, 0055, 0056, 0081, and 0087 are related to invalid sub-parameters.

For a list of tableBASE error codes, see tableBASE return codes.

Notes

A close command will close only the Alternate Index. If a close command is issued against the Data Table, all the Alternates are closed as well.

If an ST command is issued against an Alternate Index, the Data Table is stored.

A Data Table may have any number of Alternate Indexes.

Exceptions

None

See also

Examples—illustrates the use of CA and IA in conjunction with other tableBASE commands

Create Alternate Index Definition (CA)

Opening an Alternate Index

Glossary—for a definition of the term “Data Table”