Advanced ddlStructure() Functionality

There are several advanced forms of the ddlStructure() API function that are used to build and update a special kind of index, called a User Defined Index, or UDI.

Syntax:

Form3:	STRUCTURE/options <key-name> USING <cx-name> <table-name> <recno-field> <table-field> [<data-field>]
Form4:	STRUCTURE/options <key-name> USING <file-name> [ + <file-name2> ...] <rd-name> <RDrecno-field> <RDtable-field> [<RDdata-field>]
Form5:	STRUCTURE/Cnnn <key-name> [ ... <key-nameN>] USING <cx-name> <table-name> <recno-field> <table-field>
Form6:	STRUCTURE/Cnnn <key-name> [ ... <key-nameN>] USING <file-name> [ + <file-name2> ...] <rd-name> <RDrecno-field> <RDtable-field>

Where:

key-name ... keynameN represent the names of one or more key fields to be indexed; cx represents the name of a collection that contains the index data; table-name represents the name of a table in <cx> that contains the index data; this table is sometimes called the surrogate table; recno-field represents the name of a field in the surrogate table that contains the index record number; table-field represents the name of a field in the surrogate table that contains the index table name; data-field represents the name of a field in the surrogate table that contains the index data; file-name represents the name of a file containing the index data; rd-name represents the name of a record description that describes the data in <file-name>; RDrecno-field represents the name of a field in <rd-name> that contains the index record number; RDtable-field represents the name of a field in <rd-name> that contains the index table name;        alternately, this field can contain the literal table name [enclosed in 's]; RDdata-field represents the name of a field in <rd-name> that contains the index data;

Additional Options:

	/B -	In Form4 and Form6, the /B option indicates that the input meta file is in block format; in block format:     a) each record must be the same length as the record size of the RD;     b) there are no CR-LF record delimiters; Block format is required if the RD, or the data itself, contains any binary data types;
	/F -	Blank-fill ascii fields that contain the null character;
	/D -	The /D option must be used when structuring a DATA index. Only Form 3 and Form 4 can be used with a DATA index. To delete an item from a DATA index, set the high-order bit of the <recno> field [0x80000000]. In this case, <recno> is the DATA data value. Indexes built the the /D option can be queried only with the ddlFindCxData().

Notes:

Note 1	The data required to build a UDI index is:    a field containing the 1-relative index record number;    a field containing the index table name;    a field containing the index data;
Note 2	In Form3 and Form5, the data required to create or append to a UDI index is contained in a Thunderbolt table; and is specified as <cx> <table-name>. In Form3, if the optional <data-field> is not specified, the data field name in the surrogate table is the same as <key-field>. In Form5, the data field names in the surrogate table are always the same as the respective <key-nameN>.
Note 3	In Form4 and Form6, the data required to create or append to a UDI index is contained in a flat file; In Form4, if the optional <RDdata-field> is not specified, the data field name in the RD is the same as <key-field>. In Form6, the data field names in the RD are always the same as the respective <key-nameN>.
Note 4	For ddlStructure() Form4 and Form6, the requirement for block format is contingent on the contents of the data; i.e., if the data contains binary data, then block format is required; otherwise, block format is optional. For the related API function ddlStructureMem(), block format is required unconditionally.