xHarbour Reference Documentation > Function Reference

HB_WriteIni()

Creates an INI file and writes hash data to it.

Syntax

HB_WriteIni( <cFileName>      , ;
             <hIniData>       , ;
             [<cCommentBegin>], ;
             [<cCommentEnd>]  , ;
             [<lAutoMain>]      ) --> lSuccess

Arguments

<cFileName>

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

<hIniData>

This is a two-dimensional Hash() holding the section data and key/value pairs to store in the INI file.

<cCommentBegin>

This is an optional a character string which is written as a comment at the beginning of the INI file.

<cCommentEnd>

This is an optional a character string which is written as a comment at the end of the INI file.

<lAutoMain>

The parameter defaults to .T. (true), causing all entries in the "MAIN" hash key of <cIniData> be written at the beginning of the INI file without a [section] entry. When set to .F. (false), all data of <hIniData> are divided into [sections], including a possible the [MAIN] section.

Return

The function returns a logical value indicating a successful operation.

Description

Function HB_WriteIni() writes the data held in <hIniData> to the INI file <cFileName>. If the file exists already, it is overwritten. When the file cannot be created, the return value is .F. (false) and function FError() can be called to identify the cause of failure.

INI files provide a convenient way for storing configuration data of an application. They are divided into named [sections] holding key/value pairs. An example for an INI file is this:

; Start comment
Desc = Application program
Ver = Version 2.2

[Files]
DB1=Customer.dbf
DB2=Sales.dbf

[Path]
CONFIG=\apps\conf\
DATA=\apps\data\
; End comment

This INI file contains six key/value pairs, divided into three [sections]. The first section is unnamed. It has the default name "MAIN".

Info

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

Example

// The example demonstrates how an INI file can be created
// programmatically by creating a two-dimensional Hash. The
// INI file shown in the function description is created by
// the example.

   PROCEDURE Main
      LOCAL hIni := Hash()

      hIni["MAIN" ]           := Hash()
      hIni["MAIN" ]["Desc" ]  := "Application program"
      hIni["MAIN" ]["Ver"  ]  := "Version 2.2"

      hIni["Path" ]           := Hash()
      hIni["Path" ]["DATA"]   := "\apps\data\"
      hIni["Path" ]["CONFIG"] := "\apps\conf\"

      hIni["Files"]           := Hash()
      hIni["Files"]["DB1"]    := "Customer.dbf"
      hIni["Files"]["DB2"]    := "Sales.dbf"

      HB_WriteIni( "Application.ini", hIni, ;
                   "; Start comment", "; End comment" )

   RETURN