# 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.

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 210 (1024)

  mb, mib

    A multiplier of 220

  gb, gib

    A multiplier of 230

  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.