PMGuide - Initialization Files
Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation
Initialization files enable an application to store and retrieve information that the application uses when it starts up. This chapter describes how to use the IBM OS/2 Profile Manager to create, manage, and use the system's initialization files. The following topics are related to this chapter:
- File system
- Presentation Manager interface applications
About Initialization Files
An initialization file is a convenient place to store information between sessions. Profile Manager enables applications to create their own initialization files and to access the OS/2 initialization files, os2.ini and os2sys.ini. Just as the system uses the os2.ini and os2sys.ini files to store configuration information for system startup, an application can create an initialization file that stores information it uses to initialize windows and data.
The system initialization files contain sections and settings used by the PM applications. Although applications can read settings from the initialization files, only rarely does an application need to change a setting. OS/2 initialization files are binary; the user cannot view or edit them directly.
An initialization file consists of one or more sections; each section contains one or more settings, or keys. Each key consists of two parts: a name and a value. Both section names and key names are null-terminated strings. The value assigned to a key can be a null-terminated string, a null-terminated string representing a signed integer, or individual bytes of data.
Once an initialization file is created, an application can rename, copy, move, or delete that file just as it does any other file. Although an application also could read directly to or write directly to the initialization file, the application should always use Profile Manager functions to access the contents of the file. Both character-based OS/2 applications and PM applications can use Profile Manager functions. Before calling Profile Manager, a thread must initialize an anchor block by using the WinInitialize function.
Using Initialization Files
This section explains how to use Profile Manager functions to perform the following tasks:
- Create, open, and close initialization files
- Read and write settings
- Identify the initialization files
Creating, Opening, and Closing Initialization Files
You can create an initialization file or open an existing initialization file by using the PrfOpenProfile function. The function requires a handle to an anchor block and a pointer to the name of an initialization file. If the file does not exist in the given path, the function automatically creates an initialization file.
The following code fragment creates an initialization file named pmtools.ini in the current directory:
HAB hab;
HINI hini;
hab = WinInitialize(0);
if ((hini = PrfOpenProfile(hab, "pmtools.ini")) == NULL){
/* File was not created */
}
If the PrfOpenProfile function is successful, it returns a handle to the initialization file. Otherwise, it returns NULL, and the file is not created. Once you have an initialization-file handle, you can create new sections and settings in the file.
To close an initialization file, you use the PrfCloseProfile function.
Reading and Writing Settings
An application can store strings, integers, and binary data in an initialization file and retrieve them. To read from or write to an initialization file, your application must provide a section name and a key name that specify which setting to read or change. If the section or key name you specify in a writing operation does not exist in the file, it is added to the file and assigned the given value.
The following code fragment creates a section named "MyApp" and a key named "MainWindowColor" in a previously opened initialization file, and assigns the value of the RGB structure to the new setting:
HINI hini;
RGB rgb = { 0xff, 0x00, 0x00 };
PrfWriteProfileData(hini, "MyApp", "MainWindowColor", &rgb, sizeof(RGB));
To read a setting, your application can retrieve the size of the setting and then read the setting into an appropriate buffer by using the PrfQueryProfileSize and PrfQueryProfileData functions, as shown in the following example. This example reads the setting "MainWindowColor" from the "MyApp" section only if the size of the data is equal to the size of the RGB structure.
HINI hini;
ULONG cb;
RGB rgb;
PrfQueryProfileSize(hini, "MyApp", "MainWindowColor", &cb);
if (cb == sizeof(RGB))
PrfQueryProfileData(hini, "MyApp", "MainWindowColor", &rgb, &cb);
An application can also read strings by using the PrfQueryProfileString function, write strings by using the PrfWriteProfileString function, and read integers (stored as strings) by using the PrfQueryProfileInt function.
Identifying the OS/2 Initialization Files
Your application can retrieve the names of the system initialization files by using the PrfQueryProfile function. Although the OS/2 initialization files are usually named os2.ini and os2sys.ini, you can use other files when starting the system.
The following example retrieves the names of the initialization files and copies their names to the strings szUserName and szSysName. Once you know the names of the OS/2 initialization files, you can use them to open the files and read settings.
CHAR szUserName[CCHMAXPATH];
CHAR szSysName[CCHMAXPATH];
HINI hini;
PRFPROFILE prfpro = { sizeof(szUserName), szUserName,
sizeof(szSysName), szSysName };
PrfQueryProfile(hini, &prfpro);
You can change the OS/2 initialization files to files of your choice by using the PrfReset function. This function requires the names of two initialization files and uses them as replacements for the os2.ini and os2sys.ini files. The system is then reset by using the settings in the new files.