PrfQueryProfile

Gets the names of the current OS2SYS.INI and OS2.INI files.

Syntax

PrfQueryProfile ( HAB hab, PPRFPROFILE pprfproProfile )

Parameters

hab (HAB) - input

Handle to an Anchor Block returned by WinInitialize().

pprfproProfile (PPRFPROFILE) - input/output

Pointer to a PRFPROFILE structure.

Returns

bRC (BOOL) - return

This return value is always either:

TRUE

Success

FALSE

Error occurred. Some internal failure, or there was not enough space for the record names. This will cause the names to be truncated.

Include Info

#define INCL_WINSHELLDATA

or

#define INCL_WIN

or

#define INCL_PM
#include

Usage Explanation

This function merely gives you the filenames of the current user and system profiles. If either ULONG field of the PRFPROFILE structure is zero, then rather than write to a buffer, PrfQueryProfile() will return in that ULONG the number of bytes required to hold the name. This will allow you to allocate memory for a second call. If those ULONGs are greater than zero, PrfQueryProfile() expects that there is sufficient memory allocated in the PSZ fields to store the file names. If there isn't, the names will be truncated to fit.

Gotchas

The biggest "gotcha" applying to this API call is memory management. You should ALWAYS call this function twice; first, with pprfproProfile->cchUserName and pprfproProfile->cchSysName equal to zero. then allocate enough memory based on their returns, and finally call PrfQueryProfile() again with the newly allocated buffers.

Sample Code

/*
* This function assumes the existence of these two functions:
*  WhineAboutErrors(), which notifies the user of a problem and then
*  terminates the application, and RestOfProgram(), which will run
*  after our calls to PrfQueryProfile()...
*/

#define INCL_WIN
#include <os2.h>
#include <stdlib.h>

int main(void)
{
   HAB hab;
   PRFPROFILE prfproProf;

   hab = WinInitialize(0);

   /* Initialize to zero, so we can get the buffer size needed. */
   prfproProf.cchUserName = prfproProf.cchSysName = 0;

   if (PrfQueryProfile(hab, &prfproProf) == FALSE)
       WhineAboutErrors("PrfQueryProfile failed.");

   prfproProf.pszUserName = malloc(prfproProf.cchUserName);
   prfproProf.pszSysName  = malloc(prfproProf.cchSysName);

   if ((prfproProf.pszUserName == NULL) || (prfproProf.pszSysName == NULL))
       WhineAboutErrors("Memory Allocation Error.");

   /* call 2nd time, with fields initialized. */
   if (PrfQueryProfile(hab, &prfproProf) == FALSE)
       WhineAboutErrors("PrfQueryProfile failed.");

   RestOfProgram();

   return(0);
} /* main */

See Also

• PrfReset