[ Home | Alpha index | Topic index | Tutorials | Download | Feedback ]

The OS/2 API Project

PrfOpenProfile

[ Syntax | Params | Returns | Include | Usage | Structs | Gotchas | Code | Also ]

Syntax

hiniProfile = 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:

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

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.

Relevant Structures

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

Author

Ryan C. Gordon - warped42@ix.netcom.com

Additions

Last modified June 5/1996
Please send all errors, comments, and suggestions to: timur@vnet.ibm.com

The OS/2 API Project

PrfOpenProfile