The Open Client and Open Server runtime configuration file is a text file. The file is separated into sections, each of which begins with a section name enclosed in square brackets ([]) and ends with the next section name or the end of the file, whichever appears first.
Each section contains one or more settings, as illustrated below:
[section name] keyword = value ; comment keyword = value
; more comments
[next section name]
... and so forth ...
In general, all supported keywords in the file match the names of the symbolic constants that would identify the property, option, or capability in a Client-Library/C program. However, not all properties can be set in the configuration file. If a keyword is not supported, the setting is ignored.
The syntax is as follows:
; – Signifies a comment line.
[section_name] – Section names are wrapped in square brackets. The Open Client/Server configuration file comes with a section named DEFAULT. The application name will be used as the section name for an application that has been compiled with the -x option. For an application that has been compiled with the -e option, the server name will be used for the section name. Any name can be used as a section name for the sections that contain settings that will be used in multiple sections. The following example shows a section arbitrarily named “GENERIC,” and how that section is included in other sections:
[GENERIC]
CS_OPT_ANSINULL=CS_TRUE
[APP_PAYROLL]
include=GENERIC
CS_CAP_RESPONSE=CS_RES_NOSTRIPBLANKS
[APP_HR]
include=GENERIC
CS_OPT_QUOTED_IDENT=CS_TRUE
entry_name=entry_value
Entry values can be anything: integers, strings and so on. If an entry value line ends with '\'<newline>, the entry value continues to the next line.
White spaces are trimmed from the beginning and end of entry values.
If white spaces are required at the beginning or end of an entry value, wrap them in double quotes.
An entry that begins with a double quote must end with a double quote. Two double quote characters in a row within a quoted string represent a single double quote in the value string. If a newline is encountered within double quotes, it is considered to be literally part of the value.
Entry names and section names can consist of alphabetic characters (both upper and lower case), the digits 0-9, and any of the following punctuation characters:
! " # $ % & ' ( ) * + , - . / : ; < > ? @ \ ^ _ ` { | } ~
Square brackets, spaces, and the equal symbol (=) are not supported. The first letter MUST be alphabetic.
Entry and section names are case sensitive.
Include=earlier_section
If a section contains the entry include, then the entire contents of that previously defined section are considered to be replicated within this section. In other words, the properties defined in the previous section are inherited by this section.
The included section must have been defined prior to
it being included in another section. This allows the configuration
file parsing to happen in a single pass and eliminates the need
to detect recursive included directives.
If an included section in turn includes another section, the order of entry values is defined by a “depthfirst” search of the included sections.
Sections cannot include a reference to themselves. In other words, recursion is not possible because you must include a previously defined section—you cannot include the section being defined.
All direct entry values defined in a given section supersede any values which may have been included from another section. In the following example, CS_OPT_ANSINULL will be set to false in the APP.PAYROLL application.
The position of the include statement
does not affect this rule.
[GENERIC]
CS_OPT_ANSINULL=CS_TRUE
[APP_PAYROLL]
CS_OPT_ANSINULL=CS_FALSE
include=GENERIC
If an entry’s value in a C program takes symbolic constants, then the legal values are the names of these constants. For example:
CS_NETIO = CS_SYNC_IO
If an entry’s value in a C program takes integer values, then legal values match the legal range of integer values. For example:
CS_TIMEOUT = 60
If an entry’s value in a C program takes boolean values, then legal values are CS_TRUE and CS_FALSE. For example:
CS_DIAG_TIMEOUT = CS_TRUE
If an entry’s value in a C program takes character strings, then the string is typed directly into the file. For example:
CS_USERNAME = winnie
Some string values must be quoted. If a string contains leading white space, trailing white space, or the semicolon (;) comment character, then the value must be quoted. Also, null string values must be indicated by consecutive quotes. For example:
CS_APPNAME = " Monthly report; Financials "
CS_PASSWORD = ""
Long string values are continued on a subsequent line by escaping the end-of-line with a backslash (\). If an unescaped end-of-line occurs in a quoted string, it is read as part of the value. Finally, literal backslashes in a string value must be doubled.
If a property’s value in a C program takes pointers to a datatype other than CS_CHAR, the property cannot be set through external configuration. The sole exception is the CS_LOCALE keyword, which has the same effect as configuring a CS_LOCALE structure and installing it as a context or connection’s CS_LOC_PROP property. For example, this line would assign the French locale to the context or connection:
CS_LOCALE = french
If a keyword occurs twice in a section, only the first definition is used.
A section can include the keywords in another section using this syntax:
[section name] include = previous section name
... more settings ...
All settings defined under an included section name are defined in a section that includes that section. An included setting is always replaced by an explicit setting in the including section. For example, the Finance section, below, defines CS_TIMEOUT as 30. The included setting from the DEFAULT section is replaced by an explicit setting:
[DEFAULT]
CS_TIMEOUT = 45
[Finance]
include = DEFAULT
CS_TIMEOUT = 30
