                              Managing INI Files

                                 "What is fame? An empty bubble; gold?
                                  A transient shining trouble"
                                  Solitude, James Grainger, 1721-1766

     Introduction

          Look at almost any hard drive nowadays and you will find an
     assortment of INI files. Initialization files are text files that
     contain the variables related to an application or other program
     information. Although INI files were popularized by Windows
     applications, they are equally valuable to text-mode applications.

          An INI file is simply a structured text file designed for
     storing strings and numbers. An INI file consists of one or more
     sections with related entries (keynames) within the section.
     Following is an example of an .INI file.

          [DIRECTORIES]
          Programs=C:\ACCOUNTS
          Data=C:\ACCOUNTS\FILES
          Temp=C:\

          [EXTENSIONS]
          Ext1=DBF; database files
          Ext2=DAT
          Ext3=RES

          To take advantage of Gold's INI support, you need to
     understand the various components in an INI file. An INI file is
     composed of sections, keys, values and comments.

The Section

          The name (header) of a section. The enclosing brackets ([ ])
     are required, and the left bracket must be in the leftmost column
     on the screen. In the above example, there are two sections:
     DIRECTORIES and EXTENSIONS.

The Entry Name

          The name of an entry, which can consist of any combination of
     letters and digits. The entry name is usually followed by an '='
     character. In the above example, the DIRECTORIES section has three
     entries: Programs, Data and Temp.

The Value

          The value of each entry, which can be an integer, a string or
     a quoted string. This is the text which lies to the right of the
     equals sign. In the above example, the Programs entry has the value
     C:\ACCOUNTS.

The Comments

          Some entries include brief comments below the header or on the
     same line as an entry. You can include comments anywhere in an .INI
     file by prefacing the comment with a semicolon (;). Notice the
     comment database files in the above example.

INI File Management

          INI files are not renowned for their speed!

          Gold provides two methods of creating and managing INI files.
     If you are only accessing small amounts of data, the standard
     access methods should suffice. However, if the application makes
     repeated calls to an INI file, then the buffered routines will
     offer improved performance.

Standard Routines

          Listed below are the standard routines for saving and loading
     values in an INI file.

     GetIniString( Default, Section, Entry, FName: string ): string;

          Returns a string representing the data found using the defined
          parameters.

     GetIniInt( Default, Section, Entry, FName: string ): integer;

          Returns an integer representing the data found using the
          defined parameters.

     GetIniLong( Default, Section, Entry, FName: string ): longint;

          Returns a longint representing the data found using the
          defined parameters.

     GetIniReal( Default, Section, Entry, FName: string ): real;

          Returns a real value representing the data found using the
          defined parameters.

     WriteIniString( Section, Entry, EntryVal, FName: string ): integer;

          Updates the data defined by the passed parameters if both
          section and entry are found. If either is not located the
          entry and/or section are created accordingly. If the INI file
          does not exist, one will be created. If any value other than
          zero is returned, the write did not take place.

     GetIniSection( var SL: SingleLL; Section, FName: string): integer;

          Reads an entire section into the passed singly linked list. A
          zero value indicates a successful read.

          Most of the above routines contain four common parameters:
     Default, Section, Entry and Filename. The default parameter is what
     the function will return to the application if the section or entry
     is not located. The section parameter is the name of the section,
     without the brackets ([ ]). The entry parameter is the entry name
     of the data to be accessed. It is followed immediately by an equals
     sign (=). The filename parameter is the name of the .INI file to
     search in.

          Refer to the demo files DEMINI1.PAS and DEMINI2.PAS to see the
     standard INI file routines in action.

Buffered Routines

          Each time a standard INI routine (discussed above) is called,
     disk access is required. The buffered routines provide an
     alternative method to improve performance when a lot of INI calls
     are required. This method loads the entire INI file onto the heap,
     where it remains until you remove it.

          Since some INI files can be extremely large, as a developer
     you must concern yourself with the available amount of heap space.
     You should first compare the amount of available heap space to the
     size of the INI file to be loaded.

          Gold uses an internal list for the buffered routines. Remember
     that any change made to an INI entry while using the buffered
     routines must be saved to disk using SaveIni to actually be
     retained.

     LoadIni(LFileName: string): integer;

          Loads an entire INI file into memory using the available heap
          space. A zero value indicates success.

     UnLoadIni;

          Removes the previously loaded INI file from memory releasing
          the heap space.

     PutIniString( Section, Entry, EntryVal:string ): integer;

          Modifies the value of the specfied entry.

     SaveIni( LFileName: pathstr;OverWrite:boolean ): integer;

          Writes the contents of the INI buffer back to disk for future
          use. If OverWrite is set to false, a backup (.BAK) of the INI
          file is created prior to the actual saving of the data being
          held in memory, otherwise the original file is overwritten.

     ReadIniString( Default,Section,Entry:string ): string;

          Returns a string representing the data found by the defined
          parameters.

     ReadIniInt( Default,Section,Entry:string ): integer;

          Returns an integer value representing the data found using the
          defined parameters.

     ReadIniLong( Default,Section,Entry:string ): longint;

          Returns a longint value representing the data found using the
          defined parameters.

     ReadIniReal( Default,Section,Entry:string ): real;

          Returns a real value representing the data found using the
          defined parameters.

     ReadIniSection( var SL:SingleLL; Section:string): integer;

          Loads an entire section into the specified list. A zero value
          indicates a successful read.

Error Codes

     LastIniError: integer;

          Returns the last error generated by the INI unit.

INI Colors

          Just to resolve your concerns, there are no colors to be
     supported in the INI unit.

