FairCom RTG COBOL Edition User's Guide

<file>

The file element specifies file-wide configurations. It is used to delimit options to a specific file identified by the name attribute or to all the files contained in a directory identified by the dir attribute.

The name and dir setting may contain the * wildcard to match multiple files with a single <file> section. The file matching rules that apply when the wildcard * is used are described in Wildcard File Matching Rules.

If multiple file rules match a file, the rules described in File Matching Precedence determine the rules that apply.

Attributes

Attribute	Description	Default Value
name	Specifies the string to match the file name portion of the file path passed by the COBOL application.	*
dir	Specifies the string to match the directory portion of the file path passed by the COBOL application. If attribute name is also specified, the option applies to the files that match both the directory and the name.	* See Empty String Note below.
casesensitive	Specifies if the file name and/or file dir attributes should be matched against the file path considering case sensitivity.	yes (file and directory names are case-sensitive)
priority	Specify the priority of this entry. Accepted values range from ‑32767 to +32767.	0 For "matching all file rules" (a rule matching all files in all directories) the default priority is ‑32767.
type	Specify the file organization. Valid values are: I - Indexed file R - Relative file. L - Line sequential file S - Record sequential file * - Any file type (this is the default)	*

Empty String Note: Setting the dir attribute to an empty string ("") is not the same as using a * wildcard. Instead, it means to match a file path with no directory.

Example

...

</file>

To turn off case sensitivity (the example below would match CUSTMAST, custmast, CustMast, etc.):

</file>

Wildcard File Matching Rules

FairCom RTG allows wildcard file matching. The only wildcard character is: *

The wildcard character can be placed at the beginning of a string, at the end of a string, or both. It is basically a way to say:

string* - Match names that begin with the given string.
*string - Match names that end with the given string.
*string* - Match names that contain the given string.

The file matching rules are not the same as those for Windows. For example, *.* matches any file name containing a "." but it does not match names without a dot (e.g., it matches "customer.dat" but not "customers").

Wildcard matching does not distinguish between file names and extensions. For example, cust* matches customers.dat because the wildcard character can match multiple characters in the file name as well as the extension.

Wildcard	Description	Example	Matches	Does NOT match
string*	The file or directory begins with the specified string and can end with anything.	cust* (names that begin with "cust")	cust customer customers customers.dat cust.dat	newcustomer (does not begin with "cust")
*string	The file or directory ends with the specified string and can begin with anything.	*customer (names that end with "customer" with no extension)	customer newcustomer	customer.dat (the entire file name, including extension, must end with "customer")
string	The file or directory contains the specified string and can begin and end with anything.	cust (Names that contain "cust")	customer newcustomer.dat
		. (Names that contain a dot: ".")	customer.dat	customer (name does not contain a dot: ".")

Summary of Wildcard Rules

If the name/dir setting does not contain a *, the <file> options apply to the files that exactly match the name/dir setting.

If the name/dir setting begins with a *, the <file> options apply to the files for which name/dir ends with the string on the right of the *. For example: <file name="*mast"> matches file name "custmast" but does not match file name "master".

If the name/dir setting ends with a *, the <file> options apply to the files for which name/dir begins with the string on the left of the *. For example: <file name="mast*"> matches file name "master" but does not match file name "custmast".

If the name/dir setting begins with a * and ends with a *, the <file> options apply to the files which name/dir contains the string enclosed between the * and *. For example: <file name="*mast*"> matches file name "master" and file name "custmast".

If the name/dir setting contains only a *, the <file> options apply to all files.

File Matching Precedence

When multiple <file> tags are specified in ctree.conf, a file name may match more than one tag. FairCom RTG provides file precedence rules to determine which rule is actually applied.

In release V3 and later, the rules for file precedence have been simplified. The new file matching rules differ from the old rules in these ways:

In case of multiple wildcard matches: The rule with the most matching characters (name and dir combined) takes precedence. For example, file name "custmast" matches <file name="cust*"> before matching <file name="*ast">.
In case the combined name and dir lengths are equal: The order of appearance in the configuration file is used. For example, file name "custmast" matches whichever comes first in ctree.conf between <file name="cust*" dir="."> and <file name="*mast" dir= ".">.

The <config prev12filematch="yes/no"> option is provided to revert to the old rules. The old and new rules are listed below.

New Rules

In V3 and later, the following file precedence rules are in effect when ctree.conf contains no prev12filematch option or when ctree.conf contains <config prev12filematch="no">.

In case a file matches multiple <file> rules:	A <file> rule with higher priority takes precedence over one with lower priority.
In case of matching priorities:	A specific type matching rule (i.e., I, R, L, or S) takes precedence over the * (unspecified) type.
In case of multiple rules with the same type:	An exact match has precedence over any wildcard match. For example, file name "custmast" matches <file name="custmast"> before matching <file name="cust">. The match with the greatest number of specific matching characters wins. For example, file name "custmast" matches <file name="cust"> before matching <file> or <file name="">. Please notice that specifying <file name=""> is equivalent to not specifying <file name> at all.
In case of multiple wildcard matches:	The number of matching characters in name and directory is considered. The rule with the greater number of matching characters in the <file name> and <file dir> values takes precedence over rules that result in fewer matching characters. For example, file name "custmast" matches <file name="cust" dir="/data"> before matching <file name="ast" dir="data/">.
If the number of matching characters is the same:	The first rule in order of appearance in the ctree.conf file takes precedence over later rules. For example, file name "custmast" matches whichever appears first in the ctree.conf file between <file name="cust" dir="."> and <file name="mast" dir= ".">

Old Rules (backward compatibility)

The following file precedence rules are provided for backward compatibility. They are applied when ctree.conf contians <config prev12filematch="yes">.

Note: This is the set of rules that was used prior to FairCom RTG V3:

In case a file matches multiple <file> rules:	A <file> rule with higher priority takes precedence over one with lower priority.
In case of matching priorities:	A specific type matching rule (i.e., I, R, L, or S) takes precedence over the * (unspecified) type.
In case of multiple rules with the same type:	An exact match takes precedence over any wildcard match. For example, file name "custmast" matches <file name="custmast"> before matching <file name="cust">. A wildcard match has precedence over an unspecified match. For example, file name "custmast" matches <file name="cust"> before matching <file> or <file name="">. Please notice that specifying <file name=""> is equivalent to not specifying <file name> at all.
In case of multiple wildcard matches:	The rule with the most matching characters takes precedence: For example, file name "custmast" matches <file name="cust"> before it matches <file name="ast">.
In case both name and dir are specified:	The sum of the matching characters of both name and dir setting is considered.
In case the sum of matching characters is equal:	The rule with the longest matching characters takes precedence: For example, file name "custmast" matches <file name="cust" dir="data"> before it matches <file name="mast" dir= ".">.
In case the lengths of the settings are equal	Alphabetical order is used: For example, file name "custmast" matches <file name="cust" dir="."> before matching <file name="mast" dir= ".">.

Option to print the file rule sequence

This useful new ctutil option prints out the list of file rules in the sequence they are considered when matching file names. This feature is useful for debugging and to understand why a file gets matched to an unexpected rule.

The new ctutil -test filerules option will print the file rules in the order they will be considered by FairCom RTG at runtime when matching a filename:

ctutil -test filerules

Initialized from (ctree.conf)

Operation completed successfully.