PrfOpenProfile

Defines a file that can be used as OS2SYS.INI or OS2.INI. The file name is supplied as a parameter to the call.

Syntax

PrfOpenProfile ( HAB hab, PSZ pszFileName )

Parameters

hab (HAB) - input

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

pszFileName (PSZ) - 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

hiniProfile (HINI) - return

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

• NULLHANDLE - Error occurred.
• Otherwise - A valid handle to an initialization file.

If NULLHANDLE, you may use WinGetLastError() to find out what went wrong. Possible errors PrfOpenProfile() may incur:

PMERR_OPENING_INI_FILE	0x1301	Failure to open due to lack of disk space or something similar.
PMERR_MEMORY_ALLOC	0x1309	There were internal memory allocation problems.
PMERR_INI_FILE_IS_SYS_OR_USER	0x1124	Either the user or system profile was specified for a filename.

Include Info

#define INCL_WINSHELLDATA

or

#define INCL_WIN

or

#define INCL_PM
#include <os2.h>

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.
*/

#define INCL_WIN
#include <os2.h>

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 */

See Also

• PrfCloseProfile, WinInitialize