RTG settings elements

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

See Also

• FairCom RTG 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>

<batchaddition>

The batchaddition option enables batch record writes to improve performance of consecutive record additions. This is achieved by caching the records being added in the client side before they are sent in one batch operation to the server to be written to disk. The records are sent to the server after a given number of records (specified by the records attribute) have been added or when the file is closed. Since the records are actually written when they are sent to the server, a duplicate key error is returned by the operation that triggered the batch write operation. For this reason, batchaddition is recommended only for specific operations such as data import where duplicate errors are not expected. It is important that COBOL applications performing batchaddition check the status of CLOSE operations to detect possible errors writing records.

Writing records in batches improves performance of large record additions in environments where 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.

The batchaddition option is available only for files opened with OUTPUT or EXTEND mode.

The number of records to cache is defined by the records attribute.

The batchaddition option is disabled by default.

Note: Adding records using <batchaddition> within explicit transactions started by the user is not supported. If a file is OPEN WITH ROLLBACK and the file is configured for <batchaddition>, any WRITE operation that adds a record within an active transaction will fail until the transaction ends with a Commit or Rollback. To add records to a file with OPEN WITH ROLLBACK and <batchaddition> enabled, perform WRITE operations without starting a transaction.

Accepted Values

Attributes

Examples

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

<bulkaddition>

The bulkaddition option enables deferred key writes to improve performance of consecutive record additions. This is achieved by writing only the data record and postponing the key addition until the file is closed. When the file is closed, all pending keys are written in one single operation by an index rebuild routine. This technique of adding records has two benefits:

1. The index rebuild operation is faster than the sum of each key addition operation.
2. The index rebuild operation creates an index that is efficiently organized resulting in faster key searches.

The bulkaddition option is available only for files opened with OUTPUT or EXTEND mode. The bulkaddition option is disabled by default.

Buk addition is made with direct updates to the data file bypassing standard ISAM operations. Because of this optimization, bulk additions are not replicated. For use with a new table that is bulk loaded, the final indexed file would then need to be synchronizer across servers for replication.

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

Accepted Values

Attributes

Examples

To enable bulkaddition:

<bulkaddition>yes</bulkaddition>

To use the prmiidx optimization:

<bulkaddition prmiidx="yes">yes</bulkaddition>

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

<ctflexrec>

<ctflexrec> enables files be created with support for hot alter table. It determines whether to create files with RTG file mode ctFLEXREC required to support features such as the Hot Alter Table.

Tables are created by default with this mode as of RTG V12.5.0 and later.

Accepted Values

Review the ctutil -alter option for specific usage of Hot Alter Table with RTG tables.

<ctfixed> and <ctflexrec> are mutually exclusive and can not be combined together and an error will result.

Example

<ctflexrec>yes<ctflexrec>

 See Also

-alter

<recordcheck>

<maxlencheck>

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

<detectlock>

This configuration option simulates the behavior of the Micro Focus DETECT-LOCK compiler directive:

• DETECT-LOCK - If a READ statement reads a record locked by another program, it reads the record successfully and returns an error.
• NO DETECT-LOCK - If a READ statement reads a record locked by another program, it reads the record successfully and returns no error.

The <detectlock> option defaults to "no" which means that no error is returned when trying to retrieve a record locked by another user if the LOCK MODE is MANUAL and the READ operation does not have an explicit WITH LOCK option.

Example

<detectlock>yes</detectlock>

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

<extfhexit>

Detects library loading and unloading and de-initializes c-tree at library unload.

Description

The <extfhexit> global configuration keyword is used to determine c-tree de-initialization behavior when libraries are unloaded.

Accepted Values

<extfhreindexoncreate>

The <extfhreindexoncreate> global configuration keyword is used to determine whether new indices created by the EXTFH Create Index operation (special opcode 07) are immediately populated with key values.

If yes, the Get Next Record (special opcode 08) and Add Key Value (special opcode 09) operations become obsolete, allowing for improved performance. The no option is currently unsupported.

Accepted Values

<filecopy>

The <filecopy> configuration setting forces the use of the server-side file copy capability to carry on copy operations. The <filecopy> option is not enabled by default so a user must explicitly enable it in the configuration file in order to use it. When <filecopy> is enabled and conditions do not allow it to be used, the copy operation fails rather than falling back to other copy methods.

The <filecopy> option forces a physical copy of the data and index files. The other copy mechanisms available extract the structure information for the source file, create a new file accordingly with the current ctree.conf settings, and then copy records from the source to the destination (the outcome of this process can be a file which is not identical to the source file, for example it might be compressed when the source was not).

Accepted Values

Attributes

See also:

• ctutil -filecopy

<filepool>

Enables and disables support for file pooling.

Description

In COBOL applications it is common practice to close and re-open files when entering procedures. This can cause unnecessary overhead and performance issues in FairCom RTG.

The filepool feature introduces support for file pooling to keep files open when the COBOL application requests to close them. This allows the file handle to be returned immediately when the COBOL application requests to re-open it.

The <filepool> global configuration keyword enables and disables support for file pooling and optionally Sets the size of the file pool with attribute <filepool size> where size is the maximum number of files to keep in the pool.

Accepted Values

Attributes

A configuration keyword <inpool> defines if a file can be included in the file pool.

Consideratrions

1. <filepool> is client-specific and not shared among clients. Consider user A adds a file to a filepool and user B attempts to operate on that file with ctutil -copy. This fails with error 12 (-8). Automatic removal from a pool during the copy can only be done for the user that requested the pool.
2. Because the file remains physically open, other clients that expect the file to be closed (for example, when they attempt to open the file exclusively) get an error such as c-tree uerr_cod = 12 sysiocod = -8, which indicates the file is open by another client. This may be confusing as the file is logically closed by all clients.
   1. Currently there is no way for other clients to detect that the file is physically open by the <filepool> or request that the file is physically closed and removed from the <filepool> list.
3. <filepool> was introduced to increase the performance of applications that continuously close and re-open the same file in a short amount of time. It has been designed assuming that only the files that are frequently closed and re-opened are included in the pool. Files that are not frequently closed and re-opened should not be marked as <inpool>. It does not make sense to put many files in the pool as there are side-effects to keep the files physically open (conflicts, consume of both memory and file handles, etc.). In addition, searching for entries in a larger pool is slower and could frustrate the attempt to speed up the file open.

<filepool size> indicates the number of data files and it is recommended to keep it as low as possible.

See also:

• <inpool>

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

<ignorelock>

The ignorelock option determines how READ operations should handle locks. Its behavior is similar to the Micro Focus IGNORELOCK option. This option is turned off by default, which corresponds to the default for Micro Focus COBOL.

Accepted Values

Example

<ignorelock>yes</ignorelock>

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

<inpool>

The configuration keyword <inpool> defines if a file can be included in the file pool.

For example:

<config>
 <filepool size="40">yes</filepool>
 <instance server="FAIRCOMS">
  <file>
   <inpool/>
  </file>
 </instance>
</config>

See also:

• <filepool>

<keycheck>

The keycheck option specifies whether to check that all the keys belonging to an indexed file are defined in the COBOL program. If this option is enabled, keys must match key definitions otherwise an error is returned. If this option is disabled, files containing more keys than described in a COBOL program are allowed. Files that contain fewer keys than key definitions are never allowed regardless of the keycheck setting. Disabled by default.

The keycheck configuration does not apply to isCOBOL and ACUCOBOL because these COBOL runtimes perform checks on the key structure.

Accepted Values

Example

<keycheck>no</keycheck>

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

<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 RTG 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>

<rle>

The keycompress rle option indicates to compress the whole key using a simple RLE algorithm. This is the recommended compression that performs well in the majority of cases.

Accepted Values

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

<keycompress vlennod="yes"><rle>yes</rle></keycompress>

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

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

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

<locktype>

The locktype option allows changing the default record locking behavior of the COBOL system in use. It is similar to settings 0 and 1 of the Micro Focus LOCKTYPE option.

Note: If not specified, the default record locking behavior of the COBOL system is used, ExtFH interface (i.e., Micro Focus) or ACUCOBOL, as shown below. This option allows that behavior to be overridden.

Accepted Values

Example

<locktype>0</locktype>

<maxlencheck>

The maxlencheck option specifies whether to check that the record being read from disk fits entirely into the record buffer for which length is equal to the maxlen file definition. If this option is set to yes, an error is returned if the record read from disk is larger than maxlen bytes. If this option is set to no, the record is truncated at maxlen bytes before it is returned to COBOL. This option is enabled by default.

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: maxlencheck is performed on each record read operation to check if a variable length record fits in the defined record max length as specified in the application FD. This in in contrast to the recordcheck option which validates the record size on file open.

Accepted Values

Example

<maxlencheck>no</maxlencheck>

See Also

-alter

<recordcheck>

<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

<map>

The map option replaces the file name or directory passed by the COBOL 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 COBOL application.

<dir> map option

The dir option specifies the string that replaces the directory portion of the file path passed by the COBOL 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 COBOL 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 COBOL 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>

<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 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 (see links for examples):

<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 COBOL 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>

<permission>

The <permission> configuration option allows you to set file read/write access, file redefinition, and file delete permissions for the file owner, group members, and all other users.

The <permission> configuration option can have up to 3 possible options:

• <owner> - set permissions for the file owner
• <group> - set permissions for the group members of file owner
• <world> - set permissions for the rest of all users

In turn <owner>, <group>, and <world> can each have up to 4 possible options:

• <read> - set file access permission
• <write> - set record write permission
• <def> - set file redefinition permission
• <delete> - set file delete permission

If the <permission> keyword is not specified in the configuration file, the default behavior is to allow all permissions to all users. If <permission> is specified in the configuration file, the default behavior is to deny permission unless it is specifically specified with configuration options.

Example 1

The following permission configuration permits file deletion and file redefinition only to the file owner while all users can access the file for reading but only members of the file owner group are allowed to write records:

 
<file dir="protected">
 <permission>
  <owner><read>yes</read><write>yes</write><def>yes<def/><delete>yes</delete></owner>
  <group><read>yes</read><write>yes</write><def>no<def/><delete>no</delete></group>
  <world><read>yes</read><write>no</write><def>no<def/><delete>no</delete></world>
 </permission>
</file>
 

Example 2

The following permission configuration permits file deletion and file redefinition only to the file owner while all users can access the file for reading but only members of the file owner group are allowed to write records:

 
<file dir="protected">
 <permission>
  <owner><read/><write/><def/><delete/></owner>
  <group><read/><write/></group>
  <world><read/></world>
 </permission>
</file>

<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 (READ NEXT) or the previous record (READ PREVIOUS). The READ NEXT or the READ 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 where large numbers of READ 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 READ 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 a READ KEY operation in the middle of a READ NEXT or READ PREVIOUS sequence invalidates the prefetched records, causing the prefetch logic to restart at the next READ NEXT or READ 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

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.

The following example enables <prefetch> reading for at least 5 records allowing 2 seconds to consume the prefetched records:

 
<config>
   <instance server="FAIRCOMS">
      <file>
         <prefetch records="5" ttl="2"/>
      </file>
   </instance>
</config>
 

Notes about <prefetch allowwriters>

If you are calling READ NEXT or READ 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 READ NEXT calls.

If you are calling READ NEXT or or READ 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.

<prefetch ttl> attribute to define how long a set of prefetched records remains VALID

FairCom RTG has the ability to "prefetch" records to improve efficiency. When a client requests a record from the server, it can be more efficient to fetch several records at a time because they can share the same communications overhead. If the client needs another record, it may find that record has already been prefetched, making it available with no additional overhead.

In some situations, the prefetched records have been waiting long enough that they are no longer valid. This is particularly true if the application has been waiting for user input and other users have attempted to access the same records. In this case, it is necessary to invalidate the prefectched records so they will be fetched again when needed.

This modification introduces a new <prefetch ttl> attribute (ttl is "time-to-live") that defines the number of seconds a set of prefetched records remains valid. By default, the value is set to 0 seconds which means that prefetched records do not expire. When <prefetch> is enabled and <prefetch ttl> attribute is set, the records prefetched by a sequential read that are not consumed within the number of seconds specified in the <prefetch ttl> attribute will be discarded and the next consecutive sequential operation will cause a new prefetch to be requested from the server.

Example:

The following example enables <prefetch> reading for at least 5 records allowing 2 seconds to consume the prefetched records:

 
<config>
   <instance server="FAIRCOMS">
      <file>
         <prefetch records="5" ttl="2"/>
      </file>
   </instance>
</config>

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

<retrylock>

The retrylock option indicates whether a READ operation that fails because a record is locked should wait until the lock is released rather than returning an immediate lock error. When this option is enabled, records are locked with the c-tree lock mode of ctENABLE_BLK instead of ctENABLE.

Accepted Values

Example

<retrylock>yes</retrylock>

<rowid>

The <rowid> option enables support for creating a ROWID field/index. ROWID is required for creating Full-Text Indexes, 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>

<runitlockdetect>

The runitlockdetect option specifies whether to check if a record has been locked by a separate OPEN statement issued from within the same run unit. When this option is turned on, a lock error is returned while reading a record that was locked within the same instance. When this option is turned off, reading a record that was locked within the same instance does not produce a locking error.

Accepted Values

Valid <runitlockdetect> combination settings are:

<runitlockdetect>yes<runitlockdetect> (attributes anyunlock and unlockall are ignored)
<runitlockdetect anyunlock="yes">no<runitlockdetect> (attribute unlockall is ignored)
<runitlockdetect anyunlock="no" unlockall="no">no<runitlockdetect>
<runitlockdetect anyunlock="no" unlockall="yes">no<runitlockdetect>

Example (detect record locks):

<runitlockdetect>yes</runitlockdetect>

<runitlockdetect anyunlock> Attribute

The anyunlock and unlockall attributes define the unlock strategy for the shared locks therefore they are meaningful when locks are shared that is when <runitlockdetect> is set to No. When set to Yes, each OPEN instance is treated as a different run unit and locks are not shared.

The unlockall attribute defines whether the shared locks must be released by all the OPEN instances that acquired the lock, therefore it is meaningful only if <runitlockdetect anyunlock> is set to No. When set to Yes, any OPEN instance can release the shared lock.

The combinations of the anyunlock and unlockall attributes allows matching the behavior of COBOL runtimes and file systems:

• <runitlockdetect anyunlock="no" unlockall="yes">no</runitlockdetect> - The shared lock is released when all instances that acquired the lock have release it (which mimics the Btrieve file system).
• <runitlockdetect anyunlock="no" unlockall="no">no</runitlockdetect> - The shared lock is released when the first instance that acquired the lock releases it (which mimics the ACUCOBOL runtime).
• <runitlockdetect anyunlock="yes">no</runitlockdetect> - The shared lock is released when any instance that acquired the lock releases it (which mimics the behavior of the Micro Focus runtime).

Example (lock released when all OPEN instances have release their lock):

<runitlockdetect anyunlock="no" unlockall="yes">no</runitlockdetect>

<scancache>

Allows setting the cache strategy to be used for reading one file or a set of files. The notes below for a discussion of cache scanning.

Accepted Values

Example

To enable the cache scanning strategy:

<scancache>yes</scancache>

To disable cache scanning and use the default c-tree strategy:

<scancache>no</scancache>

Cache Scanning Strategy

The FairCom RTG <scancache> configuration option allows setting the cache strategy to be used for reading one file or a set of files. The <scancache> option is a boolean that is enabled with <scancache>yes</scancache>, or disabled with <scancache>no</scancache>.

If <scancache>no</scancache> is used, the data cache buffer pages are managed using c-tree's default reuse scheme, which reassigns a cache page anytime a read requires a page that is not already in cache. This strategy can allow a single user doing many reads from a single file to take over a large percentage of the total cache for that file.

If this option is enabled with <scancache>yes</scancache>, all the standard cache routines are used unless the read requires a cache page that is not already in cache. In that case, it limits each user to a maximum of 2 cache pages. The significance of this strategy is that a large set of data record read operations can be performed using only two cache pages with little or no decrease in performance compared to no restrictions on cache usage. Moreover, such restricted use may help other aspects of system performance since the bulk of data cache can be used for other files and/or other users. A large traversal of the data file by a single user will not replace other cache pages that may be useful to other users.

For more about this caching technique, see Scanner Cache in the FairCom DB Developer's Guide.

<skiplock>

The skiplock option advances the current record pointer when a locked record is encountered. This feature is off by default.

Accepted Values

Example

<skiplock>yes</skiplock>

<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">

<sqlize>

The sqlize option indicates whether to attempt linking the table to FairCom DB SQL when creating a new table. If this option is set to yes, the necessary operations to make the file accessible from FairCom DB SQL are performed when the file is open with OUTPUT or EXTEND mode. This option is disabled by default. The sqlize option accepts both XFD and XDD files as input.

Accepted Values

Attributes

XFD / XDD Notes

The xfd and xdd attributes can be used to specify an XDD (or XFD or .iss) file to use for the sqlize operation. This parameter accepts either a XDD file name or a full path to a XDD file. If only the file name is specified, the XDD file must be available to the ctutil client. Files and paths are relative to the ctutil working directory.

Values may contain %n and %d substitution specifiers. For more information about substitution specifiers, please refer to the topic Substitution specifiers.

Note: If both xfd and xdd attributes are specified, the logic first looks for an XDD file and if the file is not found, sqlize falls back to looking for an XFD file.

Note: If an XDD is directly specified with ctutil -make, any XDD specified with <sqlize> in a ctree.conf configuration is ignored in favor of the passed in XDD.

Examples

<sqlize xfd="custmast.xfd" symbolic="customers">yes</sqlize>
<sqlize xfd=".\xfd\" prefix="2012">yes</sqlize>
<sqlize xfd="%n.xfd">yes</sqlize>

<startonread>

Enables "Start on Read" logic to improve performance of applications that perform a large number of START operations all followed by READ sequential operations, such as READ NEXT or READ PREVIOUS.

Accepted Values

Example

To enable start on READ logic:

<startonread>yes</startonread>

Notes

The <startonread> configuration option improves performance of COBOL applications that perform a large number of START operations all followed by READ sequential operations, such as READ NEXT or READ PREVIOUS.

When <startonread> is enabled, FairCom RTG does not execute the START operations immediately. Instead, it waits for the subsequent READ sequential operation (READ NEXT or READ PREVIOUS). The effect is that START operations return immediately but never fail even if the specified key is not valid. It is the subsequent READ sequential operation that executes the START operation and eventually returns the error. For this reason, we do not recommend using this option unless the user understands the risks.

If the FairCom RTG server does not support <startonread>, the FairCom RTG client fails and logs error message “server does not support <startonread> configuration.”

SYMPTOM: Performance of START + READ NEXT / PREVIOUS is worse when <prefetch> is enabled and gets worse increasing the number of prefetched records with <prefetch records> configuration attribute.

PROBLEM: The RTG prefetch logic gets triggered by the second consecutive READ NEXT or READ PREVIOUS operation as a consequence, a loop of START operations followed by READ NEXT operations will never trigger the prefetch logic. However the logic that sends the request to the RTG server to read the next record, prepares the RPC network buffer to receive the prefetched records when just the <prefetch> configuration option is enabled. The result is that an useless memory allocation is performed during a READ NEXT operation that does not prefetch records. This unused amount of memory can be significant for large <prefetch records> attribute settings. We noticed that large memory allocations are sometime costly in terms of performance depending of the platform.

SOLUTION: Change the logic that calculates the RPC network output buffer to include the prefetch buffer size (CT_FILE->fetsiz) only if a prefetch request is actually sent to the server.

<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">

<trxholdslocks>

This configuration keyword simulates ACUCOBOL's TRX_HOLDS_LOCKS=1 option, which does not free locks at transaction commit unless the locked records are updated during the transaction.

Note: The <trxholdslocks> option is global-only and can be set only as a child of <config>. It is not valid if specified as child of <*instance> or <file>.

Accepted Values

Example

<trxholdslocks>yes</trxholdslocks>

<writethru>

The writethru option specifies whether to enable write synchronization.

Accepted Values

Example

<writethru>yes</writethru>