VRLEN PutIFile(pIFIL ifilptr) 

All the incremental ISAM functions require a pointer to an IFIL structure as their input parameter. The IFIL structure defines the characteristics of the data file and includes a pointer to a structure that defines the associated indices.

The formal type definition for IFIL follows:

typedef struct ifil {

  pTEXT     pfilnam,  /* file name (w/o ext)   */

  COUNT     dfilno,   /* data file number      */

  UCOUNT    dreclen,  /* data record length    */

  UCOUNT    dxtdsiz,  /* data file ext size    */

  COUNT     dfilmod,  /* data file mode        */

  COUNT     dnumidx,  /* number of indices     */

  UCOUNT    ixtdsiz,  /* index file ext size   */

  COUNT     ifilmod,  /* index file mode       */

  pIIDX     ix,       /* index information     */

  pTEXT     rfstfld,  /* r-tree 1st fld name   */

  pTEXT     rlstfld,  /* r-tree last fld name  */

  COUNT     tfilno    /* temporary file number */

} IFIL;

Note: pTEXT is a c-tree Plus data type that equates to TEXT *. For example, pTEXT pfilnam is the same as TEXT *pfilnam. The same holds true for all ‘p’ data types, i.e., pISEG = ISEG * .

Corresponding IFIL Member	c-tree Plus Parameter	Interpretation
pfilnam	filnam	The file name pointed to by pfilnam is shared by both the data file and index file. The name should not include the file extension. .dat and .idx (as defined in ctifil.h) are added to the name for the data file and index file. The extensions can be changed using extended function calls. The file name must agree with the operating system’s file naming conventions.
dfilno	datno	The file numbers assigned to the data file and any associated indices run consecutively. If dfilno is negative, c-tree Plus finds the first available block of numbers. If dfilno is positive, c-tree Plus assigns dfilno as the data file number. In either case, tfilno is set equal to the data file number.
dreclen	datlen	Record length for fixed-length records or the fixed-length portion of variable-length records.
dxtdsiz	xtdsiz	Data file extension size. When the data file needs to be extended, this is the number of bytes the file grows.
dfilmod	filmod	Data file mode indicator. See “c-tree Plus Concepts”.
dnumidx	N/A	The number of associated indices (which may be zero).
ixtdsiz	xtdsiz	Index file extension size. Same as dxtdsiz, but for the index file.
ifilmod	filmod	Index file mode indicator. See “c-tree Plus Concepts”.
ix	N/A	Pointer to IIDX index structures defined below.
rfstfld	N/A	An optional pointer to the symbolic name of the first data field in the record, as specified in the r-tree DODA. This structure entry and the next one are required for r-tree and d‑tree users only.
rlstfld	N/A	An optional pointer to the symbolic name of the last data field in the record.
tfilno	N/A	Output parameter set equal to the file number assigned to the data file. For greatest flexibility, use this argument for functions that request the data file number (datno or dfilno).

Each index is described by an IIDX structure. If a data file has associated indices, the ix member of the IFIL structure must point to an array of IIDX structures. In particular, there must be dnumidx elements (i.e., IIDX structures) in the array.

Each IIDX structure defined over a given data file receives a unique file number assigned sequentially from the data file number tfilno. For example, if tfilno is file number 5, and this data file has 3 indices, they receive file numbers 6, 7 and 8. 6 is assigned to the IIDX structure pointed to by the IFIL element ix, 7 is assigned to the next IIDX structure, and 8 to the last IIDX structure for this particular data file. Since each IIDX structure gets its own file number, there is no difference in performance between placing all IIDX definitions for a particular data file in the same physical file or in individual physical files.

The formal type definition for IIDX follows:

typedef struct iidx {

  COUNT     ikeylen,  /* key length                   */

            ikeytyp,  /* key type                     */

            ikeydup,  /* duplicate flag               */

            inulkey,  /* NULL key flag                */

            iempchr,  /* empty character              */

            inumseg,  /* number of segments           */

  pISEG     seg,      /* segment information          */

  pTEXT     ridxnam,  /* r-tree symbolic name         */

  pTEXT     aidxnam,  /* optional index file name     */

  pCOUNT    altseq,   /* optional alternate sequence  */

  pUTEXT    pvbyte    /* optional pointer to pad byte */

} IIDX;

Corresponding IIDX Members	c-tree Plus Parameter	Interpretation
ikeylen	keylen	Key length.
ikeytyp	keytyp	Key type.
ikeydup	keydup	Duplicate flag.
inulkey	N/A	Null key flag.
iempchr	N/A	Empty character.
inumseg	N/A	Number of key segments.
seg	N/A	Pointer to ISEG key segment structures.
ridxnam	N/A	Pointer to optional symbolic index name for use with r-tree.
aidxnam	filnam	Pointer to an optional index file name.
altseq	N/A	If not NULL, this points to an array of 256 short integers that specify an alternate collating sequence.
pvbyte	N/A	If not NULL, this points to a byte value to be used for trailing padding compression. An ASCII space (0x20) is the default padding character.

The following text provides additional information about select IIDX elements:

ikeylen - The sum of the segment lengths (defined below). If duplicates are allowed, the last 4 bytes of the key value are reserved for the 4 bytes of the associated data record offset. For example, a key length of 12 bytes allowing duplicates has 8 bytes of actual key value and 4 bytes for the tie-breaking data record offset. DropIndex() marks a transaction-controlled index for deletion by setting keylen to -keylen until the drop is committed. A GetIFile() call after the DropIndex() call, but before the Commit() or Abort() will return this interim setting.

ikeytyp - Valid key types are below. For additional information, consult “Alternative Key Types”.

Value	Explanation
0	fixed length key
4	leading character compression
8	padding compression
12	leading/padding compression combined (key types 4 and 8)

ikeydup - Duplicate flag. A parameter value of one indicates the index supports duplicates, add 4 bytes to the key length (see ikeylen above). A parameter value of zero indicates the index will NOT support duplicates, making all key values unique.

inulkey - Determines if NULL or missing key values are detected. After concatenating the key segments according to the ISEG array, the NULL key flag parameter determines whether or not to test for a missing value. If the parameter is zero, no check is made. If the parameter is one, the resulting key value is compared with the empty character, iempchr. If the key value is entirely empty characters, it is considered NULL or missing and not entered into the index file.

iempchr - 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.

inumseg - The number of segments concatenated to form a key value from the data record contents.

ridxnam - If r-tree or d-tree is used with this application, define this arbitrary index name. It must start with an alphabetic character and may include upper and lower case letters, numbers, and underscores. It may not include embedded blanks. Symbolic names are not necessary for the data files because each has a unique name.

aidxnam - (Optional) Permits Incremental ISAM files to have more than one index file and to locate an index file independently from the data file. The index file name must agree with the operating system file naming conventions. If not NULL for the first member of the IIDX array, this file name is used instead of being derived from the IFIL pfilnam parameter. This allows the index to be located in a different path or a different device. If not NULL for subsequent members of the IIDX array, this name is used to create additional host index files. All following member indices will be located in the new index file.

Each key value is composed of one or more segments. A segment is simply a sequence of bytes from a specified offset within the data record. Each key segment is described by an ISEG structure. The seg member of each index IIDX structure must point to an array of ISEG structures. In particular, there must be inumseg elements (i.e., ISEG structures) in the array. The formal type definition for ISEG follows:

typedef struct iseg {

  COUNT     soffset,  /* segment position (offset)   */

            slength,  /* segment length              */

            segmode   /* segment mode                */

} ISEG;

Segment Position

The segment position specifies the location of the key segment within the data record. This can be specified in one of three ways, as determined by the segment mode value (as discussed later);

1. Absolute byte offset. The number of bytes from the beginning of the data record to the first byte of the key segment. The smallest offset, zero, means that the segment begins with the first byte of the record. If a segment begins with the nth byte of the record, its offset value should be n minus one.
   This option works with fixed length fields, which have known offsets.
2. Relative field number. The segment position is treated as a field number, not a byte offset. This applies only to variable-length data records. With variable-length records, all of the fields in the variable-length portion are variable-length fields terminated with a delimiter. This delimiter is typically the NULL character, unless the default is changed by SetVariableBytes(). A segment position of zero corresponds to the first variable-length field, beginning at the first byte beyond the variable-length file’s fixed-length portion. When a variable-length file is created, the record length parameter is treated as the minimum record length, which corresponds to the fixed-length portion of the record.
   This option works with variable-length string types using NULL terminators.
   The following schematic demonstrates how varying-length fields are numbered. The delimiter is shown as a NULL byte, but can be any delimiter you set:

   

3. Record Schema field number. When using a Record Schema, (“Record Schemas”), use a schema segment type and specify the segment position by the field number in the record schema. The first field in the schema is field zero.

   This options works with any type of data in any part of the record, allowing key segments on non-variable-length data types in the variable-length portion of the record. All fields in the variable-length portion must be packed as opposed to aligned. No padding bytes are allowed between fields.

Though segoffset is a COUNT field, since a fixed length file or the fixed length portion of a variable length file may exceed 32767 bytes, segment offsets exceeding 32767 bytes, but less than 65535 bytes, are supported. The internal logic deals with segment offsets that “go negative”. A minus one for a segment offset (equivalent to 65535 for a UCOUNT) still signifies the “end of segments” so that segment offsets can now range from 0 to 65534. If a value greater than 32767 is stored in a COUNT field, it appears as a negative value; but its absolute value correctly corresponds to the original value. For example, storing 65534 into a COUNT results in a value of -2 when expressed as a COUNT, but -2 cast to a UCOUNT corresponds to 65534.

Segment Length

The segment length specifies the number of bytes that this key segment will take in the key itself. The sum of the segment lengths for an index file must equal the key length unless duplicate keys are allowed. In this case, the segments should sum to the key length less 4 bytes. If the sum of the segment lengths does not match the key length, CreateISAM(), OpenISAM(), CreateIFile(), or OpenIFile() return error ISLN_ERR (115).

For variable-length fields, segment modes 4 and 5, c-tree Plus automatically pads a key segment to the full segment length using the padding byte. The padding byte defaults to an ASCII space (0x20), but can be changed using SetVariableBytes(). When using a field other than a variable-length field, make the segment length less than or equal to the actual size of the field.

Segment Mode

The segment mode determines what transformations, if any, must be made to the key segment. In addition, it determines which of the three methods of determining the segment position will be used.

Detailed information on key segment modes is presented in the following section. When using a Record Schema to manage the building of keys, refer to “Record Schemas” for more information.

IFIL vc_dat = {

. . . .

};   /* IFIL structure to be placed in resource record */

VRLEN ret=0;  /* function return work variable */

if (ret=PutIFile(&vc_dat))

    printf("\nError during PUTIFIL(), error = %d",ret);

else

    printf("\nSuccessful PUTIFIL()!");