
            Config v1.0

           by Adam Dawes

           25th May 1996



Introduction
~~~~~~~~~~~~

Well, I hate Windows as much as the next man, but occasionally I stumble
across a good idea hidden away within the operating system.

There are a couple of functions buried in there for reading and writing
configuration files, and they actually make things very easy. I decided I'd
had enough of messing around with config files on my Amiga, so I've ported
the functions to Amiga C.

The idea is that the configuration files take a definitive structure which
the Config functions can understand. Each config file is split in to a
number of "Sections" (which are stored in the config file as a keyword
inside square brackets). In each of these sections are a number of "Items",
each of which contains an actual data item. The items are local to the
section that contains them, so it's perfectly legal to use one item name in
several sections, they'll all be treated separately.

The beauty behind the functions is you don't have to worry about creating
files or scanning through them. Even when it comes to reading data, you
don't have to care if the config file exists or not as you provide a
default value to use if the file/section/item cannot be located.
Everything is automated within the Config functions.




Using the Config Functions
~~~~~~~~~~~~~~~~~~~~~~~~~~

There are 4 public functions within the Config source code, as follows:


   WriteConfig()
   WriteConfigNumber()
   ReadConfig()
   ReadConfigNumber()


Each of these functions is detailed below.



Function:
    int WriteConfig(char *filename, char *section, char *item, char *data);

Parameters:
    filename = the name of the config file (eg, "S:MyConfig.cfg")
    section = the name of the section to add config data to
    item = the item within the section to contain the config data
    data = the actual data itself

Details:
    You do not need to worry about anything at all when calling this
    function. If the config file specified doesn't exist, it'll be
    created for you. If the section specified doesn't exist, that will
    be created. If the item doesn't exist, it'll be added to the
    appropriate section; if it does exist, the previous data will be
    replaced by the new data.

    If all goes well, the function will return CFG_WRITE_SUCCESS. If
    something goes wrong (run out of memory, or the specified file
    cannot be written to), CFG_WRITE_FAIL will be returned.



Function:
    int WriteConfigNumber(char *filename, char *section, char *item, long data);

Parameters:
    filename = the name of the config file
    section = the name of the section to add config data to
    item = the item within the section to contain the config data
    data = a long integer to be written to the file

Details:
    This function is more useful when reading/writing numbers to the config
    file. It is actually only a small front-end to the WriteConfig()
    function. If you need to write numbers that aren't longs (floats, for
    instance), just make a copy of the WriteConfigNumber() function in to
    your own code, and change the datatypes around as necessary. You can
    then copy and alter ReadConfigNumber() appropriately as well to read
    the data back in.

    As before, this will return CFG_WRITE_SUCCESS is all is well, or
    CFG_WRITE_FAIL if something goes wrong.



Function:
    int ReadConfig(char *filename, char *section, char *item, char *buffer,
                   int bufsize, char *def);

Parameters:
    filename = the name of the config file
    section = the name of the section to read config data from
    item = the item within the section that contains the config data
    buffer = an empty character array ready to receive the config data
    bufsize = the maximum length of chars than can be written to the buffer
    def = a string that will be written to the buffer if the requested
          config item cannot be found

Details:
    Use ReadConfig() to get data back from your config file. It will look
    for the specified section/item in the specified file.

    If the file cannot be opened, the section cannot be located, or the
    item within the section is not found, the function will copy the
    default string to your buffer, and return CFG_READ_SUCCESS. Therefore,
    you don't need to care at all about whether the config file exists.
    Just tell the function what you want to receive if your requested data
    cannot be found.

    The function will return CFG_READ_SUCCESS if everything is ok, or
    CFG_READ_FAIL if the string to be returned is larger than the supplied
    buffer.



Function:
    long ReadConfigNumber(char *filename, char *section, char *item,
         long def);

Parameters:
    filename = the name of the config file
    section = the name of the section to read config data from
    item = the item within the section that contains the config data
    def = a long value that will be returned if the requested config item
          cannot be found

Details:

    As with WriteConfigNumber(), this is just a front end to the
    ReadConfig() function.

    This will return as a long value, the number located in the data item
    specified. If the data item cannot be found, your default value will be
    returned instead.

    This function is assumed never to fail. The string buffer is quite
    large enough to hold a 32-bit value, so no errors should result using
    this function.




Requirements
~~~~~~~~~~~~

Obviously, you will need a C compiler to make any use of these functions.
Config was written using DICE V2, but should work with any Amiga C
compiler.

The sourcecode is not currently portable to other platforms, as it uses the
list handling functions found in the exec.library.

The code should work with any version of the Amiga operating system, past
present and future.




Legal Stuff
~~~~~~~~~~~

Config and its associated files are not public domain. They may be
distributed freely as long as no unreasonable charge is imposed. They may
not be included within any commercial package without express written
permission from the author; the exceptions from this are the AmiNet CDs and
Fred Fish's collections. Config may only be distributed if all files
contained within the original archive are present.

I do not accept responsibility for any damage done to your system or data
lost, directly or indirectly, as a result from using this program or any of
its associated files. You use the program entirely at your own risk. Of
course if you *do* experience problems then I'll do what I can to sort them
out, and please let me know so that I can try to cure them in a future
release.




History
~~~~~~~

    v1.0 (25.5.96)

        Initial release.



Contacting the author
~~~~~~~~~~~~~~~~~~~~~

Please do write to me if you like Config or if you have any problems with
it or suggestions for a new version. I can't promise to reply quickly if
you write via snail-mail, but I will do my best to always reply to email
messages. I can be contacted at:

  InterNet
     Adam@beachyhd.demon.co.uk

     http://www.pavilion.co.uk/rda/adam


  FidoNet
     Adam Dawes@2:441/93.5


  SnailMail
     Adam Dawes
     47 Friar Road
     Brighton
     BN1 6NH
     England

