In this document:
Windows has long used text-based configuration files to store setting information for itself, as well as for applications programs you have installed on your computer. These configuration files are better known as INI files; typical examples include WIN.INI and SYSTEM.INI, used in Windows 3.1- as well as many Windows 95-based systems. The WIN.INI file, for instance, contains user-selectable functions, such as the current printer, and whether to use wallpaper or a pattern for the desktop.
Windows 95 (and Windows NT) does not rely on INI files as much as Windows 3.1 did, and instead uses something called the Registry for storing system and application setting information. Though Windows 95 does not make heavy use of INI files, the operating system still supports them. Windows (3.1, 95, and NT) provides a handful of special built-in functions for writing and retrieving information in INI files.
The INI file function are designed for use by Windows programmers, but can be accessed by a WordPerfect macro. This is handy because WordPerfect for Windows lacks its own macro commands for manipulating INI files. You might want to use an INI function to read the data stored in an existing INI file, or to use an INI file to store scraps of information for later use. For example, an INI file could contain the next file number to use in an automatically incrementing file naming system you've developed.
Windows provides a series of INI file functions, but the two most commonly used are GetPrivateProfileString and WritePrivateProfileString. These functions are available to a WPWin macro using the DLLCall statement. This statement is used whenever you wish to access a function built into the Windows application programming interface (API).
The GetPrivateProfileString function retrieves a string value from a private initialization (INI) file. Your macro can write and read information from these INI files. You can also use INI files to store pieces of information you want to use later.
Note that WPWin 6.1 doesn't use many INI files itself; (rather, it stores configuration data in its proprietary binary initialization file (BIF). Further, WPWin 7 and 8 don't use INI files at all, preferring to store their information into the Windows Registry.
The 6.1 syntax for the GetPrivateProfileString function is"
DLLLoad (Kernel; "KERNEL")
DLLCall (Kernel; "GetPrivateProfileString"; wProfileResult: WORD;{
lpAppName;
lpKeyName;
Loword (nDefault);
Address (lpReturnString);
lpFileName})
DLLFree (Kernel)
The syntax for WPWin 7 and 8 is almost identical, except that the Loword keyword is omitted:
The 6.1 syntax for the GetPrivateProfileString function is:
DLLLoad (Kernel; "KERNEL")
DLLCall (Kernel; "GetPrivateProfileString"; wProfileResult: WORD;{
lpAppName;
lpKeyName;
nDefault;
Address (lpReturnString);
lpFileName})
DLLFree (Kernel)
In both cases, The function returns the length of the string copied to the lpReturnString variable. The lpAppName, lpKeyname, and lpFileName parameters are not case dependent. Before using GetPrivateProfileString, you must declare the lpReturnString variable. This is done by assigning a "buffer" variable.
For more info on the construction of an INI file see WritePrivateProfileString, below.
Example of GetPrivateProfileString:
// Retrieve and print current setting of "Value" keyword under
// the [Text] section, in file JUNK.INI
restoring=""
DLLLoad (Kernel; "KERNEL")
DLLCall (Kernel; "GetPrivateProfileString"; wGetProf:WORD;{
"Test";
"Value";
"Ick";
Address (retString);
Loword (128); // drop Loword in WPWin 7/8
"junk.ini"})
DLLFree (Kernel)
The WritePrivateProfileString is used to write a value in an INI file. You can write to INI files that below to another application, or you can create your own INI files for use with your macros.
The syntax of the function (6.1, 7, or 8) is:
DLLLoad (Kernel; "KERNEL")
DLLCall (Kernel; "WritePrivateProfileString"; bPrivateProf:BOOL;{
lpAppName;
lpKeyName;
lpString;
lpFileName})
DLLFree (Kernel)
The function returns a True if the function was successful; otherwise the return value is False.
You can better visualize how the WritePrivateProfileString function works by visualizing the way data is stored in an INI file. INI files are composed of sections, identified by a name in brackets. Under each section is a list of one or more keynames and values. For example,
[Section Name] keyname = value or string ...
If the file specified in lpFileName already exists, then WritePrivateProfileString alters the existing file. If the file doesn't exist, the function creates a new file. If you omit the path in lpFileName, WritePrivateProfileString searches the Windows directory.
WritePrivateProfileString makes no change if lpString is the same as the value already found in the file (Windows ignores the case of the string). If the keyname doesn't already exist, the function adds it under the appropriate section.
Example of WritePrivateProfileString:
// Write string to private INI file
DLLLoad (User; "KERNEL")
DLLCall (User; "WritePrivateProfileString"; bProfile:BOOL;{
"application name"; // [application name] section
"keyname"; // keyword
"newstring"; // new string for keyword
"junking"}) // Name of private INI file
DLLFree (Kernel)
You can extend the usefulness of using the Windows INI file API functions in your WPWin macros by creating your user-defined functions. A user-defined function is like a built-in macro command, except that you define what the function does, the data it accepts, and the data it returns upon completion.
Below are two user-defined INI file functions you can include in your own macros. The WriteIniString function serves as a "wrapper" for the Windows WritePrivateProfileString API function. Conversely, the GetIniString function serves as a wrapper for the GetPrivateProfileString function. Note that two versions of GetIniString are provided -- one for WPWin 6.1/7 for Windows 3.1, and another for WPWin 7/8 for Windows 95. Also note that these functions use the AnsiString statement to ensure that WPWin uses only Windows text with the functions.
//==============================================================
// For WPWin 6.1, 7, and 8
Function WriteIniString (AppName;Keyname;ValString;Filename)
DllCall (Kernel;"WritePrivateProfileString"; ret:BOOL;
{AnsiString(AppName);AnsiString(Keyname);
AnsiString(ValString);AnsiString(Filename)})
Return (ret)
EndFunc
//==============================================================
// For WPWin 6.1 or 7 for Windows 3.1
Function GetIniString (AppName;Keyname;DefaultString;Filename)
RetString=""
DllCall (Kernel;"GetPrivateProfileString";ret:WORD;
{AnsiString(Appname);AnsiString(Keyname);
AnsiString(DefaultString);AnsiString(Address(RetString));
Loword (128);AnsiString(Filename)})
Return (RetString)
EndFunc
//==============================================================
// For WPWin 7/8 for Windows 95
Function GetIniString (AppName;Keyname;DefaultString;Filename)
RetString=""
DllCall (Kernel;"GetPrivateProfileString";ret:WORD;
{AnsiString(Appname);AnsiString(Keyname);
AnsiString(DefaultString);AnsiString(Address(RetString));
128;AnsiString(Filename)})
Return (RetString)
EndFunc
To use either function you must first add the following near the top of your macro:
Global (Kernel) DLLLoad (Kernel; "Kernel")
Note: In all instances, the maximum length of any INI text value is 128 characters.
Ret=WriteIniString (AppName;Keyname;ValString;Filename)
where AppName is a section name in the INI file, Keyname is a key under that section, ValString is the string you want to write to the file, and Filename is the path and name of the INI file (note: if you leave off the path, Windows will expect the INI file to be in the main Windows directory). The Ret return variable contains a True or False, depending on whether the function worked.
Ret=GetIniString (AppName;Keyname;DefaultString;Filename)
where AppName is a section name in the INI file, Keyname is a key under that section, DefaultString is a string to return if the INI file cannot be processed, and Filename is the path and name of the INI file (note: if you leave off the path, Windows will expect the INI file to be in the main Windows directory). The Ret return variable contains the returned string.
Several example of using INI file functions are available here. These examples include:
A common question of those looking to store configuration data is whether to use INI files, the Windows Registry, or WPWin's proprietary BIFs (Binary Intialization Files). All three have their uses.
© Copyright 1997, by Gordon McComb. All Rights Reserved. Permission granted to print and distribute this document within your company or organization, as long as this copyright notice remains intact.