Home

	Expand Search

Open Client Client-Library/C Reference Manual

Chapter 2 Topics

Using the runtime configuration file

Using the runtime configuration file

By default, Client-Library reads the Open Client/Server runtime configuration file to set runtime values for the following:

• Property values (normally set with ct_config or ct_con_props calls)

• Server option values (normally set with ct_options calls after a connection is opened)

• Server capabilities (normally set with ct_capability calls before a connection is opened)

• Debugging options (normally set with ct_debug calls)

Applications that read the configuration file to apply these settings eliminate several calls to ct_con_props or the other routines mentioned above. Another benefit is that the application's runtime settings are changed without recompiling code.

If there is an external Sybase configuration file, add these sections to enable bcp and isql: [BCP][CTISQL]

Enabling debugging

Table 2-33 lists the keywords for configuring the debugging options for a connection.

CS_DEBUG specifies the data to be written to the file CS_DBG_FILE. Its value can be a list of flags that correspond to the bitmasks for ct_debug's flag parameter. For meanings of these debug flags, see the reference page for ct_debug.

The possible flags are:

• CS_DBG_ALL

• CS_DBG_API_LOGCALL

• CS_DBG_API_STATES

• CS_DBG_ASYNC

• CS_DBG_DIAG

• CS_DBG_ERROR

• CS_DBG_MEM

• CS_DBG_NETWORK

• CS_DBG_PROTOCOL

• CS_DBG_PROTOCOL_STATES

Enabling external configuration

The following properties control the use of the Open Client/Server runtime configuration file:

• CS_EXTERNAL_CONFIG - when this property is CS_TRUE at the context level, ct_init reads default Client-Library context property values from the Open Client/Server runtime configuration file.

  At the context level, CS_EXTERNAL_CONFIG defaults to CS_TRUE if the default Open Client/Server runtime configuration file exists, and to CS_FALSE otherwise. The name of the external configuration file is determined by the CS_CONFIG_FILE property. Applications can override the context-level default by calling cs_config.

  At the connection level, allocated connection structures inherit CS_EXTERNAL_CONFIG from the parent context. If CS_EXTERNAL_CONFIG is CS_TRUE at the connection level, ct_connect reads default connection properties, capabilities, server options, and debugging options from the Open Client/Server runtime configuration file.

• CS_CONFIG_FILE - specifies the name and location of the Open Client/Server runtime configuration file. CS_CONFIG_FILE is set at the context level with cs_config or at the connection level with ct_con_props. The default value is NULL, which means that a platform-specific default file will be used:

  • On UNIX platforms, the default file is $SYBASE/$SYBASE_OCS/config/ocs.cfg where $SYBASE is the path to the Sybase installation directory, specified in the SYBASE environment variable, and $SYBASE_OCS is the Open Client/Server subdirectory, specified in the SYBASE_OCS environment variable.

  • On Windows platforms, the default file is %SYBASE%\%SYBASE_OCS%\ocs.cfg, where %SYBASE% is the path to the Sybase installation directory, specified in the SYBASE environment variable, and %SYBASE_OCS% is the Open Client/Server subdirectory, specified in the SYBASE_OCS environment variable.

    For other platforms, see the Open Client/Server Configuration Guide for the name of the default Open Client/Server runtime configuration file.

• CS_CONFIG_BY_SERVERNAME - controls whether ct_connect uses the value of the connection's CS_APPNAME property or the server name as the file section name. By default, the value of CS_APPNAME is used. CS_CONFIG_BY_SERVERNAME is set at the connection level with ct_con_props.

  For example, if external configuration is enabled for the connection, the application name is "Monthly Report," and the value of server_name is "FinancialDB," then:

  • If CS_CONFIG_BY_SERVERNAME is CS_FALSE, ct_connect looks for a section labeled [Monthly Report].

  • If CS_CONFIG_BY_SERVERNAME is CS_TRUE, ct_connect looks for a section name labeled [FinancialDB].

    CS_SERVERNAME cannot be changed in the external configuration file unless CS_CONFIG_BY_SERVERNAME is set to CS_TRUE.

  The server and application names are changed by the configuration section. This allows an administrator to override a server or application name that is hard-coded in the application. For example, if the application is set up to read the section name FinancialDB, the section could contain the following:

  [FinancialDB]

   CS_APPNAME = "Monthly Financial Report"

   CS_SERVERNAME = "Dev_FinancialDB" ; redirect to

                                     ; development

                                     ; server

• CS_APPNAME - at the context level, specifies from which section of the file to read values. Applications call cs_config to set CS_APPNAME at the context level. If the application does not set CS_APPNAME for the context structure, ct_init looks for a section labeled [DEFAULT]. At the connection level, ct_connect reads the file section indicated by CS_APPNAME when external configuration is enabled and the CS_CONFIG_BY_SERVERNAME property has its default value of CS_FALSE.

Open Client/Server runtime configuration file syntax

The Open Client/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.

Legal values adhere to the following rules:

• If an item'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 item'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 item'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 item'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 via 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

Runtime configuration file keywords

The tables below contain the legal keywords for configuring Client-Library's runtime behavior and the recognized values for each.

The following table describes the keywords for configuring a context or a connection's locale. These settings replace calls necessary to set the CS_LOC_PROP property for a context or connection.

When the application calls them, ct_init and ct_connect each read a section of the configuration file if the application has requested external configuration.

If a context property is set when ct_init reads a section, then any calls to ct_con_props to set the same property override the configured setting.

If a property is set when ct_connect reads a section, then calls to ct_con_props to set the same property either:

• Get replaced by the file's value if the ct_con_props call occurs before ct_connect, or

• Replace the file's value if the ct_con_props call occurs after ct_connect.

For example, values for CS_USERNAME and CS_PASSWORD that are set in a configuration section always override hard-coded values in the application code. This is true because the application must set these properties before ct_connect is called.

The following table lists the keywords that set context or connection properties. For descriptions of what each property controls, see "Properties".

Table 2-35 lists the keywords for configuring the server options for a connection.

Application calls to ct_options always override equivalent settings in the configuration file.

The keywords for setting server options are listed below. For descriptions of what each option controls, see "Options".

Only response capabilities are configured externally. If response capabilities are read from the file, they replace any response capabilities set by application calls to ct_capability for the connection.

The following table lists the keywords for configuring the server capabilities for a connection. For descriptions of what each capability controls, see the reference page for ct_capability.

The following table lists the keywords for configuring the debugging options for a connection.

The CS_DBG_FILE keyword specifies the name of the file to which Client-Library writes text-format debug information. Client-Library only records the debug information that is requested.

Debug information is requested with the other keywords. These correspond to the bitmasks for the ct_debug flag parameter. For meanings of these debug flags, see the reference page for ct_debug.

CS_DEBUG specifies the data to be written to the file CS_DBG_FILE. Its value can be a list of flags that correspond to the bitmasks for ct_debug's flag parameter. For meanings of these debug flags, see the reference page for ct_debug in the Open Client Client-Library/C Reference Manual.

The possible flags are:

• CS_DBG_ALL

• CS_DBG_API_LOGCALL

• CS_DBG_API_STATES

• CS_DBG_ASYNC

• CS_DBG_DIAG

• CS_DBG_ERROR

• CS_DBG_MEM

• CS_DBG_NETWORK

• CS_DBG_PROTOCOL

• CS_DBG_PROTOCOL_STATES