This section describes the Config File (cfgfile) library, a set of functions that a application can use to get and set INtime parameters on an INtime Distributed RTOS system. It is a programmable alternative to the built-in webserver configuration application.

Introduction

The parameters for INtime Distributed RTOS nodes are spread out throughout several files on local HDD. There are many dependencies between parameters and in many cases, changing a parameter requires restarting the INtime kernel or the complete system.

The purpose of the cfglib is the access of config file information on DRTOS systems. There are 3 different types of files available for network, autoloader and sections based settings. To reduce dependency of these different formats, a more generic interface is implemented for file access. All files could be read and written by normal file access functions as well, but the cfglib offers some basic parsing and writing mechanisms, to make things easier.

Configuration files are ASCII text files, using CR/LF character pairs as line terminator.

File organization

rtboot.ini controls the boot process and is located in the /boot directory. Every node has a /config subdirectory with its name (default NodeA is the primary node). The rtconfig.sys holds the configuration settings for the kernel loader for that node. The primary node also performs system configurations like memory and starting other nodes.

The node specific startup script is startup.rsc. Use this script for automatically start applications and perform other tasks after a node is running.

All network related settings are stored in the subdirectory etc of each node. When a new node is created, it is recommended to copy all files from /config/template/network to /config/<nodename>/etc to have all network configuration files available with the defaults. See also advanced configuration settings for some more details.

To . . .	Use this system call . . .
Open a configuration file of given type	CfgFileOpen
Check for non saved changes	CfgFileIsDirty
Save data to file	CfgFileSave
Release a file handle	CfgFileClose
Convert a string to integer	CfgStringToDWORD
Get a textual description for an error number	CfgErrorShort

Sections files

The configuration files in format [section] parameter are used for most settings in DRTOS. To access the information in the files, read the parameter from a section. Parameters and values are always in a pair. The parameters can be strings or DWORD values. The files in this format are rtboot.ini and rtconfig.sys.

Every line may end with a comment, starting with a semicolon. The text form the semicolon to the end of the line is ignored. A line containing a comment only is removed on writing a configuration file; also an empty line is removed on writing. White space between elements is removed on writing. A section consists of a header (surrounded by square brackets [header]), followed by zer or more parameter lines. A parameter line contains a parameter name, an equal sign and a value (possibly followed by a comment). A parameter is either a string or a numerical value, it may not be empty. A section or parameter name may only contain letters, digits and underscores and must contain at least one character; the maximum number of characters is 64. When comparing a name, case is ignored. Within a section file, all section names must be unique. Within a section, all parameter names must be unique.

A numerical value can be written as:

• a series of decimal digits (‘0’ to ‘9’)
• the characters ‘0’ and ‘x’ (lower or upper case) followed by one or more hexadecimal digits (‘0’ to ‘9’, ‘a’ to ‘f’ in lower or upper case)
• a decimal digit (‘0’ to ‘9’), followed by zero or more hexadecimal digits, followed by a ‘h’ (lower or upper case).

A string value is written as a series of characters (may be empty) enclosed in a pair of single quotes (‘) or enclosed in a pair of double quotes (“). A string itself may not contain a quote. The maximum number of characters in a string is 256 (not including the quotes).

To . . .	Use this system call . . .
Add section at end of file	CfgSectionAdd
Remove a section	CfgSectionDelete
Get all sections	CfgSectionEnumerate
Set the value for one entry	CfgParSetDWORD CfgParSetString CfgParSetComment
Add entry at end of section	CfgParAddDWORD CfgParAddString
Get value for a parameter	CfgParGetDWORD CfgParGetString CfgParGetComment
Remove a parameter	CfgParDelete
Get all parameters from one section	CfgParEnumerate

Network parameters (Net and Nic)

Network parameters control the use of network hardware and TCP/IP options and are node specific. The function names include the term ‘Net’ and the files are stored relative a the node directory. These files are found in /config/<nodename>/etc per node.

The files contain one or more lines, each containing a keyword followed by a separator and a value, possible followed by more text. the separator can be a space or an equal sign, but is the same for a whole file.

To . . .	Use this system call . . .
Set the value for one entry	CfgNetSetString
Add entry at end of file	CfgNetAppend
Get value for a setting	CfgNetGetString
Remove all settings of one type	CfgNetRemoveAll
Clear content of file	CfgNetClear

Restart handling

Changing a parameter may require restarting the INtime kernel or the whole system. The library does not track such requirements and thus it is the responsibility of the programmer to restart a node or the system after parameters are changed. These could be done by ShutdownRtHost or StopLocalRtApplicationNode/StartLocalRtApplicationNode . The general rules are:

• Changing system parameters related to boot require a system restart (rtboot.ini).
• Changing memory configuration require a system restart.
• Changing settings on the primary node requires a system restart, as the primary node can not be restarted independently (default NodeA).
• Changing Node specific settings other than memory require a restart of that node.

Using the cfgfile library

All functions defined below require including the header file cfgfile.h and linking the library cfgfile.lib. At execution time, the file cfgfile.rsl is required. The functions are described in alphabetical order.

If a function in this library is called by more than one thread at a time, the client should take care of mutual exclusion; none of these functions are safe for multi-threading.

For function parameters, the notation (in) means that value is an input parameter; (out) means the parameter is a pointer and the function may write into the variable pointed to; (in/out) means the parameter is a pointer to a variable that must have been set before the call and that may be written to by the function.

Some functions return a string by setting a pointer of which the caller passes the address; such a string is contained in an internal cfgfile buffer and is only valid until the next cfgfile call.

The file functions attempt to cache file information so that no excessive reading of a file is necessary. Since the application should know when a file has changed, it should close a file and reopen it if necessary.

Note that after opening a file, the actual file is closed, but internal resources are kept. At any moment, no more than 32 files can be open. All non file functions operate on memory buffers that CfgFileOpen creates and do not access the file itself.