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

The OS/2 API Project


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


bRC = PrfReset( hab, pprfProfile );


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. See the 'Relevant structures' section below for more details. If a file doesn't exist, it is created by this API call.


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_WIN
#define INCL_PM
#include <os2.h>

Usage Explanation

This API changes the default profiles being used by the system. The reason for this is to allow applications, such as a login program, to change system defaults to accomodate 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 recieve this message, either.

Relevant Structures

ULONG cchUserName;
This is the size, in bytes, of the buffer pointed to by the pszUserName field (described below).
PSZ pszUserName;
This points to a buffer holding the name of the new user profile. (in other Prf* API calls, the user profile handle is specified as HINI_USERPROFILE). This is a null-terminated (ASCIIZ) string.
ULONG cchSysName;
This is the size, in bytes, of the buffer pointed to by the pszSysName field (described below). You should let PrfQueryProfile() set this field for you.
PSZ pszSysName;
This points to a buffer holding the name of the new system profile. (in other Prf* API calls, the system profile handle is specified as HINI_SYSTEMPROFILE). This is a null-terminated (ASCIIZ) string. Again, you should let PrfQueryProfile() set this field for you.
A pointer to a PRFPROFILE structure. Same as (PRFPROFILE *).


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 recieves 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


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


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

The OS/2 API Project