PrfReset

PrfReset changes the default profiles being used by the system.

Syntax

PrfReset( HAB hab, PPRFPROFILE pprfProfile )

Parameters

hab (HAB) - input

Handle to an anchor block. This is a return value from WinInitialize().

pprfProfile (PPRFPROFILE) - input

Pointer to a PRFPROFILE structure. This will contain the names of the new profiles to be used. This may contain any valid filename. If a filename isn't fully qualified, it is assumed to reside in the current working directory. If a file doesn't exist, it is created by this API call.

Returns

bRC (BOOL) - return

This return value is always either:

TRUE

Success

FALSE

Error occurred

If FALSE, you may use WinGetLastError() to find out what went wrong.
There is only one possible error PrfReset() may generate:

PMERR_OPENING_INI_FILE  0x1301  Due to an error, the files could not be opened.
                                This may be due to a lack of disk space, or
                                something similar.

Include Info

#define INCL_WINSHELLDATA

or

#define INCL_WIN

or

#define INCL_PM
#include <os2.h>

Usage Explanation

The reason for this is to allow applications, such as a login program, to change system defaults to accommodate a new user. The user profile contains settings for various programs, as well as Presentation Manager preferences (color schemes, the desktop, etc.). The system profile contains computer-specific variables. For this reason, PrfReset() will only let you change the user profile. When the profiles are changed, PrfReset() broadcasts a PL_ALTERED window message to all running applications. This notifies the program that the profiles have been changed, and they should re-read them to get the default values for the new user. (Although there is no guarantee all programs will process this message. DOS, Windows, and Text-based OS/2 programs do not receive this message, either.

Gotchas

First, don't expect all the applications running at any given time to be certain to process a PL_ALTERED message. Second, you must pass the current system profile to this function, since you aren't allowed to change it. Usually it is OS2SYS.INI, but a different filename may be specified in the config.sys. Hence, you must also call PrfQueryProfile() twice before PrfReset() to get that information. And since you need a handle to an anchor block, this call may only be issued from inside a Presentation Manager program. Third, it has been my experience that the WorkPlace Shell crashes (this is with Warp without Windows and no fixpak, though.) sometimes when it receives the PL_ALTERED message. I've also run out of stack space in this call (although this could be a symptom of the WPS, and not the code). So, to be safe, don't shirk on the stack space. If the WPS crashes, after the standard error message, it will reload without a need to reboot. Fourth, you can SEVERELY frighten the unsuspecting user when all his icons either change or vanish due to this API. Be careful in how you use it, or you might have people reboot/format/reinstall from scratch if they don't know what's going on.

Sample Code

 /*
  * This program merely changes the user profile without any fanfare. It'll
  *  beep the speaker on error.
  *
  * Note that since you probably do NOT have a file named 'os2new.ini' on
  *  your system, running this code will wipe out your desktop. Don't panic.
  *  It doesn't affect your original files at all, so a simple reboot will
  *  bring your desktop back. This is because when the WorkPlace Shell gets
  *  the PL_ALTERED window message, it tries to get the new desktop and
  *  backgrounds from the file you specified...which, in this case, has
  *  nothing to offer. Specifying your current user profile (usually found in
  *  C:\os2\os2.ini), will make your desktop appear to do nothing more than
  *  redraw.
  */

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

 int main(void)
 {
     HAB hab;
     PRFPROFILE prfproProf;
     UCHAR ucUserProfile[] = "OS2NEW.INI";

     hab = WinInitialize(0);
     prfproProf.cchUserName = prfproProf.cchSysName = 0;

     if (PrfQueryProfile(hab, &prfproProf) == FALSE)
     {
         DosBeep(300, 500);
         return(1);
     } /* if */

     prfproProf.cchUserName = 0;       /* set to zero for 2nd call. */
     prfproProf.pszSysName  = malloc(prfproProf.cchSysName);

     if (prfproProf.pszSysName == NULL)
     {
         DosBeep(300, 500);
         return(1);
     } /* if */

         /* call 2nd time, with fields initialized. */
     if (PrfQueryProfile(hab, &prfproProf) == FALSE)
     {
         DosBeep(300, 500);
         return(1);
     } /* if */

         /* set up user fields. */
     prfproProf.cchUserName = sizeof (ucUserProfile);
     prfproProf.pszUserName = ucUserProfile;

     if (PrfReset(hab, &prfproProf) == FALSE)
     {
         DosBeep(300, 500);
         return(1);
     } /* if */

     free(prfproProf.pszSysName);
     return(0);
 } /* main */

See Also

• WinInitialize
• PrfQueryProfile