xHarbour Reference Documentation > Function Reference

HB_ReadIni()

Reads an INI file from disk.

Syntax

HB_ReadIni( <cFileName>  , ;
           [<lCaseSens>] , ;
           [<cDelimiter>], ;
           [<lAutoMain>]   ) --> hIniData

Arguments

<cFileName>

This is a character string holding the name of the INI file to open. It must include path and file extension. If the path is omitted from <cFileName>, the file is searched in the current directory.

<lCaseSens>

This parameter defaults to .T. (true) causing the function to return a case sensitive Hash(). When set to .F. (false), the returned hash is case insensitive.

<cDelimiter>

This is a character string holding the delimiter(s) recognized as separating character between key and value within the INI file. Bydefault, the characters ":", "=" and "|" are recognized.

<lAutoMain>

This parameter defaults to .T. (true) so that a [MAIN] section is automatically added to the resulting hash. All key/value pairs appearing at the beginning of the INI file outside a [section] are assigned to the hash key "MAIN".

Return

The function returns two dimensional hash holding sections and key/value pairs of each section inthe INI file. When the file does not exist, the return value is NIL.

Description

Function HB_ReadIni() reads an INI file and loads the data into a two dimensional Hash, which is returned. INI files are commonly used for configuration data of applications. They are comfortable to use since they can be created and/or changed with a regular ASCII editor.

The basic feature of an INI file is that it organizes data in key/value pairs which can be divided into sections:

   ; comment line: this is the auto-MAIN section

   mainKey1=mainvalue1 # inline comment
   mainKey2=mainvalue2

   [SECTION1]
   sectionKey1=valueA
   sectionKey2=valueB

   [SECTION2]
   sectionKey1=valueC
   sectionKey2=valueD

INI file sections are named. The names are enclosed in square brackets in the INI file and are used as keys in the Hash returnd by HB_ReadIni(). The value of each [section] key is, again, a hash, making the return value a two-dimensional hash. The hashes in the second dimension contain the key=value pairs of each [section] of the INI file.

The example above shows two key=value entries at the beginning of the INI file which are not part of a named [section]. By default, HB_ReadIni() assigns such entries to the hash key named "MAIN".

Info

See also:	FOpen(), FRead(), Hash(), HB_SetIniComment(), HB_WriteIni()
Category:	File functions , xHarbour extensions
Source:	rtl\hbini.prg
LIB:	xhb.lib
DLL:	xhbdll.dll

Example

// The example uses the INI file discussed in the function
// description and creates from it a case sensitive Hash.
// The key values of different sections are displayed.

   PROCEDURE Main
      LOCAL hIniData := HB_ReadIni( "test.ini" )

      ? Valtype( hIniData["MAIN"] )         // result: H
      ? Valtype( hIniData["SECTION1"] )     // result: H

      ? hIniData["MAIN"]["mainKey2"]        // result: mainvalue2

      ? hIniData["SECTION1"]["sectionKey1"] // result: valueA
      ? hIniData["SECTION1"]["sectionKey2"] // result: valueB

      ? hIniData["SECTION2"]["sectionKey1"] // result: valueC
      ? hIniData["SECTION2"]["sectionKey2"] // result: valueD

   RETURN