Documentation added May 2016
xcall INIX, inifile, opcode, section, item {, value, dftvalue}
INIX.SBX reads/writes from standard "INI" files, which are ordinary text files, typically with a .INI or .CFG extension, which are made up of one or more groups (sections) of item=value pairs as follows:
[section]
item1=value
item2=value
etc.
Because these files can be edited in a standard text editor, and because comment lines beginning with a semicolon may be inserted anywhere, the format is both easy to use and self-documenting. There is no particular limit to the number of items or sections, but each item name within a section must be unique.
Source, samples and related functions can be found in SOSLIB:[907,26].
inifile (String) [in]
File spec of the INI file.
opcode (Num) [in]
Operation to perform:
|
Value |
Meaning |
|
0 |
Read single item=value pair |
|
1 |
Write single item=value pair |
|
2 |
Delete single item=value pair |
|
3 |
Delete complete section |
In addition, you may add either or both of the following options in the ATE environment:
|
Value |
Meaning |
|
+16 |
redirect the operation to the ATE client |
|
+32 |
first sync INIX.SBX from the server to the ATE client |
section (String) [in]
Name of section; without the brackets, case sensitive
item (String) [in]
Name of item to read or write; case sensitive
value (String) [in/out]
For the read operation, the value is returned here. Note that if the item is not found within the specified section, the default value will be returned here, assuming the dftvalue parameter was specified. For the write operation, this will be the value to write.
dftvalue (String) [in]
For the read operation, supplies the default value of the item if the item is not defined
When writing, if the file does not exist, it will be created, and if the specified section does not exist, the section and item will be added to the end of the file. For example:
xcall INIX, "foo.ini", 1, "Favorites", "Beatle", "Ringo"
If the foo.ini file didn't previously exist, then after the above call, it would exist and contain:
[Favorites]
Beatle=Ringo
If we then wrote another item using ...
xcall INIX, "foo.ini", 1, "Favorites", "Position", "On Top"
... the file would be updated to contain:
[Favorites]
Beatle=Ringo
Position=On Top
Note that neither the order of the sections nor the order of the items is significant.
If we then retrieve three values from the file with the following ...
xcall INIX, "foo.ini", 0, "Favorites", "Beatle", fabguy$, "Paul"
xcall INIX, "foo.ini", 0, "preferences", "Position", pos$, "upside down"
xcall INIX, "foo.ini", 0, "Favorites", "Musician", player$, "Leadbelly"
The results would be:
? fabguy$ ! "Ringo"; (default "Paul" ignored)
? pos$ ! "upside down" (no such section "preferences"; use default)
? player$ ! "Leadbelly" (no such item "Musician"; use default)
Attempting to read from a non-existent INI file is equivalent to attempting to retrieve non-existent items; you get back the default value specified in each read operation, or "" if no default specified.
Despite the lack of order or indexing, INIX is quite efficient, particularly at reading, since the file gets cached in memory on the first access. Updates to the file do require the entire file to be rewritten, but this is still reasonably efficient, particularly if the total file size is "reasonable" (say, under 32K or so), and if read operations outnumber writes, as they usually do with these kinds of configuration files.
INIX.SBX in SOSLIB:[907,26] was initially created and contributed to the SOSLIB by Steve Evans. It has since been adopted as a standard A-Shell routine, and is used extensively by many A-Shell modules.