Important Notice

The pages on this site contain documentation for very old MS-DOS software, purely for historical purposes. If you're looking for up-to-date documentation, particularly for programming, you should not rely on the information found here, as it will be woefully out of date.

◄About Section►  ◄Function Group►                     ◄Up► ◄Next► ◄Previous►
────────────────────────────────────────────────────────────────────────────
 
                           Using Profile Manager
 
You can use Profile Manager functions in character-based MS OS/2 programs as
well as in Presentation Manager applications. A thread that calls Profile
Manager functions must have initialized an anchor block by using the
WinInitialize function. You create an initialization file or open an
existing one by using the PrfOpenProfile function. You then store and
retrieve information from the file by using functions such as
PrfQueryProfileString and PrfWriteProfileString. You can also create and
manage groups and program lists by using functions such as PrfAddProgram and
PrfCreateGroup.
 
Creating or Opening an Initialization File
 
You can create an initialization file or open an existing initialization
file by using the PrfOpenProfile function. This function takes a handle to
an anchor block and a pointer to the name of an initialization file. If the
file doesn't exist in the given path, the function automatically creates an
initialization file.
 
The following example 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)
    /* initialization file not opened or created */
 
If it is successful, the PrfOpenProfile function returns a handle to the
initialization file. Otherwise, it returns NULL. Once you have an
initialization-file handle, you can create new sections in the file and make
new settings.
 
To close an initialization file, you use the PrfCloseProfile function.
 
Reading and Writing Settings
 
You can read and write strings, integers, and binary data to and from an
initialization file. To read from or write to an initialization file, you
must provide a section and a key name that specifies which setting to read
or to change. When you write to an initialization file, if there is no
corresponding section and/or key name, the section and/or key name is added
to the file and assigned the given value.
 
The following example creates the section "MyApp" and the key name
"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, you 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);
 
You can also read strings by using the PrfQueryProfileString function and
write strings by using the PrfWriteProfileString function. You can read
integers (stored as strings) by using the PrfQueryProfileInt function.
 
Identifying the Initialization Files
 
You can retrieve the names of the MS OS/2 initialization files by using the
PrfQueryProfile function. Although the MS OS/2 initialization files are
usually named os2.ini and os2sys.ini, a user can use other files when
starting the system.
 
The following example retrieves the names of the MS OS/2 initialization
files and copies the names of the initialization files to the arrays
szUserName and szSysName. Once you know the names of the MS OS/2
initialization files, you can use that name to open the files and read
settings.
 
char szUserName[80];
char szSysName[80];
PRFPROFILE prfpro = { 80, (PSZ) szUserName, 80, (PSZ) szSysName };
 
PrfQueryProfile(hini, &prfpro);
 
You can change the MS OS/2 initialization files to files of your choice by
using the PrfReset function. This function takes the names of two
initialization files and uses them as replacements for the os2.ini and
os2sys.ini files. The system is then reset using the settings in the new
files.
 
Creating Groups and Program Lists
 
You can create a group and a list of programs by using the PrfCreateGroup
and PrfAddProgram functions. A group is a window, managed by Desktop
Manager, that contains a list of programs. The user can start a program in
the list by selecting the program title or double-clicking the title using
the mouse.
 
The following example creates a new group, named "My Application," and adds
one program to it:
 
HPROGRAM hGroup;
HPROGRAM hProg;
PROGDETAILS progde;
 
progde.Length =          sizeof(PROGDETAILS);
progde.progt.progc =     PROG_PM;                /* Prof. Mngr. prog. */
progde.progt.fbVisible = SHE_VISIBLE;            /* visible           */
progde.pszTitle =        "My Application";       /* program title     */
progde.pszExecutable =   "c:\\os2\\myapp.exe";   /* path to exe file  */
progde.pszStartupDir =   "c:\\os2";              /* work directory    */
progde.pszIcon =          "";                    /* empty if not used */
progde.pszEnvironment =   "";
progde.pszParameters =    "";
progde.swpInitial.fs =    0;
progde.swpInitial.cx =    0;
progde.swpInitial.cy =    0;
progde.swpInitial.x =     0;
progde.swpInitial.y =     0;
progde.swpInitial.hwndInsertBehind = NULL;
progde.swpInitial.hwnd =  NULL;
 
hGroup = PrfCreateGroup(HINI_USER, "My Application", SHE_VISIBLE);
hProg = PrfAddProgram(HINI_USER, &progde, hGroup);
 
 
                                      ♦