Cedar expects its user to be an individual registered with Grapevine. Whenever you enter the Cedar world, you will be asked to supply your Grapevine RName and password. Once you have been authenticated, Cedar will remember your credentials until you either (1) push the boot button, (2) boot a non-Cedar partition (e.g., an Alto partition), or (3) push the "Idle" button in the extreme upper right corner of the screen. If you are not registered with Grapevine, contact your local support staff.

The precise form in which Cedar asks for your credentials depends upon the way in which the credentials were originally installed. Public machines and some personal machines (at their owners' option) have "unprotected" disks, meaning that Cedar will permit any individual recognized by Grapevine to log in. Other personal machines, however, have "protected" disks, meaning that Cedar will only allow a specific individual to log in. To change from a unprotected disk to a protected one, (or vice versa, if it is yours), use Iago's "Install Credentials" command.

The basis for screen management is the Viewer. In general, a viewer manifests itself as a rectangular area on the screen. Some viewers simply display text, others are virtual buttons that invoke procedures when clicked. We use the verb click to describe the acts of positioning the mouse-controlled cursor over a viewer then depressing and releasing a mouse button, usually the left one. Middle click means to depress the middle button, right click means to depress the right button, etc. Buttons that are active are turned a stipple pattern (gray). In the past mouse buttons were imagined to be red, yellow, and blue (remember it by saying "row your boat") scanning from left to right, so you will occasionally see that terminology.

Across the top of the screen is a small message area where various comments about the system's status and behavior will appear. If the message is especially important, the message window will flash to call the your attention to it. The large middle part of the screen is divided into two columns for displaying tools and documents. Most tools and documents will initially appear as iconssmall pictures at the bottom of the screen. You can open an icon to see its contents by middle clicking it; holding down the SHIFT key while clicking makes it consume the whole column. Left clicking an icon selects it, making it the recipient of type-in from the keyboard. Icon keyboard commands include:

Open viewers display a menu of commands across the top when you move the cursor into the caption (the black band at the top containing the name of the viewer). The commands are as follows:

Middle clicking in the caption menu always invokes the Grow command, and Right clicking always invokes Close. This allows you to invoke these frequently used operations without having to position the mouse as accurately.

The height of a viewer in a column is computed from a set of hints, some determined by programs and some indicated by the user. The program which created the viewer can specify a desired height (such as in the EditTool and Watch viewers) or the program can request that the viewer receive a "fair share" of the available space (as in Tioga text viewers). The user may override these program hints by clicking the Adjust caption menu command, entering a mode where a new height hint may be specified with the mouse. Moving the cursor out of the original column changes the mode to allow the user to specify a new column height and width. At any time while in adjust mode, simultaneously depressing two mouse buttons cancels the adjust command.

Some menu items and buttons will be displayed with a strikeout bar through the text. These are known as guarded commands, implying that command, if inadvertently triggered, might cause loss of your current state. To invoke a guarded command, click once to remove the guard and then again to trigger (within a few seconds or the guard will reappear).

In order to type something into a viewer, you must first establish the input focus by clicking somewhere inside it. (If the viewer is a typescript viewer, i.e., one in which you and the system alternately insert characters, as opposed to a Tioga document, you should make sure that you click the mouse in the white space below the last character.) Left clicking in a text area positions the blinking caret that indicates where your typed characters will appear. A sequence of text characters may be selected by left clicking the first character and right clicking the last; they will appear video reversed, i.e., white on black. Those characters then become the current selection which various buttons (e.g., Open) treat as an input parameter. Whatever you type replaces the current selection when it is video reversed. There are many other things to learn about selection described in the Tioga manual [G1]. Tioga is generally similar to Laurel [G2].

There are some buttons at the right end of the message area. You can boot any of your system volumes (e.g., Alto, Cedar, Debugger) by left clicking Boot to bring up a set of buttons. Right clicking Boot brings up a viewer that allows for more options in booting. The New button creates a new text viewer that you can type new text into; typing a file name followed by LF will load a file into it. The Open button creates a new text viewer for the file named by the current selection. Clicking Clean will take some older viewers and put them inside of a tool box labeled "MRU Cache". This is useful for getting icon space at the bottom of the screen. To get the viewer back, the "MRU Cache" icon may be opened, and the middle button clicked over the viewer's name. Clicking Idle causes the screen to turn black and display a dancing "Type Key" cursor. This is the preferred way of ending a session without actually leaving the Cedar world. If you subsequently hit a key, you will be asked to login, after which the screen will be restored to its state at the time that Idle was invoked.

It is a good idea to power off a Dorado at night since it takes almost 3 kilowatts to keep it running. Make sure the system is quiescent, then either do a "7-boot" (see section 1.7.4), or the PowerOff command or the PowerOff button.

The checkpoint facility allows you to save the effect of a long set-up computation such as the one that occurs after an installation of a release. Enter the Checkpoint command and wait for a while (over a minute on a Dandelion). After a bit, the screen will clear and the "simple terminal" window will appear. The system will type on this window to keep you appraised as to the progress of the checkpoint. Restoring the state saved in a checkpoint is called a rollback. Whenever you start your Cedar world or click the Rollback button, you will find yourself in the state saved in the checkpoint. It is important to understand that rolling back only restores the state of the virtual memory. It does not undo changes made to files or the directory. Thus you should create checkpoints only when the system is in a quiescent state with no open files; otherwise, strange things might happen after a rollback. If you want to overwrite a bcd (either by compiling or file transfer) that was loaded prior to a checkpoint you should boot the Cedar logical volume and create a new checkpoint.

The keyboard has a few unlabeled keys on a Dorado and Dolphin, and some peculiarly labeled keys on a Dandelion. Here is a list of Dorado/Dolphin keys, followed by the label on the Dandelion key which does the same thing:

Note: The following is summarized and extracted from the documentation of CommandToolDoc.tioga, [G15], which also appears as as a separate section of the Cedar Manual. For more complete discussion, refer to this documentation.

All of the material you are working on, including programs, is stored in files. Each different document you handle will be stored on its own file. The file system is somewhat complicated by the fact that it spans a network and developed in an evolutionary fashion.

Files can reside in various places. First of all, there are local files. The only copies of these files are on the local disk. Other files can be on file servers. We currently run two different types of file servers: IFS (Interim File Servers such as Ivy and Indigo), and Alpine (Luther and Ebbetts).

A number of components of Cedar permit the user to tailor Cedar's behavior along certain predefined dimensions via a mechanism called the user profile. Whenever you boot, rollback, startup a tool or certain other significant events, your user profile is consulted to obtain the value for (some of) these parameters. This operation is performed by consulting a file whose name is <YourName>.profile, e.g., Hagmann.Profile, or if no such file exists, User.Profile. This is the one file that can be kept in the root directory on a public machine. The entries in this profile are of the form

where, for any given key, the value is expected to be either TRUE/FALSE, a number, or a token (a sequence of characters delimited by SP, CR, TAB, COMMA, COLON, or SEMICOLON, or an arbitrary sequence of characters delimited by quotes), or a sequence of tokens. Comments can appear at any point in the profile, and are ignored.

More information and some examples may be found by examining [Cedar]<Cedar6.1>Documentation>UserProfileDoc.tioga, which lists all the currently available options. It is also enlightening to look at other people's profiles stored on the file servers.

The program for reading and sending electronic mail in Cedar is called Walnut. It uses the database management system as a repository for the messages. The documentation for Walnut can be found in a file stored in the documentation directory [G18]; a copy of this documentation appears as a later chapter of this manual.

Various administrative tasks associated with mail, authentication and other uses of Grapevine can be performed with the Maintain command. Bringover Maintain using the Bringover command or the DFTool (it is in Environment.df, and thus should be in your ///Commands/ directory so you don't really have to do a bringover). Its interface is layered according to the complexity of the operations various people need to perform. Many users will need only the level called "normal". This allows you to inspect distribution lists, add or remove yourself from lists, and change your password. When using Maintain, you must always specify names in full. Thus, you must say "CSL^.pa", not "CSL^", and "Hagmann.pa", not "Hagmann".

To look at a distribution list (a "group" in Grapevine terminology), fill in the text field labelled "Group" and click the "Members" button in the first line labelled "Type". The "Summary" button in that line will show you the access controls associated with that group (which control who may add or remove members). To add yourself to a group, fill in the "Group" field and click "Self" in the line labelled "Add". Similarly, you can remove yourself with the line labelled "Remove". Not all groups allow you to add or remove yourself. If you're not allowed to change the group, you should send a message to the owner of the group asking for the change. For example, you would send a message to "Owner-CSL^.pa" to ask about "CSL^.pa".

A summary of all the distribution lists is kept in Palo Alto on file [indigo]<Registrar>GV>FullDLMap.txt.

For the sake of security, it is a good idea to change your password occasionally (say, once a year). To do this, make sure your name is in the text field labelled "Individual", fill in your new password in the line below, labelled "Argument", then click "Password" in the line labelled "Set". Passwords should be at least six characters and unpronounceable. Almost everything is authenticated using Grapevine usernames (a Grapevine RName) and passwords.

This section describes how to obtain a Cedar world on your local disk. It is meant to be used only when installing Cedar on your personal computer. Do not do this on a public machine unless you know what you are doing. This section is mostly lifted from the Cedar 5.1 release message.

If you have never installed Cedar before, you may want to get the assistance of someone who has. This is particularly recommended in the case of Dandelion users. We always recommend a full installation. Shortcuts are not recommended.

There are several types of boots associated with Cedar. There is a physical boot where the user actually pushes a physical button or moves some switches, and there is soft booting where the software boots the machine.

For a physical boot, the depressed keys at the time of the boot determine what gets booted. See [G5] for a complete description of Dorado booting. Except for when installing Cedar as in section 1.7.2 above, the Cedar user almost always boots without any keys depressed. This does the default boot, and for disks set up in the normal manner does a boot into Cedar.

When Cedar is booting, you can also set keys for the boot. This is done by depressing the keys when "812" is displayed, and releasing them when "845" appears. An "F" boot of Cedar is described below. Other common switches are "L" to boot to Iago, "W" that is sometimes used when rebooting the debugger volume (see below), and "N" for booting while ignoring the disk (an option for Iago). The case of the letter does not matter; don't push down the SHIFT key.

A soft boot is done under software control. This is normally done via the BootTool (the "Boot" button on the top of the screen), or Checkpoint/Rollback.

During a boot, several different types of files can be boot-loaded. An etherboot involves taking a copy of a boot file from a server and booting it over the ethernet. This is normally only done during Cedar installation. Etherboots often fail and should be retried after an appropriate interval. Booting a Cedar world has three major options (to the novice): boot to Iago, Full Boot, and Rollback. A boot to Iago is described above.

A full boot loads the Basic Boot File, and starts it up. To trigger a full boot, boot a Cedar volume where there is no checkpoint, or do the boot with the "f" switch. The switch can be set by: 1) holding down the "f" key during booting from the time "812" is displayed until the time when "845" is displayed, 2) using the BootTool, by right clicking the "Boot" button on the top of the screen, and setting the "f" switch, or 3) booting a Cedar volume from Iago (the Boot Logical Volume command) and specifying the "f" switch. The basic boot sequence then looks for a "Basic.loadees" (normally in /indigo/cedar6.1/top/Basic.Loadees), and runs all the binaries found. The end of this sequence does a "Bringover" of BootEssentials, and a "Bringover" of all the df files specified in the user's Installation.Bringover entry in the profile. When all the dust settles, it is a good time to make a checkpoint.

Full boots are dependent on the system file server (Indigo in Palo Alto) being up. Any "FS.Error" occurring during full boot means that either a file server is down, or it was overloaded. Retrying may succeed if the server is only overloaded.

A rollback is the restart of a Cedar image stored on disk. The image was written by Checkpoint. Booting a Cedar volume, with no switches, where there is a Checkpoint file, will cause the Checkpoint to be booted. This is the normal method of booting and occurs when you boot from the physical boot switch or by clicking RollBack.

The debugger volume, if you have one and use it, is somewhat different (normal users do not need to read this paragraph). It also is built during Cedar installation. When a world-swap error occurs, the running Cedar world is outloaded (written to a special place on the disk), and the Debugger world is restarted (this is called inloading). This is similar to a RollBack except that when you leave the Debugger by an approved route (proceeding the Cedar world or booting something with the BootTool), then the current state of the Debugger world is saved as the image to restart the next time the Debugger is needed. The Debugger will sometimes get confused (some cached values are wrong?). You can reboot the Debugger with the "w" switch ("w" means to assume debuggee outload file is valid/interesting), and continue debugging. Of course, you loose the typescripts and everything volatile from the previous debugger. Leaving the Debugger by a non-approved route, such as a physical boot, will cause the debugger to be full booted the next time it is needed. The use of the world swap debugger has almost been discontinued due to the long time to swap between worlds, and the large amount of disk space needed to keep the worlds.

All of these variations are called booting. If someone tells you to boot something, ask for clarification if it is not clear what type of boot is meant.

If the system file server(s) is (are) down (Indigo in Palo Alto) then Cedar will exhibit peculiar behavior. Sometimes this is only annoying, such as opening some files is very slow, but often "server inaccessible" errors will prevent useful work. To see if Indigo is up, boot Iago and use the "List Files" command to list a file on the server such as /Indigo/Cedar6.1/Top/FS.df. If you are using a running Cedar world, type "Chat Indigo" to a CommandTool window. If you cannot open the connection to Indigo, then there is trouble. If you can open the connection, click "Disconnect" and destroy the window. You cannot full boot when all of the system file server(s) is (are) down, and you cannot do a Bringover of any release software.

If the user file server is down (Ivy in Palo Alto), then you cannot access your files or save changed files.

You also may have the misfortune to encounter a bug in the Cedar system that causes it to crash. There are various ways to recover from crashes.

If you seem to be stuck and the maintenance panel lights (on a Dorado they actually appear on the screen) say:

Do an "openr MPCodes" for more codes. (If your machine is dead, you may need to do this on a different machine).

An 815 MP code indicates that the machine is waiting for teledebugging. Find a machine running (the same release of) Cedar, and ask if the user will teledebug your machine. It is a good idea for them to save their work, since the teledebugger has been known to crash. Get into the DebugTool by typing "Debug machine-name" where machine-name is replaced by the machine's name stuck in 815 (e.g., "Hornet"). If everything works, then an "Event" window showing an error from the machine in 815 will appear on the display. If you forced the machine into 815 (e.g., CTRL-LEFTSHIFT-SWAT), then this will be the DebugNub and not really the error process. Use the DebugTool, described in [Cedar]<Cedar6.1>Documentation>DebugToolDoc.tioga to poke around and find the error. Freezing "SignalsImpl" is a good way to find processes that have current signals or errors raised. Using the "SetDebugSearchRules" and "AddDebugSearchRules" commands may help the system to find source and binary necessary for debugging. See 2.2 and 2.3 below.

Anything less than 800 typically indicates a microcode or hardware problem. Maintenance panel codes less than 800 usually occur only on Dolphins and DLions. See [G6] for a list of Dolphin maintenance panel codes. On a Dorado, a hardware or microcode-detected error usually halts the machine; the usual manifestation is that the screen turns completely black or gray with diagonal stripes or vertical lines. Seek help from the hardware support staff if this occurs (mail to CMS.pa or call 4370 at PARC): it probably means you have a bad RAM chip in the microcontrol store and they can find it if you don't reboot. Maintenance panel codes above 800 but not in the above list are usually but not always due to hardware problems also.

If the maintenance panel says 800 (or, on a Dorado, no numbers are visible), but there is no response to keyboard or mouse input, you need to get control somehow. In general, there are several levels of fall-back to try. Starting from the least drastic:

You might try running the following example program:

To create this file, take a CommandTool and "cd" it to a new directory. Enter the "New" command, and copy this text into the new viewer (see the Tioga documentation [G1]), and store the file as test.mesa (using the Files sub-menu: select the name to store it under (Test.mesa), left click "Store", and then click it again when the message window displays "Confirm Store to file ...").

To establish the file name binding for the interfaces needed in the compilation, use the commands listed belod. When you are all done, do a ``delete *!*'' in this directory (not in "///" !!!!!!) to clean it out. Now type:

You then compile and run it with the following interaction:

Now click anywhere near the bottom of the new viewer named Compute.Log, and type in two numbers, followed by a RETURN.

Compiler error messages can be somewhat obscure. Look in [Cedar]<Cedar6.1>Documentation>CompilerMessagesDoc.tioga for assistance in understanding them.

DebugTool [G4] provides the Cedar debugging facilities, which include a basic interpreter, primitives for controlling programs by setting breakpoints, proceeding from breakpoints, and other such services. These facilities are available to the user through the Commander as described in section 1.2. The BreakTool [G14] provides more complicated facilities such as conditional breakpoints and conditional tracing.

The interpreter has access to all names defined in the global frames of loaded programs (including types) plus all names in a special name space local to the interpreter. These special names all begin with &.

The interpreter handles a subset of Cedar expressions. The following is a summary of the subset:

The interpreter handles expressions containing arithmetic and logical operators (such as + and OR), and conditional expressions (IF but not SELECT.) Sometimes it is necessary to write parentheses around an expression to prevent the interpreter from getting confused. In general, you must prefix a procedure name with the name of its interface or implementation module; e.g., Rope.Cat.

In looking up a name, the interpreter

The most important document for locating parts of the system are the Catalogs ([Cedar]<Cedar6.1>Documentation>CedarCatalog.tioga [G9] and [Cedar]<CedarChest6.1>Documentation>CedarChestCatalog.tioga). These files list the various packages with brief descriptions and pointers to further documentation (if available).

If you are reading some software that is loaded in your world (most commonly by the run command or in the basic boot file), then use the "←" operator in a CommandTool to find the implementation. For example, suppose I have a source line like this:

To find the implementation of PutF, enter "← IO.PutF" into a CommandTool window. This yields "IOPrintImpl.PutF". Now use open or openr to see the source for IOPrintImpl (e.g., type "openr IOPrintImpl", or select "IOPrintImpl" and click "openr" if you have a button for it). Use open for files know in the current subdirectory, and openr for files in the release (such as IOPrintImpl). Select "PutF", and click "Def". Alternatively, select "IOPrintImpl.PutF" and click "openr" (or type "openr IOPrintImpl.PutF") to do all this in one step.

Things are much harder if the software is not loaded in your system. If it is in the Cedar release, then it is indexed in [Cedar]<Cedar6.1>Documentation>DFIncludes.txt. Open this file and do a Find on the package name (e.g., "IO.bcd" for the example above). This will tell you the df file where the interface is exported. Normally, it is pretty straightforward to find or guess where the modules are that export to the interface (for interface Foo.mesa, look in FooImpl.mesa). If there is more than one candidate, you can either open them all, or use grep to search them (grep looks a lot like the UNIX (tm) grep). You may have to do a bringover on grep and run it before using it.

While doing compilations, you will often get errors due to missing interface BCDs (interface `cannot be opened' in compiler jargon). GetFromRelease helps remove these compiler errors by making attachments, and suggests additions to the df file. GetFromRelease reads the Compiler.log (and hence any Foo.errlog files if you use separate logs) looking for the interface names that are missing. GetFromRelease uses the Cedar version maps to discover the released files containing the interfaces.

Findr, FindRBin and Openr use the version maps. This is how much of the system maps from short file names to global file names. There are maps for both source and symbols, and they are set by User Profile options VersionMap.SourceMaps and VersionMap.SymbolsMaps. A good starting value for these are as follows:

In the following, assume the file is on [Cedar]<Cedar6.1>Documentation> or [Cedar]<CedarChest6.1>Documentation> unless a full path name is explicitly given