ISAM settings elements

The Settings Elements apply the settings that you use to configure a Structure Element. These elements configure FairCom RTG/ISAM behavior.

See Also

• FairCom RTG/ISAM Configuration

<automkdir>

The <automkdir> option indicates whether to automatically create missing directories when creating new files. If this option is set to yes, any missing directory of the file path is automatically created. If this option is set to no, an error is returned if the file path does not exist. This option is disabled by default.

Accepted Values

Example

<automkdir>yes</automkdir>

<ctfixed>

The ctfixed option indicates whether to create fixed record-length files with c-tree file mode ctFIXED. If this option is set to yes, files with fixed record length are created with c-tree file mode ctFIXED. If this option is set to no, all files are created with c-tree file mode ctVLENGTH. This option is disabled by default.

Setting ctfixed to yes imposes a minimum record length of 9 bytes for huge files or 5 bytes for non-huge files (based on the setting of the <hugefile> configuration option).

<ctfixed> and <ctflexrec> are mutually exclusive options and an error is returned when used in combination.

Accepted Values

Example

<ctfixed>yes</ctfixed>

<datacompress>

The datacompress option indicates whether to create files with data compression enabled. When data compression is enabled, data records are compressed using the compression algorithm specified by the type attribute. Data compression reduces disk space utilization but it may also impact performance. This feature is turned off by default.

Note: If your configuration file does not include a datacompress element, the application can turn on compression programmatically for the files that need them. If you include this attribute in the configuration file, the setting will override programmatic requests from the application.

Accepted Values

Attributes

Please refer to the zlib documentation available at http://zlib.net/manual.html for more information about zlib compression.

Note: The zlib library is not included with FairCom RTG/ISAM. You will need to download the zlib library and place it in the local directory with the c-tree Server binary). If the FairCom RTG/ISAM Server does not find ZLIB1.DLL in the path when it is started, an error 946 is returned when attempting to create files with zlib data compression.

Notice that the default for RM/COBOL is to create files with compression. Set datacompress to No if you do not want your RM/COBOL files to be compressed.

Examples

<datacompress type="rle" level="5">yes</datacompress>
<datacompress type="zlib" strategy="3" level="9">yes</datacompress>
<datacompress level="1">yes</datacompress>

<datafilesuffix>

The datafilesuffix option defines the string to append to data file names. It can be used to define the default data file extension. The file extension is considered by FairCom RTG/ISAM to be part of the file name. If you want to override the "suffix", use the datafilesuffix configuration option.

If not specified, the default data file extension is .dat.

Any string is accepted. Make sure your operating system's file system accepts the value you specify.

Please remember to specify the "." (dot) if you want to use this as part of your file extension.

If you want your files to be created with no file extension, you can leave the datafilesuffix empty or set it to a SPACE character as follows:

<datafilesuffix> </datafilesuffix>

or

<datafilesuffix></datafilesuffix>

Example 1:

<datafilesuffix>.cdt</datafilesuffix>

Example 2:

This example removes the extensions .cdt and .cap by mapping them to an empty <name></name>:

<file name="*.cdt">
    <datafilesuffix>.CAD</datafilesuffix> 
    <map><name></name></map>
</file>
<file name="*.IND">
    <datafilesuffix>.cap</datafilesuffix> 
    <map><name></name></map>
</file>

Attributes

<delcurrent>

When deleting a record, avoid re-reading if the record's primary key was not changed since the last read operation.

The <delcurrent> configuration option improves performance of COBOL applications that perform a large number of DELETE operations all preceded by a READ operation that placed a lock on the same record.

When <delcurrent> is enabled, FairCom RTG does not re-read the record during the execution of the DELETE operation to ensure that it is the current record. Instead, it deletes the current ISAM record immediately. The effect is that DELETE operations are faster.

Note: This option is effective only if:
1) The primary key of the file does not allow duplicates.
2) The record was locked during the read operation so it could not be replaced by another user between the read and delete operations.

Default: No.

<encrypt>

The encrypt option indicates whether to create files with encryption enabled or disabled. When enabled, files are masked using the type of advanced encryption specified.

Note: If your configuration file does not include an <encrypt> element, the application can still create files with encryption enabled if the application explicitly requests encryption. If you include the <encrypt> attribute in the configuration file, the setting will override the programmatic requests from the application.

Accepted Values

Attributes

Example

To encrypt using aes32 encryption:

<encrypt type="aes32">yes</encrypt>

See Also

• Advanced File Encryption in the FairCom DB Programmer's Referenced Guide

 V13: Camouflage usage has been restricted to existing files and may be removed entirely in a future version.

<fileversion>

The <fileversion> configuration option specifies a major version number of RTG. When specified, the default values of all configuration options are reset to the default value of the selected RTG version.

The default value of <fileversion> will be the major version number of the current RTG version.

Example

<fileversion>2</fileversion>

<forcedelete>

The <forcedelete> configuration option controls the behavior of DELETE FILE operations. The behavior of DELETE FILE in isCOBOL and ACUCOBOL is to return a "corrupted file" error (98) and not delete the orphan file if the index file is missing. The DELETE FILE behavior in Micro Focus is to delete the orphan file.

Accepted Values

By default, <forcedelete> is set to "no" except for ExtFH drivers where it is set to "yes" to match Micro Focus COBOL behavior.

The logic returns success (COBOL error 0) on a DELETE FILE operation if <forcedelete> is enabled (default for FairCom RTG ExtFH driver) and an orphan data file is detected. Before this change, 0 was returned only for orphan index files and an error was returned for orphan data files. That matched the behavior of old Micro Focus COBOL products, however, more recent Micro Focus products always return 0.

<hugefile>

This configuration keyword allows the huge file mode to be turned off so that non-huge files are created. The default is to use FairCom RTG/ISAM support for huge files, which accommodate up to 16 exabytes of data when segmented files are used. Non-huge files accommodate up to 2 or 4 gigabytes of data depending on the operating system.

Accepted Values

Example

<hugefile>yes</hugefile>

<indexfilesuffix>

The indexfilesuffix option defines the string to append to index file names. It can be used to define the default index file extension.

If not specified the default data file extension is .idx.

Any string is accepted. Make sure that your operating system file system accepts the value you specified.

Please remember to specify the "." (dot) if you want to use this as part of your file extension.

If you want your files to be created with no file extension, you can leave the indexfilesuffix empty or set it to a SPACE character as follows:

<indexfilesuffix> </indexfilesuffix>

or

<indexfilesuffix></indexfilesuffix>

Example

<indexfilesuffix>.cix</indexfilesuffix>

<keycompress>

The keycompress option indicates whether to create files with key compression enabled. This feature is turned off by default. It may impact performance, but it reduces disk space usage.

Accepted Values

Attributes

Additionally, the keycompress option may accept the following sub-options to specify which compression type to use:

<rle> keycompress option

• Indicates to compress the whole key using a simple RLE algorithm. This option is available only if vlennod is enabled.

<leading> keycompress option

• Indicates to compress the leading characters of key values. The <keycompress vlennod> attribute must be disabled to use <leading>. See <leading>.

<padding> keycompress option

• Indicates to compress the padding characters of key values.

Note: The <rle> and <padding> sub-options are mutually exclusive.

vlennod Index Node Format

Setting vlennod to "yes" causes new files to be created with the new index node format. The new index node format is variable-length hence the name "vlennod". The variable-length nature of the new index nodes allows better index compression. The vlennod attribute is enabled by default.

The following <keycompress> suboptions specify which compression type to use:

• <rle> - Indicates to compress the whole key using a simple RLE algorithm.
• <padding> - Indicates to compress the padding characters of the key.

The new index compression does not support the <leading> compression type. The old index compression can be used by disabling <keycompress vlennod> (enabled by default), which allows the <leading> and <padding> to be specified. The new <rle> option cannot be specified when the <keycompress vlennod> attribute is disabled. The <rle> and <padding> sub-options are mutually exclusive unlike the old index compression where it was possible to combine <leading> and <padding>.

Examples

The following examples show different ways to turn on the new index compression:

<keycompress/>
<keycompress>1</keycompress>
<keycompress><rle/></keycompress>
<keycompression><padding>1</padding></keycompression>

The following example turns on default key compression that implicitly uses RLE compression:

<keycompress>yes</keycompress>

The following example turns on only padding key compression:

<keycompress>
	<padding>yes</padding>
</keycompress>

The following example turns off key compression:

<keycompress>no<keycompress>

Using the Old-Style Compression

In some cases, older FairCom RTG/ISAM versions that do not support the new vlennod index node format are in production and cannot be updated. The vlennod index node format can be disabled in these cases. This allows creation of compressed files in the old compression format so they are compatible with the old version.

The old index compression can be used for file creation by disabling the <keycompress vlennod> attribute, which is enabled by default. When the <keycompress vlennod> attribute is disabled, the old index compression sub-options <leading> and <padding> can be specified. The new <rle> option cannot be specified when the <keycompress vlennod> attribute is disabled. The following examples show different ways to enable the old index compression:

<keycompress vlennod="no"/>
<keycompress vlennod="0">1</keycompress>
<keycompress vlennod="false"><leading>1</leading></keycompress>
<keycompression vlennod="n"><leading/><padding/></keycompression>

<leading>

The keycompress leading option indicates to compress the leading characters of key values. It is indicated when there is significant leading character duplication among the key values.

Accepted Values

This option can be specified when the <keycompress vlennod> attribute is disabled:

<keycompress vlennod="no"><leading>yes</leading></keycompress>

Examples

The following example turns on only leading key compression:

<keycompress>
	<leading>yes<leading>
</keycompress>

<padding>

The keycompress padding option indicates to compress the padding characters of key values. It is indicated when key lengths vary in size and are padded with spaces.

Accepted Values

The <rle> and <padding> sub-options are mutually exclusive.

Examples

The following example turns on only padding key compression:

<keycompress>
	<padding>yes</padding>
</keycompress>

<log>

The log option indicates whether to log events such as errors that occur in FairCom RTG/ISAM. This feature might be helpful for diagnostics purposes.

Attributes

Accepted Values

If the log option is enabled, it may accept the following sub-options to specify which event to log:

<debug> log option

• The debug option indicates to log debug information.

<error> log option

• The error option indicates to log errors.

<info> log option

• The info option indicates to log generic information.

<profile> log option

• The info option indicates to log performance profiling information.

<warning> log option

• The info option indicates to insert a warning into the log file.

If the log option is enabled and no sub-options are specified, it has the same effect as turning on the <error>, <warning>, and <info> sub-options.

Examples

The following example turns on implicit logging of errors and generic information to standard error stream:

<log>yes</log>

The following example turns on explicit logging of errors and generic information to file mylog.txt:

<log file="mylog.txt">
	<error>yes</error>
	<info>yes</info>
</log>

The following example turns on only error logging:

<log>
	<error>yes</error>
</log>

Substitution Specifiers

Substitution specifiers can be used in the <log file> configuration attribute. The <log file> attribute can contain substitution specifiers to build the log file name using (for example) an environmental variable.

Example:

The following setting creates a different log file for each Windows user:

<log file="%(USERNAME).log">yes</log>

<debug>

The debug log option instructs the FairCom RTG/ISAM to insert debug information in the log file.

Accepted Values

The debug log option also accepts the following Boolean (yes or no) sub-options to include or exclude certain types of debug information from the log file.

Children elements

Examples

The following example enables the logging of debug information only:

<log file=mylog.txt>
	<debug>yes</debug>
</log>

The following example enables debug logging of configuration and explicitly disables the debug logging of prefetch and batch addition operations:

<log file=mylog.txt>
	<debug>
		<config full="yes">yes</config>
		<prefetch>no</prefetch>
		<batchaddition>no</batchaddition>
	</debug>
</log>

The following example enables debug logging each time FairCom RTG/ISAM switches between c-tree and the native COBOL file handler:

<log>
    <debug>
        <switcher/>
    </debug>
</log>

<error>

The error log option instructs the FairCom RTG/ISAM to log file error events.

Accepted Values

The error log option also accepts the following Boolean (yes or no) sub-options to include or exclude certain type of errors from the log file.

Children elements

By default, the entries associated with <atend>, <notfound>, and <duplicate> are not logged unless they are explicitly enabled. <locked>, <missingfile>, and <undefined> remain logged by default.

* Note:

These masks can be useful if you encounter a large number of error 9:0 (undefined record position) in your FairCom RTG/ISAM logs and need a way to mask them.

In the FairCom RTG/ISAM log file, these errors can be identified by the first of the three colon-separated error values:

RTG Error : Underlying c-tree API Error : Operating System Error

For example, a record locked error will display the following (notice 42 is the c-tree error for record locked):

ERROR 5:42:0 

Examples

The following example enables the logging of errors only:

<log file=mylog.txt>
	<error>yes</error>
</log>

The following example enables the logging of end-of-file errors but not of record-not-found errors:

<log file=mylog.txt>
	<error>
		<atend>yes</atend>
		<notfound>no</notfound>
		<undefined>no</undefined>
	</error>
</log>

<info>

The info option indicates to log generic information in the specified log file.

Accepted Values

Examples

The following example enables the logging of generic information only:

<log file=mylog.txt>
	<info>yes</info>
</log>

<whoformat>

The whoformat log option indicates the format of the log entry portion that prints which client application logged the entry.

The value of <log whoformat=""> is a character string that can contain substitution specifiers such as %p for process ID, %t for thread ID, etc.

The default value is <log whoformat="%08Xt>. This prints the thread ID ("%t") in uppercase hexadecimal format ("%Xt") with an 8 digits fixed width ("%8Xt") left-padded with zeroes (0) instead of spaces ("%08Xt") followed by a literal "> " as separator ("%08Xt> ").

<profile>

The profile option indicates to log performance profiling information in the specified log file.

Accepted Values

Examples

The following example enables the logging of profiling information:

<log file="mylog.txt">
	<profile>yes</profile>
</log>

<warning>

The warning option indicates to log warnings about potentially unwanted conditions in the specified log file.

The warnings do not represent blocking errors.

Accepted Values

Examples

The following example enables the logging of warnings only:

<log file=mylog.txt>
	<warning>yes</warning>
</log>

<locktimeout>

In V2 and later, a new configuration option, <locktimeout>, sets the blocking lock timeout. For example: <locktimeout>15</locktimeout> sets the timeout for blocking locks to 15 seconds.

• If <locktimeout> is set to a value greater than 0, an operation attempting to acquire a blocking lock on a locked record returns after <locktimeout> seconds with a locked error.
• If <locktimeout> is set to 0 (default), an operation attempting to acquire a blocking lock on a locked record waits until the record becomes available.

<map>

The map option replaces the file name or directory passed by the Btrieve application with the specified values.

The map option may contain the following sub-options:

<name> map option

The name option specifies the string that replaces the file name portion of the file path passed by the Btrieve application.

<dir> map option

The dir option specifies the string that replaces the directory portion of the file path passed by the Btrieve application.

Both of these options support substitution specifiers.

Examples

The following example replaces only the file name portion of the passed file path:

<map>
    <name>CUSTMAST2010</name>
</map>

The following example replaces both the name and directory portion of the passed file path:

<map>
    <name>CUSTMAST2010</name>
    <dir>/Data2010</dir>
</map>

Multiple <file> Rules

If you have multiple <file> rules and you want all of the affected files to be located in a specific directory, you must define the <map> option for each <file> rule to which it applies. For example, if you have two <file> rules and you want both to be directed to a folder called my_files under a folder specified in an environment variable called CTREE, you need to add <map><dir>%(CTREE)/my_files</dir></map> to each <file> rule:

<file name="*.vis">
 <map>
  <name></name>
  <dir>%(CTREE)/my_files</dir>
 </map>
</file>
 
<file name="*">
 <map>
  <dir>%(CTREE)/my_files</dir>
 </map>
</file>

Wildcards

If wildcards are used in the <file> matching rule, the <map> string does not replace the part of the file name or directory that matches a wildcard. Only the part of the file name that is specified explicitly is replaced by the <map> string.

Wildcard Example

The following example changes all file names ending with "2010" so that they end with "2013". If a file named CUSTMAST2010 is found, it will be changed to CUSTMAST2013.

<file name="*2010">
    <map>
        <name>2013</name>
    </map>
</file>

<name>

The name option specifies the string that replaces the file name portion of the file path passed by the Btrieve application. It supports %n and %d substitution specifiers. For more information about substitution specifiers, please refer to "Substitution specifiers."

Examples

The following example replaces only the file name portion of the passed file path:

<map>
	<name>CUSTMAST2010</name>
</map>

<dir>

The dir option specifies the string that replaces the directory portion of the file path passed by the Btrieve application. It supports %n and %d substitution specifiers. For more information about substitution specifiers, please refer to "Substitution specifiers."

Examples

The following example replaces the directory portion of the file path with the content of the FILEDIR environment variable:

<map>
	<dir>%(FILEDIR)</dir>
</map>

<maxsize>

The maxsize option, when enabled, specifies the maximum file size limit for files in MB. When a file is created with this option enabled, an error will be returned when the file reaches the specified size. The default value is 0, which allows files to grow up to the limit of the file system where the file is located.

Example

<maxsize>1024</maxsize> 

This example will allow the file to grow up to 1 GB.

See also

• -maxsize

<memoryfile>

The memoryfile option indicates whether to create files in memory rather than on disk. This feature is indicated for temporary files. This feature is off by default.

The synonym <memfile> can be used for the <memoryfile> option.

Accepted Values

Attributes

FairCom RTG/ISAM memory files default to a maximum size of 4Gb. The KEEPOPEN attribute is automatically applied.

Note: The bulkaddition option (available in FairCom RTG COBOL only) should not be used with the memoryfile option (because doing so would cause the indexes to be created on disk).

Note: The memoryfile option and the <transaction logging="yes"> option are mutually exclusive.

<memoryfile persist> Attribute

Once created, memory files are available until they are either removed or until the FairCom RTG server is shut down. This allows the memory file to be available for multiple sessions to multiple applications while the FairCom RTG server is active.

Typically the deletion of the memory file is performed by the application that created it as it has knowledge of its existence. However, if the application disconnects from the FairCom RTG server in a non-controlled way (i.e., crash), the memory file remains available to other applications which might not know of its existence and therefore will not be able to delete it. Overall, this may cause an accumulation of orphan memory files and an exhaustion of memory.

The <memoryfile persist> configuration attribute specifies if the memory file being created will be available while the FairCom RTG server is active or if it is automatically removed when the application that created it disconnects from the FairCom RTG server (either in a controlled way or as a result of a crash).

<memoryfile persist="yes"> - Once created, the memory file is available until the FairCom RTG server is shut down or until any application manually deletes it.

<memoryfile persist="no"> - The memory file is available until the application that created it disconnects from the FairCom RTG server.

Example

<memoryfile>yes</memoryfile>

See Also

• Memory Files

<normalize>

The <normalize> configuration option normalizes file paths passed to FairCom RTG. This option is global-only, and can only be set only as a child of <config>. It is invalid if specified as child of <*instance> or <file>. When this option is used, the file path gets normalized before any file configuration matching.

The <normalize> option may contain the following sub-options:

<sep>

Specifies the path separator, such as a forward slash (/) or backslash (\).

<drive>

Specifies a drive letter to be used if the path to be normalized does not include a drive letter.

If a drive letter is already included in the path, it is not replaced with the one specified by <drive>. Also, <drive> applies only to full file paths, not relative ones. The following attributes can modify these behaviors:

• <drive force> - If the file path to be normalized already includes a drive letter, then setting <drive force="yes"> will force it to change the drive to the one specified. Defaults to "no".
• <drive relative> - Setting <drive relative="yes"> will cause the drive letter to be added to relative file paths as well, not just full file paths. Defaults to "no".

<relative>

Specifies if the relative file paths will be normalized to always begin with a "./" or ".\". Defaults to "no", meaning nothing is automatically added to the start of relative file paths.

<trim>

If "yes", all specified leading and trailing characters are automatically trimmed from the file paths. Defaults to "no". When "yes", then by default, all whitespace characters will be trimmed. This can be customized using the following attribute:

• <trim set> - Customizes which character types will be trimmed. Defaults to <trim set=" \t\n\r\f\v">, which trims the following list of whitespace character types:
  • (' ') - Space
  • '\t' - Tab
  • '\n' - Newline
  • '\r' - Carriage return
  • '\f' - Formfeed
  • '\v' - Vertical tab

<sep>

Sub-option of <normalize>. Specifies the path separator, such as a forward slash (/) or backslash (\).

Example

The following <normalize> section replaces all path separators with a backslash (\) and prefixes all the file paths with a C drive unless the path to be normalized already includes a drive letter:

 <normalize><sep>\</sep><drive>C</drive></normalize>

<drive>

Sub-option of <normalize>. Specifies a drive letter to be used if the path to be normalized does not include a drive letter.

If a drive letter is already included in the path, it is not replaced with the one specified by <drive>. Also, <drive> applies only to full file paths, not relative ones. The following attributes can modify these behaviors:

• <drive force> - If the file path to be normalized already includes a drive letter, then setting <drive force="yes"> will force it to change the drive to the one specified. Defaults to "no".
• <drive relative> - Setting <drive relative="yes"> will cause the drive letter to be added to relative file paths as well, not just full file paths. Defaults to "no".

Examples

If the file path to be normalized already has a drive it is not changed by default. It is possible to force the drive to be changed to the one specified by setting the force= attribute to yes. For example:

 <normalize><drive force="y">C</drive></normalize>

It is also possible to remove an existing drive by specifying an empty drive. For example:

 <normalize><drive></drive></normalize>

To normalize absolute file paths, but not relative file paths, by adding the specified drive letter:

<normalize><drive relative="no">D</drive></normalize>

For instance, here the D drive is added to the absolute file path "\data\custmast", but not to the relative file path "custmast":

>ctutil -info \data\custmast |findstr path
File path               : D:\data\custmast.dat

>ctutil -info custmast |findstr path
File path               : custmast.dat

Conversely, to normalize both relative and absolute paths, use:

<normalize><drive relative="yes">D</drive></normalize>

Resulting in:

>ctutil -info \data\custmast |findstr path
File path               : D:\data\custmast.dat

>ctutil -info custmast |findstr path
File path               : D:custmast.dat

<relative>

Sub-option of <normalize>. Specifies if the relative file paths will be normalized to always begin with a "./" or ".\". Defaults to "no", meaning nothing is automatically added to the start of relative file paths.

Examples

<normalize><relative>no</relative></normalize> (default) does not normalize the file path passed by the application to RTG, so the file path is used as is.

<normalize><relative>yes</relative></normalize> cause all relative file paths to be prefixed with . and the platform path separator.

For instance, the following ctutil -info command opens the file with file path "custmast" (which is a relative file path), and the ctutil -info output shows that the file path used to open the file is ".\custmast":

>ctutil -info custmast |findstr path
File path               : .\custmast.dat

The file path is not normalized for absolute file paths like D:\data\custmast and \data\custmast:

>ctutil -info D:\data\custmast |findstr path
File path               : D:\data\custmast.dat

>ctutil -info \data\custmast |findstr path
File path               : \data\custmast.dat

<trim>

Sub-option of <normalize>. If "yes", all specified leading and trailing characters are automatically trimmed from the file paths. Defaults to "no". When "yes", then by default, all whitespace characters will be trimmed. This can be customized using the following attribute:

• <trim set> - Customizes which character types will be trimmed. Defaults to <trim set=" \t\n\r\f\v">, which trims the following list of whitespace character types:
  • (' ') - Space
  • '\t' - Tab
  • '\n' - Newline
  • '\r' - Carriage return
  • '\f' - Formfeed
  • '\v' - Vertical tab

Examples

Example of trimming standard whitespace:

• <normalize><trim/></normalize>
  • Input: " \t my-file.txt \n" 
  • Output: "my-file.txt"

Example of custom trimming (periods and underscores):

• <normalize><trim set="._"/></normalize>
  • Input: ".my-file.txt_"
  • Output: "my-file.txt"

<optimisticadd>

The <optimisticadd> option enables adding keys before the data during WRITE operations.

The strategy that c-tree uses to add new records consists of adding the data record first and subsequently adding the keys in the indexes. In case of duplicate keys errors, the record just added is deleted. This approach is optimistic as it assumes that the user is attempting to add new records with unique keys and only occasionally the operation fails with duplicate errors.

A common practice is to use a pessimistic approach where the WRITE is performed mostly on already existing keys and the Btrieve programmer relies on the WRITE return code to know if a key already exists. In such cases, the default optimistic approach used by c-tree does not provide optimal performance.

When <optimisticadd> is enabled (default), c-tree uses an optimistic strategy which provides optimal performance when adding non-existing records.

When <optimisticadd> is disabled, c-tree uses a pessimistic strategy that attempts to add unique keys before adding the data record.

Examples

To disable <optimisticadd>:

<optimisticadd>no<optimisticadd>

To enable <optimisticadd> (default):

<optimisticadd>yes<optimisticadd>

<prefetch>

This option enables batch record retrieval to improve performance of consecutive sequential reads. This is achieved by retrieving a given number of records (specified by the records attribute) from the server to the client side at the second consecutive sequential read operation. The next sequential read operations do not need to contact the server to retrieve the records as the records are now cached on the client side. Once all the records in the client cache are processed, the next block of records is requested to the server.

By default, the records cached on the client side cannot be updated by other users (the allowwriters attribute overrides this default). This avoids situations in which the cached records do not match the records on the server.

The records are prefetched during the second subsequent call to an operation that reads the next record (Get Next) or the previous record (Get Previous). The Get Next or the Get Previous operation performs as follows when <prefetch> is active:

The pattern described above also applies to a series of READ PREVIOUS calls.

Prefetching records improves performance of sequential reads in environments where the client and server reside on different systems connected with a network. In such environments any request from the client to the server is sent over the network which is generally a time-expensive operation. It is advisable to configure c-tree so that <prefetch> is enabled only on files were large numbers of Get Next operations are performed, as shown in the examples below.

The default value of <prefetch records="10"> has been demonstrated to be optimal for most cases. However, if you want to fine tune the value, please make sure that it matches (as closely as possible) the number of subsequent Get Next operations performed by your application. Setting <prefetch records> to a larger number will result in reading records from disk that will never be returned to the application which may neutralize the performance gain of prefetching records.

Please notice that any Get Record operation in the middle of a Get Next or Get Previous sequence invalidates the prefetched records causing the prefetch logic to restart at the next Get Next or Get Previous operation.

The number of records to prefetch is defined by the records attribute. The size of the prefetch buffer is determined by the record size and the number of records:

prefetch_buffer_size = record_size * <prefetch_records>

Accepted Values

Attributes

Notes about <prefetch allowwriters>

If you are calling Get Next or Get Previous with any locking options, then <prefetch allowwriters> has basically no effect as all the prefetched records will be locked as a result of the requested lock options of the Get Next calls.

If you are calling Get Next or Get Previous without any locking options, then <prefetch allowwriters> is significant. With allowwriters=no (the default), the prefetched records are locked with a read lock type that allows other users to read them but prevents other users from updating them. Setting allowwriters=yes allows other users to read and write the prefetched records, which may cause the user reading the prefetched record to retrieve a record that has been changed or even deleted by another user.

Note: It is the programmer's responsibility to ensure that the application does not have issues with prefetched records that have been modified. Enable allowwrites only when data is not critical and/or seldom changes. For example, a list of countries or dealer locations may not change frequently, so prefetched records will rarely be out-of-date.

Do not enable allowwrites if the data is critical and/or frequently changing. For example, account balances or line items on an open order need to be up-to-date.

Examples

To enable <prefetch> and set the number of prefetched records to 50:

<prefetch records="50">yes</prefetch>

To enable prefetch and allow prefetched records to be modified by other users:

<prefetch allowwriters="yes">yes</prefetch>

To configure c-tree so that <prefetch> is enabled only on specific files:

<config>
   <file/>
   <file name="specific_file">
      <prefetch>yes</prefetch>
   </file>
</config>

The configuration above turns on <prefetch> only for specific_file, leaving it off all other files.

<recordcheck>

The recordcheck option specifies whether to check that the record length of the file being open matches the record length definitions of the calling application.

If this option is set to "yes", an error is returned at file open time if the record minlen or maxlen does not match the application-defined minlen or maxlen. This is the default option.

If this option is set to "no", an error is returned at file open time only if the record minlen or maxlen is less than the application-defined record minlen or maxlen.

This option is must useful for a table that has been expanded with new fields using the RTG alter table operation. Existing runtimes might not be immediately able to be recompiled, and this option allows file opens from these existing applications as they don't care and are unaware of any new fields that have been added.

Note: recordcheck is performed at the time the file is opened, to validate the application-defined record maximum and minimum lengths. This is in contrast to the maxlencheck option which validates only the maximum length each time a record is read, to ensure that variable length records are compatible.

Accepted Values

Example

<recordcheck>no</recordcheck>

 See Also

-alter

<maxlencheck>

<rowid>

The <rowid> option enables support for creating a ROWID field/index. The ROWID is required for creating a Full-Text Index, so this option is necessary if Full-Text Search is desired.

Accepted Values

Attributes

Example

<rowid>yes</rowid>

Notes

Full text search requires additional information on each record. A unique ROWID value provides this extended information. The new configuration element <rowid> enables this feature for newly created tables. ROWID is internally supported by the FairCom RTG serial segment feature (SRLSEG), an auto incrementing value transparent to the application.

ROWID support is enabled by including <rowid>yes</rowid> in your FairCom RTG local configuration file (ctree.conf).

1. Once you have created a table with ROWID, a Full-Text Index (FTI) can be created on the new table without further intervention.
2. Existing tables require a one-time conversion to support FTI. ctutil -upgrade enables this support.

The "size" attribute for the <rowid> tag can be used to set the size of the rowid hidden field in the record header. The default value is 8 for COBOL (4 for BTRV). Accepted values are 8 and 4.

<rowid size="8">yes</rowid>

 Compatibility: The size setting of <rowid> is taken into consideration even if <rowid> is set to no, affecting other FairCom RTG features. Setting it to 8 (for COBOL, not setting a value has the same effect) makes new files incompatible with previous FairCom RTG versions.

Therefore, to be sure that files created with V3 are compatible with older versions, it is necessary to include the following in ctree.conf:

 <rowid size="4">no</rowid>

<smartcopy>

The smartcopy option enables the use of batched read/write techniques to improve performance of file copy operations. If this option is set to yes, the file copy reads and writes records in blocks in order to reduce the number of read and write operations. If this option is set to no, the records are copied one by one. This option is enabled by default.

Accepted Values

Attributes

Example

To enable smartcopy:

<smartcopy>yes</smartcopy>

To disable the server-side copy, define the following attribute:

<smartcopy rpc="no">

To enable raw copying (using physical batches), define the following attribute:

<smartcopy raw="yes">

<temporary>

In V2 and later, a FairCom RTG configuration element, <temporary> can be used to suppress the disk flush of certain operations to increase performance.

Note: Use this option only on files that are not required to persist in the event of a system crash or power failure.

<transaction>

The transaction option indicates whether or not to create files with transaction support enabled. This feature is turned on by default.

The <transaction fileops="yes"> setting instructs FairCom RTG/ISAM that file operations are under transaction processing control. Basically, it means that if you perform a file operation (file create, rename, delete) while a transaction is active, the result of such operation is affected by the transaction result.

For example, consider the following set of operations:

Open fileA
Begin Transaction
Update Record1 on FileA
Create fileB
Abort Transaction

• If fileops is turned on, fileB will be automatically removed when the transaction is aborted. If fileops is turned off (default) the file will always be created regardless of the transaction result.
• If fileops is turned on and a file creation is attempted outside a transaction scope, FairCom RTG/ISAM starts and commits a transaction automatically to allow for the file creation to complete.

Please note that it is possible to enable/disable transaction support and transaction logging on existing files using the -tron option of the ctutil utility.

Accepted Values

Attributes

Examples

Example 1: To turn off transaction logging:

<transaction logging="no">yes</transaction>

Example 2: The following pseudo-code creates a file if <transaction fileops="no"> and does not create a file if <transaction fileops="yes">:

begin
create file
rollback

Example 3: To enable autocommit optimization:

<transaction deferautocommit="yes">

<writethru>

The writethru option specifies whether to enable write synchronization.

Accepted Values

Example

<writethru>yes</writethru>