<p>This page refers to the zmapConfig directory as of 09 Dec 2009.</p>
<p>
Refer to <ahref="Design_notes/notes/config.txt">config.txt</a> for some discussion of the previous code which was distributed amongst the <b>zmapConfig/</b> and <b>zmapUtils/</b> and <b>zmapFeature/</b> directories, including some not very obvious files (eg zmapStyleUtils.c), and also included the previous version of code which was not used.
<br>
For this version all the config handling code will resides in </b>zmapConfig/</b>.
</p>
See also <ahref="Design_notes/notes/old_styles.shtml">styles documentation</a>.</p>
</fieldset>
<fieldset><legend>Reading Files</legend>
<p>
The user may specify a config file by a command line argument but if not a default file <b>~/.ZMap/ZMap</b> will be used. ZMap may also refer to system and application specific config files if installed (<b>/etc/ZMap</b> and <b>$ZMAP_HOME/ZMap</b>). If so then the data in the system and application files will take precedence.</p>
<p>The ZMap file may contain stanzas and keys as defined by the <b>GLib GKeyFile</b> module. Multiple instances of a stanza will be combined and if multiple instances of a key exist thent last one will take precedence.</p>
<p>
Any number of extra config files may be refered to by keys and any nuumber of these may be loaded on request by the application - by default only the main config file will be processed.by ZMap's main thread.
</p>
<p>
In cases where multiple instances if a single stanza type are required (eg for multiple data sources) then either a list of stanzas will be specified by a key, or the stanza names will be prefixed by the stanza type (eg [source:wublastx]). ZMap will get a list of all stanzas and process each appropriately.
</p>
<p>A name key will be added to all stanzas if not present.</p>
Currently only the <b>[Blixem]</b> stanza needs to be updated by ZMap, but if so the entire ZMap config file will be written. Note that this applies to the 'user config' only, not the system or application files (if present).</p>
<p>
There are modules in the code that edit a memory copy of config data. Although they use the config module they are not part of it and are not included in config code.
</p>
</fieldset>
<fieldset><legend>Stanzas and Keys</legend>
<p>
Here it is assumed that the reader is familiar with the <ahref="Design_notes/notes/style_config.shtml">existing scheme</a> and some modifications have been perpetrated:
</p>
<p>
In the [source] type stanzas options are available to define featuresets and styles. Coincidentally at present these are identical and style names could be defaulted to be the same as the featureset name - this makes sense as when a source provides featuresets data it would be expected to supply styles as part of this. ACEDB for example can suppy styles and link these to featuresets, other sources not neccessarily so.
</p>
<p>
Styles may be defined in a config file which can be specified in the <b>[ZMap]</b> stanza with the key <b>styles-file=filename</b>, and only one will be allowed.
Individual source stanzas will not have a styles-file key.</p>
<p>
Styles may be defined in a source stanza as before - it is inteneded that DAS servers will be able to request styles in future - but sources are not required to process this. ACEDB servers have styles defined by thier featuresets and do not use styles config. File and Pipe servers do not use styles config as they assume that featuresets are displayed using a style of the same name, however they will honour the list of styles if given.</p>
<p>
Options to specify ambiguous stanzas have been removed eg [sources], [source] etc.
</p>
<p>
Sources must be listed in <b>[ZMap]</b> eg <b>sources=one ; two ;.... </b> and the individual sources defined in a stanza each, as named.
In terms of policy <b>[source]</b> is no longer allowed ... but the code is still there, one <b>[source]</b> stanza will still work.
</p>
</fieldset>
<fieldset><legend>Application interface</legend>
<p>
Each module that uses configuration data will read in the config file(s) and create its own copy of config data each time that it initialises - for example creating a new window will result in up to date setting beings used for that window. Or the main thread may create new data sources when a new ZMap is created (any existing ZMap will continue unchanged).
</p>
<p>
Application code can choose to read in extra files (specified by a config key or hard-coded), and this function will be provided by the zmapConfig module. Regardless of how many files are read for any given config data object all files and stanzas will be merged into a single interface.
</p>
<p>
The files themselves are read into a blank <b>GKeyFile</b> data structure and stanza names and key values accessed by querying this GLib interface. Each stanza has an associated data structure defined by ZMap which is initialised by the config code and key data overlayed onto this.
After reading in config file and creating these data structures the GKeyFile data may be freed.
</p>
<p>
Key and stanza names/ strings are defined in a single file: <b>include/ZMap/zmapConfigStrings.h</b>. The file <b>zmapConfig/ZMapConfigLoader.c</b> has all the code for constructing stanzas. It was intended to scatter stanza specific data to modules that used it but this proved impractical due to the need for several different modules to access the same stanzas.
</p>
<p>All the config handling code is now in zmapConfig/ and there are 15 source files the use it (grep for ConfigIni.h to find them).
</p>
</fieldset>
<fieldset><legend>User guide</legend>
(This needs to be updated)
</fieldset>
<fieldset><legend>Technical details</legend>
<h3>Source files, config data structures and related functions</h3>
<tr><td>zmapConfig/zmapConfigDir_P.h </td><td> private header for ConfigDir</td></tr>
<tr><td>zmapConfig/zmapConfigIni_P.h </td><td> private header for ConfigIni</td></tr>
</tbody>
</table>
<h3>Data Structures</h3>
<p>Internal to the zmapConfig module there is a <b>ZMapConfigIni</b> struct which is simply a list of <b>GKeyFiles</b>. Functions which deal with this are in the files <b>zmapConfigFile.c</b> and <b>zmapConfigKey.c</b> and are generally named -ConfigIniThing();
</p><p>
External (ie visible from outside) to the zmapConfig module there is a <b>ZMapConfigIniContext</b> struct which includes a <b>ZMapConfigIni</b> and a few other items. Pretty much all of the global functions in zmapConfig take an -IniContext structure, pass on the -Ini struct and ignore all the rest,
</p><p>
<b>zmapConfigIni.c</b> and <b>zmapConfigLoader.c</b> hold the external functions, External functions are called -IniContextThing()<br>
<b>zmapConfigDir.c</b> was intended as internal but turns out to have some functions called from startup code.
