INtime SDK Help
Config File library
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.
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.
rtboot.ini controls the boot process and is located in root directory. The config directory holds the memory settings for all nodes in nodeboot.sys as well the PCI configuration for all PCI devices in config.pci. Every node has an own config subdirectory with its name (default NodeA is the primary one). During creation of a new node, it is recommended to copy all files from /config/template/network to /config/<nodename>/etc to have all network configuration files available with its defaults.
The node specific configuration files are rtload.sys which holds the autoload application and rtconfig.sys which contains settings for the kernel loader. All network related settings are stored in subdirectory etc of each node. 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 |
The configuration files in format [section] parameter are used for most settings in DRTOS. All you need to access the information in the files, is to read the parameter from a section, so it is always a pair, which is needed to access information. The parameters can be strings or DWORD values. The files in this format are rtboot.ini, nodeboot.sys 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 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 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 |
Auto load parameters define what applications are loaded automatically when the INtime kernel starts and are node specific. The set of auto-load applications can be extended and reduced. The function names include the term ‘Load’. For each application a number of parameters can be manipulated. The file is named rtload.sys and is stored in the node specific config /config/<nodename>.
The file contains one or more lines, each containing a path, arguments, options and comment. The comment is optional; a line may also be empty or contain a comment only.
A path is a combination of characters not including space or the comment character (;). If it is followed by arguments or options, at least one space must be present.
Arguments are enclosed in quotes ("). Within the quotes, the quotes character cannot be used. If an arguments string contains a comment character (;), that character is assumed to be part of the arguments. If an arguments string is followed by options, at least a single space must be present.
Options start with a minus sign (-) and extend up to the end of the line or to the comment character (;).
A comment starts with a comment character (;) and continues up to the end of the line. A comment starting with ";--disabled--"causes that line to be disabled; removing the comment enables the line.
The functions CfgLoadAppend, CfgLoadGet and CfgLoadSet are deprecated and replaced by CfgLoadAppend1, CfgLoadGet1 and CfgLoadSet1. The deprecated functions do not take care on disabled entries and thus should not any longer be used.
| To . . . | Use this system call . . . |
|---|---|
| Update one entry in a file | CfgLoadSet1 |
| Append an entry to end of file | CfgLoadAppend1 |
| Read entry from file | CfgLoadGet1 |
| Remove an entry from file | CfgLoadRemove |
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:
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.