CREATE-INDEX

Creates an index to a particular data section, based on a specified index or data definition.

Command class

TCL-I command.

Syntax

CREATE-INDEX fileName{,dataSection} [indexDefinition || dictionaryDefinition || indexName] {(options}

Syntax elements

fileName The name of the file in which the index will be created.

dataSection The name of the data section with which the index will be associated. Must immediately follow fileName and be preceded by a comma. If omitted, the default data section is assumed.

indexDefinition The item-id of an index definition item created by the DEFINE-INDEX command, located in the dictionary specified by fileName. Creates an explicit index with the same name as the index definition item.

dictionaryDefinition
The item-id of a data definition item in the dictionary specified by fileName to use as the index definition. Creates an implicit index with the same name as the data definition item.

indexName If the I option is specified, an implicit index is built by item-id. indexName specifies the name of the index created.

Options

m An integer number that is used as the initial modulo for the index section. If this is close to the index's optimum size, it will result in faster index population.

If the Z option is used to specify that the index should not be automatically sized, this parameter sets the modulo of the index (if omitted, a linear function of the modulo of the data file is used). You might need to use a different modulo if the index is critical to performance, if the file characteristics are expected to change or if you have used BY-EXP and/or BY-EXP-SUB clauses in the index definition.

For information on how to determine m, refer to the topic Selecting the Modulo for an Index.

D Makes the index descending (BY-DSND - see Sort Criteria); the default is ascending. This option can only be used if the index is being created from a data definition item.

F Attempts to build the index in memory (fast create). This can only be done if the file is not in use and will prevent access to file by other processes while the index is being built. If the file is in use, slow create is used.

I Builds an index by item-id.

L Specifies that right-aligned fields should be treated as left-aligned; that is, as alphanumeric, rather than numeric. This ensures that any leading zeros are included in the keys.

This option can only be used if the index is being created from a data definition item.

N Excludes null entries from the index (by making it selective). This option can only be used if the index is being created from a data definition item.

S Builds the index by updating the items in situ (slow create). This allows other processes to access the file while the index is being built.

U Specifies that the index should contain only unique keys; a write will fail if the key already exists for another item.

This option can only be used if the index is being created from a data definition item.

V Specifies that the index should be exploded to the value level (BY-EXP - see Sort Criteria). Has no effect unless combined with the X option.

This option can only be used if the index is being created from a data definition item.

X Specifies that the index should be exploded to the sub-value level (BY-EXP-SUB - see Sort Criteria); the default is non-exploded. To explode to the value level, use the X and V options together.

This option can only be used if the index is being created from a data definition item.

Z Specifies that the index should not be automatically sized.

Restrictions

Requires SYS2 privileges.

Comments

Unless the Z option is specified, the index will be configured to use automatic file sizing.

It is recommended that an index is created when the file is not being updated; this will make the CREATE-INDEX operation much faster.

If neither the F nor the S option is specified, CREATE-INDEX attempts to use fast create. If the file is being updated, slow create is used.

Note that if you create an index from a data definition item, you do not need to first create an index definition with DEFINE-INDEX.

The D, X, V, N and U options can only be used when creating an index from a data definition item. If used with an index definition item or the I (item-id) option, an error message is displayed and no index is created.

When an index is created, the current Environment Options settings are used. These settings are stored with the index definition and are used in subsequent automatic updates, thus ensuring that changes to the environment options do not cause unexpected changes in the index. To change the environment options used by an index, delete and recreate it.

Once created, the index is maintained until deleted by the DELETE-INDEX command.

See the topic Indexing for more information on indexes.

Case Sensitivity

For correct operation, an index relies always using the same settings for data and item-id case-sensitivity. Because of this, when you create an index, the current settings for these are saved with that index.

If you subsequently change the item-id case-sensitivity of the file with the CONVERT-FILE command, you will invalidate the index. To restore correct operation, you must delete it with the DELETE-INDEX command and then create it again.

Example

The following command creates index GT200 for file SALESTAFF.

:CREATE-INDEX SALESTAFF GT200

Subsequently, whenever changes are made to items in the file, the changed item is compared against the selection criteria of the index definition of GT200 and inserted, removed or relocated within the index accordingly. Their position in the index depends on the index's sort criteria.

See also

Indexing, DEFINE-INDEX, VERIFY-INDEX, DELETE-INDEX, HYPER-CREATE-INDEX.