Working with INI files and the user profile directory

OpenScript ››


For some time Microsoft has recommended that product configuration information be stored in the user's profile directory rather than in the product's install directory or the Windows directory. This has become particularly important in versions of Windows newer than Windows XP (which means Windows Vista, 7, 8, etc.) where the operating system actively prevents access to directories other than the current user's profile directory, even if you are running as an administrator.

In ToolBook 9 and higher, all ToolBook product configuration data is stored in the user's profile directory. ToolBook developer's maintaining their own configuration data should aim to do likewise. The situation for ToolBook developers is somewhat alleviated by the fact that the ToolBook authoring environment runs as a signed application in Vista, and so allows write access to directories that would otherwise be blocked. However, in order to be a well behaved Windows application, and in order to work in the ToolBook runtime environment (which is not a signed application), ToolBook developers should aim to store their own configuration data and other data which is written at runtime to the user's profile directory.

ToolBook provides the following new unsupported feature to make that possible. Please note that this feature is unsupported as well as not in the ToolBook help system because it has not yet been fully tested by the Quality Assurance team. However Technical Support is documenting this because it appears to be very stable at this time. This feature will be added in an official capacity in a future release of ToolBook.


OpenScript is a programming language within ToolBook. It is more powerful than the Actions Editor programming language, however it only works within Native ToolBook. OpenScript does not function within a Web Published lesson.

INI File Access

To read and write INI files in the user's profile directory, you can use the new functions getConfigVar() and setConfigVar() instead of getIniVar() and setIniVar(). Users who have worked with getIniVar() and setIniVar() should find themselves quite at home with these two new functions, which are very similar.

The syntax of these new functions is as follows:

  getConfigVar(<sect name>,<item name>,<file name>[,<loc>])

  setConfigVar(<sect name>,<item name>,<new value>,<file name>[,<loc>])

The parameters are the same as for getIniVar() and setIniVar(), except for:

<file name>

The name of the INI file you want to access, with an optional relative path. The path is relative to the directory specified by the <location> parameter.

<loc> (optional)

This identifies the location of the INI file, and can be one of the following values:


-- Write INI entry to

-- <user profile>\Local Settings\Application Data\MyApp\users.ini

get setConfigVar("UserNames",uID,uN,"MyApp\users.ini","local")

-- Read INI entry from MyApp\users.ini

-- wherever it is found in the INI search path

userName = getConfigVar("UserNames",uID,"MyApp\users.ini")


These functions exist within the Runtime System book (TB115R.SBK). It is necessary to ensure that this Runtime System book is added to your Bound System Books list (see File menu), in order for the functions to work properly in the Runtime engine. There is a slight difference in behavior between getIniVar and getConfigVar that you need to be aware of.


x = ASYM_Trim(getConfigVar("UserNames",null,"MyApp\users.ini"))

Created with the Personal Edition of HelpNDoc: Easily create EPub books