UserProfile.mesa
Copyright © 1985 by Xerox Corporation. All rights reserved.
Teitelman on December 16, 1982 11:59 am
Russ Atkinson (RRA) February 5, 1985 3:22:36 pm PST
DIRECTORY Rope USING [ROPE];
UserProfile: CEDAR DEFINITIONS = BEGIN OPEN Rope;
Overview
UserProfile is a package for reading information from the disk file <YourName>.profile, or if none exists, User.profile. The purpose of the profile is to allow personalized tailoring of the system. The current catalogue of ways the Cedar can be parameterized may be found in the file UserProfile.doc.
Entries in the user's profile are of the form: <key>: <value>RETURN, where value is either (1) a BOOL, (2) an INT, (3) a TOKEN, or (4) a ListOfTokens (for more details, see UserProfile.doc). When Cedar is booted, rolledBack, or any file whose extension is "profile" is edited, the profile is parsed and a data structure which describes the information that was found in the profile is constructed. Comments (indicated using the standard "--" convention) can appear anywhere in the profile and will be ignored. The parsing will also ignore extra spaces or blank lines. Any errors or anomalies discovered when parsing or accessing the profile will cause diagnostics to be printed to the file UserProfile.log. The user will be informed that problems have been encountered via the Message Window. In no case however will the system break.
Access to individual profile entries via the procedures below is relatively efficient, since this access does not require any file reads or parsing. Therefore, many simple applications can simply read information from the profile as needed. However, some applications derive complex data structures from the profile (consider the effect of the "UserCategory" profile entry on the state of Tioga), and hence cannot afford to interrogate the profile whenever some information derived from it is used. Such an application must register a ProfileChangedProc and perform all of its profile interrogations from within this procedure. This guarantees that the corresponding values will be updated whenever the profile changes. The ProfileChangedProc will be called when it is first registered, whenever the system is booted or rolled-back, or whenever a file with extension ".profile" is saved.
Note: Since the ProfileChangedProc for an application is not called from that application's process(es), the application must explicitly synchronize its reads to variables derived from the profile with the ProfileChangedProc's writes to these variables. This may involve adding a monitor to an application that previously did not require one.
Accessing the Profile
The procedures described below all read simple results from the value field given a key. The default value is passed in as an argument so that the client can specify what the procedure returns should the value be absent or malformed, or the profile be missing.
Boolean: PROC [key: ROPE, default: BOOL ← FALSE] RETURNS [value: BOOL];
Number: PROC [key: ROPE, default: INT ← 0] RETURNS [value: INT];
Token: PROC [key: ROPE, default: ROPE ← NIL] RETURNS [value: ROPE];
returns next token following <key>:, i.e. effectively does an IO.GetRope[IDBreak]. If the first character encountered is ", then reads everything to the next matching ", and returns this as a single rope.
ListOfTokens: PROC [key: ROPE, default: LIST OF ROPE ← NIL] RETURNS [value: LIST OF ROPE];
For example, if your profile contains:
PreRun: Clock.bcd, VersionMapOpsImpl.bcd, HideousKludge.bcd, -- just until 3.4 -- WalnutSend.bcd
then ListOfTOkens["PreRun"] will return ("Clock.bcd", "VersionMapOpsImpl.bcd", "HideousKludge.bcd", "WalnutSend.bcd).
Note that if the user profile contains Key:{cr}, then ListOfTokens["key", default] will return NIL, not default, i.e. the entry for "key" is neither malformed or absent.
Line: PROC [key: ROPE, default: ROPE ← NIL] RETURNS [value: ROPE];
Like ListOfTokens except returns the result as a single rope, e.g. for above example, the value of Line["PreRun"] would be "Clock.bcd VersionMapOpsImpl.bcd HideousKludge.bcd WalnutSend.bcd".
GetProfileName: PROC RETURNS [ROPE];
returns name of file used to build the profile, i.e. either <YourName>.profile, or UserName.Profile. Returns NIL if no profile.
Registering procedures for accessing the profile
As mentioned above, if the result of accessing the user profile is going to be cached by the client, then the profile should not be accessed directly, but via a ProfileChangedProc which has been registered with CallWhenProfileChanges. This guarantees that the corresponding values will be updated whenever the profile changes.
In other words, rather than writing:
ClientCheckpointFlag: BOOL ← UserProfile.Boolean["ClientCheckpoint", TRUE];
the implementor should write:
ClientCheckpointFlag: BOOL;
Init: ProfileChangedProc = {
ClientCheckpointFlag ← UserProfile.Boolean["ClientCheckpoint", TRUE];
};
UserProfile.CallWhenProfileChanges[Init];
CallWhenProfileChanges: PROC [proc: ProfileChangedProc];
proc is called when it is first registered with reason = firstTime.
ProfileChangedProc: TYPE = PROC [reason: ProfileChangeReason];
ProfileChangeReason: TYPE = {firstTime, rollBack, edit};
ProfileChanged: PROC [reason: ProfileChangeReason];
Calls all of the ProfileChangedProcs. This procedure is automatically called after a rollback, whenever the UserExec.Login is called, or whenever the a file with extension 'profile' is saved by tioga.
GetErrorLog: PROC RETURNS [fileName: ROPE];
if there were any errors reported, this closes the stream and returns the name of the file.
END.
Edited on December 14, 1982 3:50 pm, by Teitelman
changes to comments only
changes to: ListOfTokens, Line
Russ Atkinson (RRA) February 5, 1985 3:21:37 pm PST
reformatted