Configuring the client

Configuring the client through Framework properties

The isCOBOL Framework looks for the c-tree configuration between configuration properties if

•	the c-tree version is 9.5.49790 or greater

•	the property iscobol.ctree.new_config (boolean)* is set to true

Properties are evaluated at the first open of a c-tree file. Changing them after the first c-tree file has been opened will have no effect.

Property	Description
iscobol.file.index.autolock_allowed (boolean)	True = More locks on the same record can be acquired in the same run unit. False = Only one lock on the same record can be acquired in the same run unit.   If omitted, False is assumed.
iscobol.file.index.batchaddition (boolean)	True = write operations are buffered in order to speed up performance. False = write operations are not buffered.   If omitted, False is assumed.
iscobol.file.index.batchaddition.records	Specifies the number of write operations that must be buffered at a time.   If omitted, 10 is used.
iscobol.file.index.bulkaddition (boolean)	True = files open for output are managed with bulk addition (indexes are written at the close of the file) to speed up performance. False = files open for output are managed without bulk addition.   If omitted, False is assumed.
iscobol.file.index.connect (boolean)	True = connect to c-tree server during runtime initialization. False = connect to c-tree server at the first open of a c-tree file.   If omitted, False is assumed.
iscobol.file.index.data_suffix	Specifies the extension for the data file.   If omitted, then .dat is assumed.
iscobol.file.index.datacompress (boolean)	True = data records are compressed using zlib algorithm. False = data records are not compressed.   If omitted, False is assumed.
iscobol.file.index.datacompress.level	This property selects the zlib compression level. Valid values are between 1 and 9 where 1 gives best speed but use more disk space and 9 gives best compression at the expenses of performance.   If omitted, then 1 is assumed.
iscobol.file.index.datacompress.strategy	This property specifies the strategy for data compression. Possible values are: 0 = Use the default zlib compression strategy. 1 = Use the zlib filtered compression strategy. 2 = Use zlib Huffman only compression strategy. 3 = Use zlib RLE compression strategy. 4 = Use zlib fixed compression strategy.   If omitted, 0 is assumed.
iscobol.file.index.datacompress.type	Specifies the algorithm for data compression. Valid values are: zlib = zlib algorithm is used. rle = rle algorithm is used.   If omitted, then rle is assumed.
iscobol.file.index.encrypt (boolean)	True = files are encrypted using ctCAMO encryption algorithm. False = files are not encrypted.   If omitted, False is assumed.
iscobol.file.index.file_mapping	This property specifies the list of files that should be included in the current instance. Multiple names must be separated by comma. Wildcards are supported. See Configuring multiple instances for details.
iscobol.file.index.file_mapping_p	This property specifies the list of files that should be included in the current instance. Multiple names must be separated by comma. Wildcards are supported.   At the end of each file name you can put an ordinal number that is the number of the path between iscobol.file.index_path_mapping paths. In this way it’s possible to specify a file mapping for each path maggping. Example:   iscobol.file.index.1.path_mapping=/dir1,/dir2 iscobol.file.index.1.file_mapping_p=customers1,invoices1,reports2,discounts   The instance mapping is valid for the files customers and invoices when they’re are under /dir1, for reports when it’s is under /dir2 and for discounts, wherever it is.   See Configuring multiple instances for details.
iscobol.file.index.fixed_length (boolean)	True = files are created with fixed length records. False = files are created with variable length records.   If omitted, False is assumed.
iscobol.file.index.forcedelete (boolean)	True = if a file segment is missing, DELETE FILE deletes the other segment. False = if a file segment is missing, DELETE FILE returns a ‘file corrupted’ error.   If omitted, False is assumed.
iscobol.file.index.index_suffix	Specifies the extension for the index file.   If omitted, then .idx is assumed.
iscobol.file.index.keycheck (boolean)	True = extra keys in the file are not allowed. False = extra keys in the file are allowed.   If omitted, True is assumed.
iscobol.file.index.keycompress (boolean)	True = index files are compressed using zlib algorithm. Leading and padding compression are applied. False = index files are not compressed.   If omitted, False is assumed.
iscobol.file.index.keycompress.leading (boolean)	True = leading compression is applied on index files. False = leading compression is not applied on index files.   If omitted, False is assumed.
iscobol.file.index.keycompress.padding (boolean)	True = padding compression is applied on index files. False = padding compression is not applied on index files.   If omitted, False is assumed.
iscobol.file.index.lock_read_anyhow (boolean)	True = locked records are returned. False = locked records are not returned.   If omitted, False is assumed.
iscobol.file.index.lock_wait (boolean)	True = if a record is locked, wait until lock is released. False = if a record is locked, return a record locked error.   If omitted, False is assumed.
iscobol.file.index.log.debug.batchaddition (boolean)	True = trace batchadditions details. False = do not trace batchaddition details.   If omitted, False is assumed.
iscobol.file.index.log.debug.prefetch (boolean)	True = trace prefetch details. False = do not trace prefetch details.   If omitted, False is assumed.
iscobol.file.index.log.error (boolean)	True = trace errors in the log file. False = do not trace errors in the log file.   If omitted, False is assumed.
iscobol.file.index.log.error.atend (boolean)	True = trace EOF errors. False = do not trace EOF errors.   If omitted, False is assumed.
iscobol.file.index.log.error.notfound (boolean)	True = trace NOTFOUND errors. False = do not trace NOTFOUND errors.   If omitted, False is assumed.
iscobol.file.index.log.file	Specifies the name of the log file where to trace c-tree client operations.   If omitted, no log is created.
iscobol.file.index.log.info (boolean)	True = trace generic information in the log file. False = do not trace generic information in the log file.   If omitted, False is assumed.
iscobol.file.index.log.profile (boolean)	True = trace profile information in the log file. False = do not trace profile information in the log file.   If omitted, False is assumed.
iscobol.file.index.maxinstance	This property specifies how many instances can be created. It is mandatory in order to work with multiple instances. The value must range between 2 and 99. Any value less than 2 is considered as 2 while any value greater than 99 is considered 99. Note that the default instance is counted, so you should calculate the value of this property by adding 1 to the highest instance number you put in your property names. See Configuring multiple instances for details.
iscobol.file.index.maxlencheck (boolean)	True = return an error if record is larger than maxlen bytes.. False = record larger than maxlen bytes is allowed.   If omitted, False is assumed
iscobol.file.index.memoryfile (boolean)	True = files are created in memory rather than on disk. False = files are created on disk.   If omitted, False is assumed.
iscobol.file.index.optimisticadd (boolean)	True = use optimistic strategy when adding records. Unique key violation is not checked before writing the whole record. This provides better performance. False = use pessimistic stragety when adding records.. Unique key violation is checked before writing the whole record.   If omitted, True is assumed
iscobol.file.index.password	This property specifies the password.   If omitted, then ADMIN is assumed
iscobol.file.index.path_mapping	This property specifies the list of paths that should be included in the current instance. Multiple paths must be separated by comma. See Configuring multiple instances for details.
iscobol.file.index.prefetch (boolean)	True = read operations are buffered in order to speed up performance. False = read operations are not buffered.   If omitted, False is assumed.   The number of buffered records is controlled by iscobol.file.index.prefetch.records. The locking on these records is controlled by iscobol.file.index.prefetch.allowwriters (boolean).
iscobol.file.index.prefetch.allowwriters (boolean)	True = prefetched records are not locked. False = prefetched records are locked.   If omitted, False is assumed.   Note - if the file has an implicit or explicit LOCK MODE AUTOMATIC WITH LOCK ON MULTIPLE RECORDS, then all the prefetched records are locked, since these records are retrieved with the same options of the READ NEXT that instigates the read a-head operation.
iscobol.file.index.prefetch.records	Specifies the number of read operations that must be buffered at a time.   If omitted, 10 is used.   Note - this value should be set carefully according to the number of read operations between a Start and another. Having an high value for this setting and few read operations between a Start and another might slow down performance as useless records are loaded in memory even if the program will not read them.
iscobol.file.index.read_lock_test	True = a READ WITH NO LOCK returns a lock condition if the record is locked. False = a READ WITH NO LOCK reads the record even if it’s locked.   If omitted, False is assumed.
iscobol.file.index.rpc (boolean)	True = use RPC calls to communicate with c-tree server False = use standard c-tree calls to communicate with c-tree server (recommended only for diagnostic purposes)   If omitted, True is assumed
iscobol.file.index.rpc.crc (boolean)	True = enable CRC checks on the RPC data buffers that are sent/received over the network. Recommended only for diagnostic purposes. False = disable CRC checks on the RPC data buffers that are sent/received over the network.   If omitted, False is assumed
iscobol.file.index.server	This property specifies the server name and IP address. The value can be one of the following syntaxes: • servername • servername@hostname • servername@IPaddress • #port@hostname • #port@IPaddress   If omitted, then FAIRCOMS@127.0.0.1 is assumed.
iscobol.file.index.skiplock (boolean)	True = advance to the next record when a locked record is encountered. False = do not advance to the next record when a locked record is encountered.   If omitted, False is assumed.
iscobol.file.index.transaction (boolean)	True = transaction support is on. False = transaction support is off.   If omitted, True is assumed.
iscobol.file.index.transaction.dependent	True = file operations are transaction dependent. False = file operations performed within an active transaction are not affected by the transaction ending operation (commit or abort).   If omitted, False is assumed
iscobol.file.index.transaction.logging (boolean)	True = turns on transaction logging. It is indicated when data safety is more important than performance. Files are created with c-tree file mode ctTRNLOG and are automatically recovered after a crash. False = turns off transaction logging. It is indicated when performance is more important than data safety.   If omitted, False is assumed.
iscobol.file.index.trxholdslocks (boolean)	True = only the locks on records updated during the transaction are released at transaction commit while all other locks not specifically released are held. At transaction rollback instead records locks are held unconditionally. False = all pending locks are released during a transaction commit or rollback.   If omitted, False is assumed.
iscobol.file.index.user	This property specifies the user name.   If omitted, then admin is assumed
iscobol.file.index.versioncheck (boolean)	True = check if c-tree client and server versions match during the connection at runtime initialization. False = do not check if c-tree client and server versions match during the connection at runtime initialization.   If omitted, False is assumed.

Configuring multiple instances

It is possible to define multiple instances of the c-tree client in the same runtime session. Each instance can work on a different server and can have a specific configuration. For example you might want all files whose name starts with “TMP” to be treated as memory files, or you might want to distribute your archives on different c-tree servers depending on the directory where they reside.

In order to create multiple instances, you can repeat the above iscobol.file.index settings by putting the instance number between before the setting name. For example:

iscobol.file.index.server=FAIRCOMS@127.0.0.1 iscobol.file.index.1.server=FAIRCOMS@192.168.0.101 iscobol.file.index.2.server=FAIRCOMS@192.168.0.102

The above snippet defines three instances that connect to three different servers.

Note that the iscobol.file.index.maxinstance property must be set accordingly or an error will occur. According to the above snippet, since we have three instances defined, we will set

iscobol.file.index.maxinstance=3

The runtime chooses which instance to use by checking the file name and path against the properties iscobol.file.index.file_mapping and iscobol.file.index.path_mapping.

Example:

iscobol.file.index.server=FAIRCOMS@127.0.0.1 iscobol.file.index.1.server=FAIRCOMS@192.168.0.101 iscobol.file.index.2.server=FAIRCOMS@192.168.0.102 iscobol.file.index.1.path_mapping=/dir1 iscobol.file.index.2.path_mapping=/dir2

According to the above configuration, all files under the /dir1 folder will go on the server listening on 192.168.0.101, all files under the /dir2 folder will go on the server listening on 192.168.0.102, while all the other files will go on the server listening on 127.0.0.1.

Once multiple instances are defined, specific properties can be specified for each instance.

Example

iscobol.file.index.server=FAIRCOMS@127.0.0.1 iscobol.file.index.1.server=FAIRCOMS@192.168.0.101 iscobol.file.index.2.server=FAIRCOMS@192.168.0.102 iscobol.file.index.1.path_mapping=/dir1 iscobol.file.index.2.path_mapping=/dir2 iscobol.file.index.1.memoryfile=true

According to the above snippet, all the files on instance number 1 will be memory files.

Note - When setting configurations made by multiple properties (e.g. the log or the key compression), all the properties should be related to the instance. For example, the following configuration is not correct:

iscobol.file.index.1.log.file=/tmp/ctree.log iscobol.file.index.log.error=1 iscobol.file.index.log.profile=1 iscobol.file.index.log.info=1

because only the file has been specified for the instance number 1, but all the other settings will go on the default instance and will be ignored by the instance number 1. The correct configuration would be:

iscobol.file.index.1.log.file=/tmp/ctree.log iscobol.file.index.1.log.error=1 iscobol.file.index.1.log.profile=1 iscobol.file.index.1.log.info=1