CIniFile

An object of the cIniFile class can be used for reading information avaiable from an INI file.

INI files are often used to store user preferences or setup options for applications.

INI files

In Visual DataFlex you can freely use as many INI files as you require, however the two-level structure of INI files (sections and keys) means that there is often no need to use more than one. Here, for example, is a boot.ini file (usually found in the root directory of the system drive of Windows operating systems):

[boot loader]
timeout=30
default=multi(0)disk(0)rdisk(0)partition(2)\WINDOWS

[operating systems]
multi(0)disk(0)rdisk(0)partition(2)\WINDOWS="Microsoft Windows XP Professional" /fastdetect /NoExecute=OptIn

As you can see, it defines two sections - [boot loader] and [operating systems] - each with different settings within them.

Visual DataFlex Workspace files

Another example are the workspace configuration files used by Visual DataFlex itself (by default named "Config.ws", showing that they don't have to use the .ini extension - see the artice in "See Also" below), which must exist in the same directory the program is run from (usually the "Programs" subdirectory of the workspace). Here is an example:

[Workspace]
Home=..\
AppSrcPath=.\AppSrc
AppHTMLPath=.\AppHtml
BitmapPath=.\Bitmaps
IdeSrcPath=.\IdeSrc
DataPath=.\Data
DDSrcPath=.\DdSrc
HelpPath=.\Help
ProgramPath=.\Programs
FileList=.\Data\Filelist.cfg
Description=MyFirstProject

Here only a single section - [Workspace] - is defined, however the fact that an INI file can have as many sections as it needs means that you can use this very file to set up options for how you want your program to behave.

Note that section names (the ones in the square brackets), key names ("Home", "AppSrcPath", etc.) and key values can all contain spaces (although for my own part I prefer not to use those and depend on camelCase to supply readability).

INI file advantages

The advantage of the INI file approach is that it can make programs configurable for different environments or uses without them having to be recompiled with different settings each time: the program can be made with a set of default values which can then be overridden at run-time by the settings in an INI file. It has the advantage over Registry settings, which perform very much the same function, in that you don't need any special rights on the machine to set it up and make changes to it: you are just working with text files, so security policy issues about who has rights to the Windows Registry, or who can run RegEdit or RegEdit32 do not apply - if you can run Notepad and modify files you can configure your application.

Here is an example where an additional section allowing the configuration of a database location and login has been added:

[Workspace]
Home=..\
AppSrcPath=.\AppSrc
AppHTMLPath=.\AppHtml
BitmapPath=.\Bitmaps
IdeSrcPath=.\IdeSrc
DataPath=.\Data
DDSrcPath=.\DdSrc
HelpPath=.\Help
ProgramPath=.\Programs
FileList=.\Data\Filelist.cfg
Description=MyFirstProject

[Database Login]
Server=big-iron.database-servers.local
Login=itsme
Password=letmein
Database=Accounting
Driver=MSSQLDRV

Combining these factors - the fact that there is probably no need to have more than one INI file, and the fact that Visual DataFlex requres one anyway - means that for most purposes you can just add what you need to the existing workspace configuration file.

Accessing INI files

So how do you access that information in your program?

For most purposes the information in an INI file will only be read at program start-up. This means that (a) the oApplication object is a good place to do such things (see the article in "See Also" below for some guidance on sub-classing the cApplicatiion class) and (b) the cIniFile object need not be retained after it has been used. (Of course you might have different requirements, but here we will assume these are true.)

So... in your oApplication object (perhaps in the "OnCreate" procedure, perhaps elsewhere, such as in "Construct_Object" or "End_Construct_Object") what you need to do is dynamically create a cIniFile object, use it to get the information you want, then destroy it again. You also want to be able to access the workspace configuration file for the application, perhaps without knowing ahead of time what that is actually called.

Here is one way of doing it (note - this code is assumed to be in the oApplication object or a sub-class of the cApplication class; the only place this matters is in the "Set psFileName ..." line, where "Self" will refer to the oApplication object, and where the various properties are held):

  String  sServer sLogin sPW sDrv sDB
  Boolean bLogin
  Handle  hoIni

  // Retrieve your application defaults into local variables
  Get psServer   to sServer
  Get psLogin    to sLogin
  Get psPassword to sPW
  Get psDriver   to sDrv
  Get psDatabase to sDB
  Get pbDoLogin  to bDB

  Get Create U_cIniFile to hoIni    // Create INI file object

  // Make it use the workspace configuration file
  Set psFileName of hoIni to (psWorkspaceWSFile(phoWorkspace(Self)))

  // Read the information
  Move (ReadString(hoIni, "Database Login", "Server",   sServer)) to sServer
  Move (ReadString(hoIni, "Database Login", "Login",    sLogin))  to sLogin
  Move (ReadString(hoIni, "Database Login", "Password", sPW))     to sPW
  Move (ReadString(hoIni, "Database Login", "Driver",   sDrv))    to sDrv
  Move (ReadString(hoIni, "Database Login", "Database", sDB))     to sDB
  Move (ReadString(hoIni, "Database Login", "DoLogin",  bLogin))  to bLogin
     
  Send Destroy of hoIni             // And Destroy it again

  // Set the properties to make the information persistent
  Get psServer   to sServer
  Get psLogin    to sLogin
  Get psPassword to sPW
  Get psDriver   to sDrv
  Get psDatabase to sDB
  Get pbDoLogin  to bDB

The above code will retrieve the values set in the second workspace file example above. Note that in that example, the "DoLogin" value is not present - the "ReadString" method of the cIniFile class lets you supply a default value to use if the setting is not present, and here we have used the bLogin variable, which was set from the pbDoLogin property, and which is then used to set that property again... so the fact that the setting is absent (not "missing" - it is deliberate!) means that the default property remains unchanged.

You could save some code by not retrieving the properties into local variables first, but using the properties as defaults directly:

  Move (ReadString(hoIni, "Database Login", "Server",   psServer(Self)))   to sServer
  Move (ReadString(hoIni, "Database Login", "Login",    psLogin(Self)))    to sLogin
  Move (ReadString(hoIni, "Database Login", "Password", psPassword(Self))) to sPW
  Move (ReadString(hoIni, "Database Login", "Driver",   psDriver(Self)))   to sDrv
  Move (ReadString(hoIni, "Database Login", "Database", psDatabase(Self))) to sDB
  Move (ReadString(hoIni, "Database Login", "DoLogin",  pbDoLogin(Self)))  to bLogin

Or even dispense with the local variables completely:

  Set psServer   to (ReadString(hoIni, "Database Login", "Server",   psServer(Self)))
  Set psLogin    to (ReadString(hoIni, "Database Login", "Login",    psLogin(Self)))
  Set psPassword to (ReadString(hoIni, "Database Login", "Password", psPassword(Self)))
  Set psDriver   to (ReadString(hoIni, "Database Login", "Driver",   psDriver(Self)))
  Set psDatabase to (ReadString(hoIni, "Database Login", "Database", psDatabase(Self)))
  Set pbDoLogin  to (ReadString(hoIni, "Database Login", "DoLogin",  pbDoLogin(Self)))

But some might consider that a bridge too far!

Summary

The cIniFile has other methods as well: it can write as well as read (WriteString, DeleteKey and DeleteSection) and can dynamically determine the contents of the file (ReadSections, ReadSection, SectionExists and KeyExists) - see the VDF Help for full information - but the ReadString method is the one you will need in most circumstances.

See Also

Passing the workspace as a parameter

External references

• http://en.wikipedia.org/wiki/INI_file