Configuration

The DC-API library uses a configuration file to control its operations. The location of the config file must be specified by the master application when it calls the DC_initMaster() function.

Note

Individual work units may also use a config file that has a slightly different format than the master's config file. Work unit config files however are usually generated by the DC-API library on the master side so applications should not be concerned about it.

Configuration file format

The DC-API configuration file contains key-value pairs organized into groups. The full syntax description can be found in the Desktop Entry Specification, but we also give a brief explanation below.

Lines starting with # are considered comments and are ignored. Groups are started by a line containing the group's name between brackets ([ and ]). Groups are terminated by the start of an other group or by the end of the file.

A group may contain a list of key = value assignments, each in a separate line. White space arount the = character is ignored. Note that the DC-API do not use the localized string feature of the Desktop Entry Specification.

Configuration values can be of 4 types:

Simple strings. According to the format specification, they must be UTF-8 encoded.
Integer values.

Floating point values. For both integer and floating point values, the following suffixes are recognized:

kb, kib	A multiplier of 2¹⁰ (1024)
mb, mib	A multiplier of 2²⁰
gb, gib	A multiplier of 2³⁰
min	A multiplier of 60
h, hour	A multiplier of 3600
day	A multiplier of 86400

Boolean values. The strings true, yes and on means true, the strings false, no and off are considered false.

Generic configuration items

The DC-API configuration file should contain a group called [Master] that defines global configuration options. There may be also groups called [Client-CLIENTNAME] where CLIENTNAME is the logical name of a client application the master wishes to start (the same string that is passed to the DC_createWU() function).

Default values for client-specific configuration options may also be specified in the [Master] group. If the same key is also present in a client-specific group, the client-specific value will override the value in the [Master] group.

Configuration values for the master application

The following entries can be specified in the [Master] group. Grid backends may require and/or allow further items; refer to the backend-specific documentation.

WorkingDirectory	REQUIRED. The working directory of the master application. The value must be an absolute path. The DC-API sets the master's current directory to the value specified here when the `DC_initMaster()` function is called.
LogLevel	OPTIONAL. Specifies the verbosity of log messages generated by the DC-API or by the master application if it uses the `DC_log()` or `DC_vlog()` functions. The allowed values in the order of increasing priority are `Debug`, `Info`, `Notice`, `Warning`, `Error` and `Critical`, the default being `Notice`.
LogFile	OPTIONAL. Specifies the name of the file where log messages should be written to. If not specified, log messages are sent to the application's standard output.

Configuration values individual work units

LogLevel	OPTIONAL. Specifies the verbosity of log messages generated by the DC-API or by the client application if it uses the `DC_log()` or `DC_vlog()` functions. The allowed values in the order of increasing priority are `Debug`, `Info`, `Notice`, `Warning`, `Error` and `Critical`, the default being `Notice`.
LogFile	OPTIONAL. Specifies the name of the file where log messages should be written to. The value must be a relative file name without any path components. The default value is determined by the DC-API when it creates the work unit and generally it should not be overridden.
SendCfgKeys	OPTIONAL. Specifies a `;`-separated list of configuration keys that should be sent to the client application when a work unit is created. `LogLevel` and `LogFile` are always included so those should not be listed. The client application may use the `DC_getCfgStr()`, `DC_getCfgInt()`, and `DC_getCfgBool()` functions to access the values of the keys specified by `SendCfgKeys`
DefaultPriority	OPTIONAL. Specifies the default priority of the work unit. The priority is an integer number; its allowed range and exact meaning depends on the grid backend. The default value is 0.