PrfOpenProfile

Syntax
PrfOpenProfile ( hab, pszFileName )

Parameters

 * HAB hab (input)
 * Handle to an Anchor Block. This should be a return value from WinInitialize.


 * PSZ pszFileName (input)
 * Pointer to a null-terminated string that holds the filename to use as a profile. By convention, this filename is usually in the format "basename.ini". This string may not be either the current user profile or the system initialization profile.

Returns

 * HINI hiniProfile: This is a handle to an initialization file. hiniProfile will contain either:

Include Info
or or
 * 1) define INCL_WINSHELLDATA
 * 1) define INCL_WIN
 * 1) define INCL_PM
 * 2) include

Usage Explanation
This function allows you to specify an alternate filename for using the Prf* APIs on. The most handy use for this is if you have a lot of data fields for an individual application, and don't wish to clog up the end user's OS2.INI file. When you can have a profile entirely to yourself, you can make more of a data 'tree', using both application names and keywords to separate data, instead of just keywords.

Also, uninstalling an app is simpler when all that need be done is erase an INI file along with the executables, as opposed to digging all your entries out of the collective-user profile.

Gotchas
Easily enough, don't specify a file that's being used, or the two default profiles, and everything will probably run fine. And it isn't wise to use a file unless it was created with the Prf* APIs. Some Prf* API calls can be used in a VIO (text-based) program, but this one, and a few others, require a handle to an Anchor Block (HAB), which you get from WinInitialize, so you might run into difficulties trying to implement your own profiles outside of a Presentation Manager program. In this case, you'll have to use either OS2.INI or OS2SYS.INI to store your information.

You do not have to, and in fact should NOT attempt to open the user or system profiles with PrfOpenProfile. Instead, use HINI_USER (or HINI_USERPROFILE) for the current user profile, and HINI_SYSTEM (or HINI_SYSTEMPROFILE) as handles to INI files in accessing these profiles.

Finally, handles returned by PrfOpenProfile are only valid in the process that originally called this API, perhaps due to the need for a Handle to an Anchor Block. This means that you can't pass a HINI variable through shared memory, named pipes, or other means of interprocess communication and have it work on the other end.

Sample Code
/* * Assume for the sake of this example that there exists two functions, *  one named RestOfProgram, which will contain everything after we *   get the profile opened, and WhineAboutErrors, which displays an *   error message, and terminates the program. */ int main(void) {   HAB hab; HINI hiniMyProfile; hab = WinInitialize(0); hiniMyProfile = PrfOpenProfile(hab, "MYPROF.INI"); if (hiniMyProfile != NULLHANDLE) RestOfProgram(hiniMyProfile); else WhineAboutErrors("Couldn't open profile."); return(0); } /* main */
 * 1) define INCL_WIN
 * 2) include 