|
|
|
Each of the fields comprising the parameter file records is separated from neighboring fields by one or more “white space” characters (blanks, tabs, or new lines). In the following subsections, if a parameter corresponds to a formal parameter in a FairCom DB function call, its name is included after the parameter’s brief description (e.g., bufs in the first position of the initialization record).
|
|
|
The Initialization Record is made up of four numeric fields:
The first and third parameters correspond to the first and third parameters of the InitCTree() function, bufs and sect, described earlier. For each index specified in the second parameter, there is either an Index Description record or an Index Member record. For each data file specified in the fourth parameter there is a Data File Description record. The Number of Node Sectors times 128 is the size, in bytes, of the B-Tree nodes. The number of data files specified by the fourth parameter of the Initialization Record must match exactly the number of Data File Description Records. However, the number of index files given by the second parameter can be equal to, OR GREATER than, the actual number of indexes. If greater, FairCom DB reserves extra file control blocks that your application may use with its own calls to OpenCtFile(), OpenIFile(), or for more flexible numbering of files in the parameter file.
|
|
|
Each Data File Description record is made up of six required fields and two additional fields if r-tree is to be used:
If RTREE is defined in your library, which is the default in ctopt2.h unless NO_RTREE is defined, each Data File Description record must have two additional fields:
The first five fields correspond to the parameters of CreateDataFile(). The data file name must agree with the operating system’s file naming conventions. Usually it can include a disk drive designation and/or a directory path name. The record length parameter is used only when the file is created. However, it should be properly maintained since the rebuild utility verifies that the parameter file value matches the value in the data file header record. filmod specifies:
The sixth parameter specifies how many indexes will be maintained for the data file. Each such index will either be a separate FairCom DB file or a member of an index file. See “CreateIndexFile” and “CreateIndexMember” in the FairCom DB Professional Developers Guide. If RTREE is defined in ctoptn.h, then the seventh and eighth parameters must be present. If the parameter file is to be used in conjunction with r-tree, these parameters must match actual entries in the data object definition array, DODA, otherwise r-tree will report an error. The DODA is described in Record Schemas in the FairCom DB Professional Developers Guide. If the parameter file is not actually for use with r-tree, then any arbitrary symbolic names may be used as long as there are no embedded blanks.
|
|
|
Each Index File record has eleven required fields and one additional field if r-tree is to be used:
If RTREE is defined in ctoptn.h, then one additional parameter is required:
The first eight fields correspond to the parameters of CreateIndexFile(). The index file name must agree with the operating system’s file naming conventions. Usually, the index name may contain a disk drive designation and/or a directory path name. The third through seventh parameters are used at the time the index file is created. However, they should be maintained carefully since the rebuild utility verifies that the ISAM parameter file values agree with the corresponding values stored in the index file header record. Remember, if duplicates are allowed, the last 4 bytes of the key value are reserved for the 4 bytes of the associated data record position. For example, a key length of 12 bytes combined with duplicate values results in 8 bytes for the actual key value and 4 bytes for the tie-breaking data record position. Skipping the ninth and tenth parameters for now (see the term “Null Key Values” below), the eleventh parameter specifies the number of segments concatenated to form a key value from the data record contents.
If RTREE is defined in ctoptn.h, the twelfth parameter is required. It is a symbolic name for the index file. It should start with an alphabetic character and may include upper and lower case letters, numbers and under scores. It may not include embedded blanks. Unlike the field names in the Data Description record, these do not, and must not, match entries in the r-tree DODA. Symbolic names for the data files are not necessary because each data file has a unique name.
Null Key Values
The ninth parameter of the Index File Description record, NULL key flag, determines if NULL or missing key values will be detected. After the key segments have been concatenated according to the Key Segment Description records, the NULL key flag parameter determines whether or not to test for a missing value. If the NULL key flag parameter is zero, no check for a NULL or missing value is made. If the NULL key flag is set to one, then the resulting key value is compared with the empty character (tenth parameter). If the key value is composed entirely of empty characters, then the key value is considered NULL or missing and is not entered into the index file.
The empty character is expressed in the decimal equivalent of the character. For example, an ASCII space (0x20) is specified with a value of 32. A NULL byte (0x00) is specified with a value of zero.
|
|
|
It is not necessary for each index associated with a data file to be in a separate file. Indexes can be combined in the same physical file. If the nomemb parameter of an Index File Description Record is greater than zero, the following nomemb Index File Description Records must be replaced by Index Member Records. For example, if a data file has three indexes, and the second index has an additional member, nomemb equals one, use two Index Description Records and one Index Member Record.
The Index Member Record is composed of seven required fields and one additional field to be used with r‑tree:
If RTREE is defined in ctoptn.h, each Index Member record needs one additional parameter:
These fields have the same interpretation as the corresponding fields in the Index Description Record. Index Member records do not include explicit member numbers (membno). The sequence of Index Member records following an Index File Description record determines the member number of each Index Member, (the first Index Member record is member number one, and so on). While a key number (keyno) is specified for each member, there is no freedom in the keyno value. The keyno specified in each Index Description Record must equal the keyno value of the host index file plus the member number, or error IMKY_ERR (108) will be raised in CreateISAM() and OpenISAM().
|
|
|
Each key value is composed of one or more segments. A segment is simply a sequence of bytes from specified offset within the data record. Each Key Segment Description record is comprised of three fields:
