The Create operation (B_CREATE) lets you generate a new data file from within your application. The Create operation also has subfunctions that allow you to delete or rename a file (see Delete and Rename Subfunctions for the Create Operation).

Table 8 illustrates the order in which the file and key specifications must be stored.

Logical Record Length. (Offset 0x00) The logical record length is the number of bytes of fixed-length data in the file. (Do not include variable-length data in the logical record length.)

Page Size. (Offset 0x02) Page size is determined by your file format version. See Choosing a Page Size in Pervasive PSQL Programmer's Guide.

Number of Indexes. (Offset 0x04) The number of indexes is the number of keys (not key segments) you are defining for the file. To create a data-only file, set the number of indexes to 0.

File Version. (Offset 0x05) The transactional interface file version to be created. In prior releases, the transactional interface used a two byte integer to receive the number of indexes on a create operation. The high order byte of this integer was always zero because the maximum number of indexes is 119. This high-order byte has always been used in the Stat operation to return the file version and it can now be used to specify the file version in the Create operation without breaking any previous applications. The supported file versions for Create are 6.x, 7.x, 8.x, 9.x, 9.5 which are represented in the specified byte with hex values 0x50, 0x60, 0x70, 0x80, 0x90, 0x95, respectively.

Physical Page Size. (Offset 0xA). This field was previously marked “Not Used.” This field is used in conjunction with the “Page Compression” file flag. If the “Page Compression” flag is not specified then this field is ignored.

The value specified for the physical page size cannot be larger than the value specified for the logical page size. If it is then the engine will round down the value specified for the physical page size so that it is the same as the logical page size. The logical page size needs to be an exact multiple of the physical page size. If it is not then the logical page size is rounded down so that it becomes an exact multiple of the physical page size. If, as a result of these manipulations, the logical and physical values end up to be the same, then page level compression will not turned on for this file. See also Creating a File with Page Level Compression in Pervasive PSQL Programmer's Guide

File Flags. (Offset 0x0A) The bit settings in the File Flags word specify file attributes. Table 9 shows the binary, hexadecimal, and decimal representations of the file flag values.

The database engine automatically uses data compression on files that use system data and have a record length that exceeds the maximum length allowed. See Table 12 in Pervasive PSQL Programmer's Guide.

Set the Duplicate Pointers bit if you anticipate adding an index sometime after creating a file, and if that index has many duplicate values. Setting this bit causes the transactional interface to reserve space in each record of the file for pointers that link the duplicate values. By reserving this space, you can possibly lower retrieval time and save disk space, especially if the keys are long and you anticipate that many records will have duplicate key values.

Number of Duplicate Pointers to Reserve. (Offset 0x0C) You can specify the number of duplicate pointers to reserve for each file. Use this element only if you specified the Reserve Duplicate Pointers file flag. For more information about duplicatable keys, refer to the following topic in Pervasive PSQL Programmer's Guide: Duplicatable Keys.

Allocation. (Offset 0x0E) You can specify the number of pages to preallocate. Use this element only if you specified the Page Preallocation file flag. For more information about page preallocation, see the following topic in Pervasive PSQL Programmer's Guide: Page Preallocation.

See also the status codes 26: The number of keys specified is invalid and 29: The key length is invalid, both in Status Codes and Messages.

Key Position. (Offset 0x00) The key position is the byte offset at which the key or key segment begins. Positions are relative to 1; A key at the beginning of the record starts at position 1. There is no position 0.

Key Length. (Offset 0x02) The length of the key or key segment. The maximum length of a key, including all key segments, is 255 bytes.

Key Flags. (Offset 0x04) The bit settings in the Key Flags word specify key attributes. Table 10 shows the binary, hexadecimal, and decimal representations of the Key Flags values.

Extended Data Type. (Offset 0x0A) You specify the Extended Data Type in byte 10 of the Key Specification block as a binary value. Table 11 shows the codes for the extended data types.

Regarding the data type you assign to a key, transactional interface does not ensure that the records you input adhere to the data types defined for the keys. For example, you could define a TIMESTAMP key in a file, but store a character string there. Your Btrieve API application would work fine, but an ODBC application that tries to access the same data using the ODBC TIMESTAMP format might fail, because the byte format could be different and the algorithms used to generate the timestamp value could be different. For complete descriptions of the data types, refer to SQL Engine Reference.

Null Value. (Offset 0x0B) of the Key Specification block represents an exclusion value for the key. If you have defined a key as a null key, you must supply a value for the transactional interface to recognize as the null value for each key segment. This is in reference to the legacy null and does not reflect true nulls. For a discussion of null support, see the following topic in Pervasive PSQL Programmer's Guide: Null Value.

Manually Assigned Key Number. (Offset 0x0E) The transactional interface allows an application to assign specific key numbers when creating a file with indexes. To manually assign key numbers to each index for a file, specify each key’s number as a binary value in byte 14 of the key specification block, and set the Key Number bit (0x400) in the File Flags word.

ACS Number. (Offset 0x0F) For keys that use a specific ACS, offset 0x0F in the key specification block provides the ACS number by which to collate the key. The ACS number is based on its position in the Data Buffer. The first ACS following the last key specification block is ACS number 0. Following ACS 0 is ACS 1, which is followed by ACS 2, and so on.

User-Defined ACSs. To create an ACS that sorts string values differently from the ASCII standard, your application must place 265 bytes directly into the Data Buffer, using the format displayed in Table 12.

For examples of user-defined ACSs, refer to the following topic in Pervasive PSQL Programmer's Guide: Alternate Collating Sequences.

International Sort Rules (ISRs). To specify an ISR, your application must place 265 bytes directly into the Data Buffer, using the following format:

The Data Buffer Length must be long enough to include the file specifications, the key specifications, and any ACSs that have been defined. Do not specify the file’s record length in this parameter.

Use Table 14 to determine which value you should use for the Key Number parameter.

These subfunctions have been modified to work with the security model in that they will accept a URI in place of a file name in the key buffer and data buffer, if needed, to indicate a transactional interface file to delete or rename. This allows you to provide security information with the operation. For details about URI connection strings, see Database URIs in Pervasive PSQL Programmer's Guide.