This is a levelled Tioga document, intended to be read both on line and (during crucial breaks in the action) in hardcopy. Command lines from this document can be secondary-selected and stuffed to a UserExec with appropriate editing. *** and ~~~ are used in command lines to indicate that you must do some editing. None of the command lines end in carriage returns; you must supply your own.

Walnut uses two versions of information about your mail -- the log and the segment (also called the database). The log is the truth. The segment can be generated from the log by a process called scavenging. Entries in your User.profile tell Walnut where to look for your segment and log.

Until recently, Walnut needed for you to have your segment and log on your local disk while it was running. The normal mode was for people to back up their segments and logs on Ivy via entries in their User.df files and periodic SModeling. People who used public machines needed to do Bringovers and SModels of their segments and logs (and millions of weird errors resulted from doing them incorrectly).

Now it is possible for Walnut to use segments and logs on a remote machine. You no longer need to have either segment or log on your local disk, and you no longer need to back them up yourself.

(a) Security and peace of mind. We promise to back up your Walnut log once a day. You may think you are conscientious, but every day people lose their Walnut logs.

(b) Save your valuable time. Bringover of a 1000-message Walnut log takes five minutes on a Dolphin, two on a Dorado.

(c) Storage space -- don't clutter up your local disk and Ivy.

(d) Alpine is the wave of the future.

Ask Karen Kolling for an account and backup of your Walnut log on Alpine. (The name of your Walnut log must be Walnut.DBLog, and it may not be in a subdirectory.) She will notify you when you are on the backup list -- do nothing further till she tells you it's OK.

Nothing is going to work correctly unless you have the right versions of Walnut and everything Walnut needs to use a remote segment and log. At the moment, the best version of Walnut is on <PostCedar>, but by the time you read this there may be an even better version available elsewhere. Consider the following instructions, therefore, as a pattern for the sort of thing you will have to do, rather than absolute gospel.

(1) Put in your User.df (or Mail.df or whatever you use to model your mail world) the lines:

(Your mail world might include other things as well.) Save the file.

(2) Do an SModel of that file:

(The &n notation is shorthand for "Tell a UserExec." Throughout this document, substitute appropriately for *** and ~~~.)

(3) Do a BringOver of your User.df (or Mail.df or whatever).

If you use a public machine, be sure to do a BringOver of your User.df (or Mail.df etc.) and be sure to do a Login with your User.profile on the disk every time before starting Walnut.

(4) Double-left-click Rollback in the upper right-hand corner of your screen unless you have Walnut in your checkpoint. (Walnut is not included in checkpoints on public machines.)

If you are on a private machine and you have Walnut in your checkpoint, Boot your Client volume.

(5) Open a new Viewer on this document. (Sigh.)

Add to your User.profile the entries:

(Check to be sure that you don't have duplicate entries.)

EnableTailRewrite: TRUE gives people who use Alpine to store their Walnut logs the safest kind of expunges.

When you save the new .profile, the entries get processed.

Be warned that if you ever run Walnut in such a way that it cannot read your User.profile it will assume that you use a local segment and log; the only way Walnut knows about the segment and log on Alpine is through your User.profile.

Do

and you should be in business. Ignore the message there are unbound imports.

Why start by doing an expunge? What you need is not the expunge itself but the extra space that it tacks on to the end of your log; without that extra space, Walnut will abort again and again whenever you run it, and you will be irritated by the flashing screen and the delays.

Probably you'll also want to set read and modify access to your Walnut log and segment to be "owner". If you have just rolled back or booted, it should be safe to do:

Be warned that horrible things happen when you run AlpineUserImpls twice. (Getting the message there are unbound imports is not horrible.)

Substitute your name for "~~~." Do not substitute your name for "owner," which is a string that Alpine uses intelligently.

Wildcarding filenames does not work for SetReadAccess and SetModifyAccess. The Set*Access commands return TRUE for finding the file whose access you want to change.

You now have Walnut.EnableTailRewrite set to TRUE in your User.profile. The first time after so setting it, double-left-clicking Expunge in Walnut gives you a full expunge and sets an expunged-to-here marker in your Walnut log.

Thereafter, double-left-clicking Expunge usually gives you a short-cut expunge, from that marker to the end of the file. (You get the short-cut expunge unless you have written "too much" log since the last expunge. If you have written "too much" you get the full expunge.)

Double-right-clicking Expunge always gives you a full expunge.

During a full expunge, there is one dangerous period during which the only version of the truth about your mail is stored on your local machine in a file called Walnut.TempLog. If any part of the system fails during that period, the thing to do is to run Walnut again; Walnut is smart enough to realize what happened and complete the expunge correctly. Since a full expunge takes a long time, some people do one right before going home for the night. Fine, but be sure to check next morning that the full expunge completed. If it didn't, run Walnut again.

Various symptoms are possible if Alpine goes down while you are running Walnut. Perhaps the most confusing is that Walnut will completely freeze up. The explanation is simple: a procedure call on Alpine is taking a very long time. Unfortunately, there are other plausible explanations for this behavior. Walnut may, for instance, have a bug in it that produces a local deadlock. You can generally tell the difference by executing an AlpineCmds procedure in the UserExec, such as AlpineCmds.List. If the procedure fails to return within a reasonable interval, you can safely conclude that Alpine is down. (Walking down the hall to look at the Alpine server can also be enlightening, especially if you find an Alpine implementer there slaving away frantically.)

Regardless of the cause, the most graceful way to get out of this state (i.e. get rid of the catatonic Walnut viewers, as well as the UserExec you have just hung up) is to roll back. If enough of your world is still functioning, you may be satisfied with making these viewers iconic.

On rare occasions the Alpine implementors may have to cold-start Alpine (give it amnesia about the recent past in order to get it going again). If you were actively using Alpine just before the crash, the cold start may leave your Walnut.segment with internal inconsistencies. When you run Walnut and your Walnut.segment has been smashed like this, you will get some random horrible signal from Cypress. Double-left-click Rollback in the upper right-hand corner of your screen. Then scavenge by typing

WalnutScavenge takes a long time but does you the favor of calling the Walnut registered command when it is done.

If you should chance to be running Walnut while the backup system is copying your log file, your Walnut transaction will abort and will not restart until the copy is complete. (The copy may take two minutes for a very long file.) If you leave your Walnut running overnight, you can expect the backup system to copy your log file some time during the night and abort your Walnut transaction.

Do not take a checkpoint on a public machine unless you know how to restore the default checkpoint.

There are two possible stages in which Walnut might be included in a checkpoint: If you use Walnut in almost every session, you might want to load and start the modules for Walnut & Co. and take a checkpoint. If you use Walnut immediately after every Rollback (unlikely but possible), you might want not only to load and start the modules but also to call the registered Walnut procedure.

If you do include Walnut in a checkpoint (either way, by loading and starting the modules or by loading and starting them and calling the registered Walnut procedure) and if there is a new release of Walnut, Cypress, AlpineUser, or TSetter, you must boot your Client volume to get the new release.

A procedure for checkpointing Walnut follows. There are nearly as many ways to achieve approximately this same end as there recipes for authentic Texas chili. The following procedure has been tested, and it includes explanations. Use other procedures at your own risk.

(1) Booting your Client volume causes your User.profile to be read for entries called "PreRun:" and "CommandsFrom:". PreRun specifies a list of .bcd files to load and start. CommandsFrom specifies a series of commands to feed to the UserExec. CommandsFrom has two main advantages over PreRun -- it allows you to specify actions other than loading and starting bcds (such as defining Aliases), and it gives you better error reporting (your commands are right there in the Work Area A Executive; take a look after booting finishes). So the best scheme is to use PreRun to get UserExec loaded and started, then use CommandsFrom for everything else. To do this, change your PreRun entry to:

and add a CommandsFrom entry of the form:

where *** is your name.

Be sure to avoid duplicate PreRun or CommandsFrom entries in your profile. Save the file. (Be sure you have it in your User.df file or whatever file you use to model your identity.)

(2) Make the ***.commands file for yourself and include the lines:

"Run" means "load and start modules"; it does not mean ... uh ... run, exactly. You might want to include other command lines in this file as well, and you might want to load and start the modules for other programs that you use in nearly every session. Save the file and include it in your User.df file or whatever file you use to model your identity.

(3) Left-click Boot (in the upper right-hand corner of the screen) and then double-left-click Client. (Always boot before taking a checkpoint. Do not take a checkpoint on top of an earlier checkpoint. It is not worth discussing the ways in which the system may fail if you ignore this advice.)

(4) Do whatever you like to do to initialize your world, open viewers, etc. A useful trick if you frequently use Walnut after a Rollback is to end this initial session by typing:

with no carriage return. If you really use Walnut every single time you roll back, go ahead and type:

(or "Walnut; WalnutNewMail" or whatever) followed by a carriage return and set up your Walnut viewers to your liking.

(5) Double-left-click Checkpoint (in the upper right-hand corner of the screen).

Again, the best version of Walnut at this moment is on <PostCedar>, but by the time you read this there may be an even better version available elsewhere. Bringover of your User.df (or Mail.df or whatever you use to model your mail world) with lines something like the following:

will capture any new release.

If you include Walnut in a checkpoint (either way, by loading and starting the modules or by loading and starting them and calling the registered Walnut procedure) and if there is a new release of Cypress, Walnut, AlpineUser, or TSetter, do the Bringover, boot your Client volume, and take a new checkpoint.

See Karen Kolling or Mark Brown.

[Indigo]<Cedar>Documentation>WalnutDoc.*
[Indigo]<Cedar>Documentation>AlpineDoc.*
[Indigo]<Cedar>Documentation>Catalog.*

This is a levelled Tioga document, intended to be read both on line and (during crucial breaks in the action) in hardcopy. Command lines from this document can be secondary-selected and stuffed to a UserExec with appropriate editing. *** and ~~~ are used in command lines to indicate that you must do some editing. None of the command lines end in carriage returns; you must supply your own.

Walnut uses two versions of information about your mail -- the log and the segment (also called the database). The log is the truth. The segment can be generated from the log by a process called scavenging. Entries in your User.profile tell Walnut where to look for your segment and log.

Until recently, Walnut needed for you to have your segment and log on your local disk while it was running. The normal mode was for people to back up their segments and logs on Ivy via entries in their User.df files and periodic SModeling. People who used public machines needed to do Bringovers and SModels of their segments and logs (and millions of weird errors resulted from doing them incorrectly).

Now it is possible for Walnut to use segments and logs on a remote machine. You no longer need to have either segment or log on your local disk, and you no longer need to back them up yourself.

(a) Security and peace of mind. We promise to back up your Walnut log once a day. You may think you are conscientious, but every day people lose their Walnut logs.

(b) Save your valuable time. Bringover of a 1000-message Walnut log takes five minutes on a Dolphin, two on a Dorado.

(c) Storage space -- get all that stuff off your disk and Ivy.

(d) Alpine is the wave of the future.

Ask Karen Kolling for an account and backup of your Walnut log on Alpine. (The name of your Walnut log must be Walnut.DBLog, and it may not be in a subdirectory.) She will notify you when you are on the backup list -- do nothing further till she tells you it's OK.

Nothing is going to work correctly unless you have the right versions of Walnut and everything Walnut needs to use a remote segment and log. At the moment, the best version of Walnut is on <PostCedar>, but by the time you read this there may be an even better version available elsewhere. Consider the following instructions, therefore, as a pattern for the sort of thing you will have to do, rather than absolute gospel.

(1) Put in your User.df (or Mail.df or whatever you use to model your mail world) the lines:

(Your mail world might include other things as well.) Save the file.

(2) Do an SModel of that file:

(The &n notation is shorthand for "Tell a UserExec." Throughout this document, substitute appropriately for *** and ~~~.)

(3) Destroy your Walnut viewer or icon if you are currently running Walnut.

(4) Do a BringOver of your User.df (or Mail.df or whatever).

If you use a public machine, be sure to do a BringOver of your User.df (or Mail.df etc.) and be sure to do a Login with your User.profile on the disk every time before starting Walnut.

(5) Double-left-click Rollback in the upper right-hand corner of your screen unless you have Walnut in your checkpoint. (Walnut is not included in checkpoints on public machines.)

If you are on a private machine and you have Walnut in your checkpoint, Boot your Client volume.

(6) Open a new Viewer on this document. (Sigh.)

If you have just rolled back or booted, it should be safe to do:

Be warned that horrible things happen when you run AlpineUserImpls twice. (Getting the message there are unbound imports is not horrible.)

Now use the AlpineCmds set to copy your local Walnut log and segment to Luther.alpine. Substitute your RName for ~~~ in the command lines below. Substitute the name of your local Walnut log for *** in the first line and the name of your local Walnut segment for *** in the second line. (If you use Walnut on a public Dorado, you probably have some kind of personal name for your Walnut log and segment; if you use it on a private machine, your log and segment are probably named simply Walnut.DBLog and Walnut.segment.)

The copies take a long time; look at "requests" in the WatchTool if you need reassurance that they're really happening.

If by chance Alpine should go down during the course of one of these copies, delete the partially copied file with AlpineCmds.Delete before re-copying.

Go ahead, check to be sure they're really there -- we're all twitchy that way.

Should return:

Probably you'll also want to set read and modify access to these files to be "owner". Substitute your name for "~~~." Do not substitute your name for "owner," which is a string that Alpine uses intelligently.

Wildcarding filenames does not work for SetReadAccess and SetModifyAccess. The Set*Access commands return TRUE for finding the file whose access you want to change.

Add to your User.profile the entries:

(Check to be sure that you don't have duplicate entries.)

EnableTailRewrite: TRUE gives people who use Alpine to store their Walnut logs the safest kind of expunges.

When you save the new .profile, the entries get processed. At this point, Walnut is cut loose from your local segment and log; the only reason not to delete them immediately is to back yourself up for the next day or so in case you have done something so strange that we failed to account for it.

Be warned that if you ever run Walnut in such a way that it cannot read your User.profile it will assume that you use a local segment and log; the only way Walnut knows about the segment and log on Alpine is through your User.profile.

Do

and you should be in business. Ignore the message there are unbound imports.

Why start by doing an expunge? What you need is not the expunge itself but the extra space that it tacks on to the end of your log; without that extra space, Walnut will abort again and again whenever you run it, and you will be irritated by the flashing screen and the delays.

(If you had not been using the latest version of Walnut & Co., other adjustments may be necessary.)

After a day or so of successful Alpine use, delete your local Walnut log and segment. If you have been backing them up yourself, delete the versions on Ivy and the entries in your User.df.

You now have Walnut.EnableTailRewrite set to TRUE in your User.profile. The first time after so setting it, double-left-clicking Expunge in Walnut gives you a full expunge and sets an expunged-to-here marker in your Walnut log.

Thereafter, double-left-clicking Expunge usually gives you a short-cut expunge, from that marker to the end of the file. (You get the short-cut expunge unless you have written "too much" log since the last expunge. If you have written "too much" you get the full expunge.)

Double-right-clicking Expunge always gives you a full expunge.

During a full expunge, there is one dangerous period during which the only version of the truth about your mail is stored on your local machine in a file called Walnut.TempLog. If any part of the system fails during that period, the thing to do is to run Walnut again; Walnut is smart enough to realize what happened and complete the expunge correctly. Since a full expunge takes a long time, some people do one right before going home for the night. Fine, but be sure to check next morning that the full expunge completed. If it didn't, run Walnut again.

Various symptoms are possible if Alpine goes down while you are running Walnut. Perhaps the most confusing is that Walnut will completely freeze up. The explanation is simple: a procedure call on Alpine is taking a very long time. Unfortunately, there are other plausible explanations for this behavior. Walnut may, for instance, have a bug in it that produces a local deadlock. You can generally tell the difference by executing an AlpineCmds procedure in the UserExec, such as AlpineCmds.List. If the procedure fails to return within a reasonable interval, you can safely conclude that Alpine is down. (Walking down the hall to look at the Alpine server can also be enlightening, especially if you find an Alpine implementer there slaving away frantically.)

Regardless of the cause, the most graceful way to get out of this state (i.e. get rid of the catatonic Walnut viewers, as well as the UserExec you have just hung up) is to roll back. If enough of your world is still functioning, you may be satisfied with making these viewers iconic.

On rare occasions the Alpine implementors may have to cold-start Alpine (give it amnesia about the recent past in order to get it going again). If you were actively using Alpine just before the crash, the cold start may leave your Walnut.segment with internal inconsistencies. When you run Walnut and your Walnut.segment has been smashed like this, you will get some random horrible signal from Cypress. Double-left-click Rollback in the upper right-hand corner of your screen. Then scavenge by typing

WalnutScavenge takes a long time but does you the favor of calling the Walnut registered command when it is done.

If you should chance to be running Walnut while the backup system is copying your log file, your Walnut transaction will abort and will not restart until the copy is complete. (The copy may take two minutes for a very long file.) If you leave your Walnut running overnight, you can expect the backup system to copy your log file some time during the night and abort your Walnut transaction.

Do not take a checkpoint on a public machine unless you know how to restore the default checkpoint.

There are two possible stages in which Walnut might be included in a checkpoint: If you use Walnut in almost every session, you might want to load and start the modules for Walnut & Co. and take a checkpoint. If you use Walnut immediately after every Rollback (unlikely but possible), you might want not only to load and start the modules but also to call the registered Walnut procedure.

If you do include Walnut in a checkpoint (either way, by loading and starting the modules or by loading and starting them and calling the registered Walnut procedure) and if there is a new release of Walnut, Cypress, AlpineUser, or TSetter, you must boot your Client volume to get the new release.

A procedure for checkpointing Walnut follows. There are nearly as many ways to achieve approximately this same end as there recipes for authentic Texas chili. The following procedure has been tested, and it includes explanations. Use other procedures at your own risk.

(1) Booting your Client volume causes your User.profile to be read for entries called "PreRun:" and "CommandsFrom:". PreRun specifies a list of .bcd files to load and start. CommandsFrom specifies a series of commands to feed to the UserExec. CommandsFrom has two main advantages over PreRun -- it allows you to specify actions other than loading and starting bcds (such as defining Aliases), and it gives you better error reporting (your commands are right there in the Work Area A Executive; take a look after booting finishes). So the best scheme is to use PreRun to get UserExec loaded and started, then use CommandsFrom for everything else. To do this, change your PreRun entry to:

and add a CommandsFrom entry of the form:

where *** is your name.

Be sure to avoid duplicate PreRun or CommandsFrom entries in your profile. Save the file. (Be sure you have it in your User.df file or whatever file you use to model your identity.)

(2) Make the ***.commands file for yourself and include the lines:

"Run" means "load and start modules"; it does not mean ... uh ... run, exactly. You might want to include other command lines in this file as well, and you might want to load and start the modules for other programs that you use in nearly every session. Save the file and include it in your User.df file or whatever file you use to model your identity.

(3) Left-click Boot (in the upper right-hand corner of the screen) and then double-left-click Client. (Always boot before taking a checkpoint. Do not take a checkpoint on top of an earlier checkpoint. It is not worth discussing the ways in which the system may fail if you ignore this advice.)

(4) Do whatever you like to do to initialize your world, open viewers, etc. A useful trick if you frequently use Walnut after a Rollback is to end this initial session by typing:

with no carriage return. If you really use Walnut every single time you roll back, go ahead and type:

(or "Walnut; WalnutNewMail" or whatever) followed by a carriage return and set up your Walnut viewers to your liking.

(5) Double-left-click Checkpoint (in the upper right-hand corner of the screen).

Again, the best version of Walnut at this moment is on <PostCedar>, but by the time you read this there may be an even better version available elsewhere. Bringover of your User.df (or Mail.df or whatever you use to model your mail world) with lines something like the following:

Imports [Indigo]<PostCedar>Top>Cypress.df Of >
Imports [Indigo]<PostCedar>Top>Walnut.df Of >
Imports [Indigo]<PostCedar>Top>AlpineUser.df Of >
Imports [Indigo]<PostCedar>Top>TSetter.df Of >

will capture any new release.

If you include Walnut in a checkpoint (either way, by loading and starting the modules or by loading and starting them and calling the registered Walnut procedure) and if there is a new release of Cypress, Walnut, AlpineUser, or TSetter, do the Bringover, boot your Client volume, and take a new checkpoint.

See Karen Kolling or Mark Brown.

[Indigo]<Cedar>Documentation>WalnutDoc.*
[Indigo]<Cedar>Documentation>AlpineDoc.*
[Indigo]<Cedar>Documentation>Catalog.*

This is a levelled Tioga document, intended to be read both on line and (during crucial breaks in the action) in hardcopy. Command lines from this document can be secondary-selected and stuffed to a UserExec with appropriate editing. *** and ~~~ are used in command lines to indicate that you must do some editing. None of the command lines end in carriage returns; you must supply your own.

Walnut uses two versions of information about your mail -- the log and the segment (also called the database). The log is the truth. The segment can be generated from the log by a process called scavenging. Entries in your User.profile tell Walnut where to look for your segment and log.

Until recently, Walnut needed for you to have your segment and log on your local disk while it was running. The normal mode was for people to back up their segments and logs on Ivy via entries in their User.df files and periodic SModeling. People who used public machines needed to do Bringovers and SModels of their segments and logs (and millions of weird errors resulted from doing them incorrectly).

Now it is possible for Walnut to use segments and logs on a remote machine. You no longer need to have either segment or log on your local disk, and you no longer need to back them up yourself.

(a) Security and peace of mind. We promise to back up your Walnut log once a day. You may think you are conscientious, but every day people lose their Walnut logs.

(b) Save your valuable time. Bringover of a 1000-message Walnut log takes five minutes on a Dolphin, two on a Dorado.

(c) Storage space -- get all that stuff off your disk and Ivy.

(d) Alpine is the wave of the future.

Ask Karen Kolling for more quota if you need it and for permission to store your Walnut log on Alpine. The name of your Walnut log must be Walnut.DBLog, and it may not be in a subdirectory. She will notify you when you are on the backup list -- do nothing further till she tells you it's OK.

Nothing is going to work correctly unless you have the right versions of Walnut and everything Walnut needs to use a remote segment and log. At the moment, the best version of Walnut is on <PostCedar>, but by the time you read this there may be an even better version available elsewhere. Consider the following instructions, therefore, as a pattern for the sort of thing you will have to do, rather than absolute gospel.

(1) Put in your User.df (or Mail.df or whatever you use to model your mail world) the lines:

(Your mail world might include other things as well.) Save the file.

(2) Do an SModel of that file:

(The &n notation is shorthand for "Tell a UserExec." Throughout this document, substitute appropriately for *** and ~~~.)

(3) Destroy your Walnut viewer or icon if you are currently running Walnut.

(4) Do a BringOver of your User.df (or Mail.df or whatever).

If you use a public machine, be sure to do a BringOver of your User.df (or Mail.df etc.) and be sure to do a Login with your User.profile on the disk every time before starting Walnut.

(5) Double-left-click Rollback in the upper right-hand corner of your screen unless you have Walnut in your checkpoint. (Walnut is not included in checkpoints on public machines.)

If you are on a private machine and you have Walnut in your checkpoint, Boot your Client volume.

(6) Open a new Viewer on this document. (Sigh.)

If you have just rolled back or booted, it should be safe to do:

Be warned that horrible things happen when you run AlpineUserImpls twice. (Getting the message there are unbound imports is not horrible.)

Now use the AlpineCmds set to copy your local Walnut log to Luther.alpine. Substitute your RName for ~~~ in the command line below. Substitute the name of your local Walnut log for *** in the line. (If you use Walnut on a public Dorado, you probably have some kind of personal name for your Walnut log; if you use it on a private machine, your log is probably named simply Walnut.DBLog.)

The copy takes a long time; look at "requests" in the WatchTool if you need reassurance that it's really happening.

If by chance Alpine should go down during the course of doing this copy, delete the partially copied file with AlpineCmds.Delete before re-copying.

Go ahead, check to be sure it's really there -- we're all twitchy that way.

Should return:

Probably you'll also want to set read and modify access to these files to be "owner". Substitute your name for "~~~." Do not substitute your name for "owner," which is a string that Alpine uses intelligently.

Wildcarding filenames does not work for SetReadAccess and SetModifyAccess. The Set*Access commands return TRUE for finding the file whose access you want to change.

In order to use Alpine to store your Walnut segment, you already had the entry:

in your User.profile. Now you need to say also:

(Check to be sure that you don't have duplicate entries.)

EnableTailRewrite: TRUE gives people who use Alpine to store their Walnut logs the safest kind of expunges.

When you save the new .profile, the entries get processed. At this point, Walnut is cut loose from your local log; the only reason not to delete it immediately is to back yourself up for the next day or so in case you have done something so strange that we failed to account for it.

Be warned that if you ever run Walnut in such a way that it cannot read your User.profile it will assume that you use a local segment and log; the only way Walnut knows about the segment and log on Alpine is through your User.profile.

Do

and you should be in business. Ignore the message there are unbound imports.

Why start by doing an expunge? What you need is not the expunge itself but the extra space that it tacks on to the end of your log; without that extra space, Walnut will abort again and again whenever you run it, and you will be irritated by the flashing screen and the delays.

(If you had not been using the latest version of Walnut & Co., other adjustments may be necessary.)

After a day or so of successful Alpine use, delete your local Walnut log. If you have been backing it up yourself, delete the version on Ivy and the entry in your User.df.

You now have Walnut.EnableTailRewrite set to TRUE in your User.profile. The first time after so setting it, double-left-clicking Expunge in Walnut gives you a full expunge and sets an expunged-to-here marker in your Walnut log.

Thereafter, double-left-clicking Expunge usually gives you a short-cut expunge, from that marker to the end of the file. (You get the short-cut expunge unless you have written "too much" log since the last expunge. If you have written "too much" you get the full expunge.)

Double-right-clicking Expunge always gives you a full expunge.

During a full expunge, there is one dangerous period during which the only version of the truth about your mail is stored on your local machine in a file called Walnut.TempLog. If any part of the system fails during that period, the thing to do is to run Walnut again; Walnut is smart enough to realize what happened and complete the expunge correctly. Since a full expunge takes a long time, some people do one right before going home for the night. Fine, but be sure to check next morning that the full expunge completed. If it didn't, run Walnut again.

Various symptoms are possible if Alpine goes down while you are running Walnut. Perhaps the most confusing is that Walnut will completely freeze up. The explanation is simple: a procedure call on Alpine is taking a very long time. Unfortunately, there are other plausible explanations for this behavior. Walnut may, for instance, have a bug in it that produces a local deadlock. You can generally tell the difference by executing an AlpineCmds procedure in the UserExec, such as AlpineCmds.List. If the procedure fails to return within a reasonable interval, you can safely conclude that Alpine is down. (Walking down the hall to look at the Alpine server can also be enlightening, especially if you find an Alpine implementer there slaving away frantically.)

Regardless of the cause, the most graceful way to get out of this state (i.e. get rid of the catatonic Walnut viewers, as well as the UserExec you have just hung up) is to roll back. If enough of your world is still functioning, you may be satisfied with making these viewers iconic.

On rare occasions the Alpine implementors may have to cold-start Alpine (give it amnesia about the recent past in order to get it going again). If you were actively using Alpine just before the crash, the cold start may leave your Walnut.segment with internal inconsistencies. When you run Walnut and your Walnut.segment has been smashed like this, you will get some random horrible signal from Cypress. Double-left-click Rollback in the upper right-hand corner of your screen. Then scavenge by typing

WalnutScavenge takes a long time but does you the favor of calling the Walnut registered command when it is done.

If you should chance to be running Walnut while the backup system is copying your log file, your Walnut transaction will abort and will not restart until the copy is complete. (The copy may take two minutes for a very long file.) If you leave your Walnut running overnight, you can expect the backup system to copy your log file some time during the night and abort your Walnut transaction.

Do not take a checkpoint on a public machine unless you know how to restore the default checkpoint.

There are two possible stages in which Walnut might be included in a checkpoint: If you use Walnut in almost every session, you might want to load and start the modules for Walnut & Co. and take a checkpoint. If you use Walnut immediately after every Rollback (unlikely but possible), you might want not only to load and start the modules but also to call the registered Walnut procedure.

If you do include Walnut in a checkpoint (either way, by loading and starting the modules or by loading and starting them and calling the registered Walnut procedure) and if there is a new release of Walnut, Cypress, AlpineUser, or TSetter, you must boot your Client volume to get the new release.

A procedure for checkpointing Walnut follows. There are nearly as many ways to achieve approximately this same end as there recipes for authentic Texas chili. The following procedure has been tested, and it includes explanations. Use other procedures at your own risk.

(1) Booting your Client volume causes your User.profile to be read for entries called "PreRun:" and "CommandsFrom:". PreRun specifies a list of .bcd files to load and start. CommandsFrom specifies a series of commands to feed to the UserExec. CommandsFrom has two main advantages over PreRun -- it allows you to specify actions other than loading and starting bcds (such as defining Aliases), and it gives you better error reporting (your commands are right there in the Work Area A Executive; take a look after booting finishes). So the best scheme is to use PreRun to get UserExec loaded and started, then use CommandsFrom for everything else. To do this, change your PreRun entry to:

and add a CommandsFrom entry of the form:

where *** is your name.

Be sure to avoid duplicate PreRun or CommandsFrom entries in your profile. Save the file. (Be sure you have it in your User.df file or whatever file you use to model your identity.)

(2) Make the ***.commands file for yourself and include the lines:

"Run" means "load and start modules"; it does not mean ... uh ... run, exactly. You might want to include other command lines in this file as well, and you might want to load and start the modules for other programs that you use in nearly every session. Save the file and include it in your User.df file or whatever file you use to model your identity.

(3) Left-click Boot (in the upper right-hand corner of the screen) and then double-left-click Client. (Always boot before taking a checkpoint. Do not take a checkpoint on top of an earlier checkpoint. It is not worth discussing the ways in which the system may fail if you ignore this advice.)

(4) Do whatever you like to do to initialize your world, open viewers, etc. A useful trick if you frequently use Walnut after a Rollback is to end this initial session by typing:

with no carriage return. If you really use Walnut every single time you roll back, go ahead and type:

(or "Walnut; WalnutNewMail" or whatever) followed by a carriage return and set up your Walnut viewers to your liking.

(5) Double-left-click Checkpoint (in the upper right-hand corner of the screen).

Again, the best version of Walnut at this moment is on <PostCedar>, but by the time you read this there may be an even better version available elsewhere. Bringover of your User.df (or Mail.df or whatever you use to model your mail world) with lines something like the following:

Imports [Indigo]<PostCedar>Top>Cypress.df Of >
Imports [Indigo]<PostCedar>Top>Walnut.df Of >
Imports [Indigo]<PostCedar>Top>AlpineUser.df Of >
Imports [Indigo]<PostCedar>Top>TSetter.df Of >

will capture any new release.

If you include Walnut in a checkpoint (either way, by loading and starting the modules or by loading and starting them and calling the registered Walnut procedure) and if there is a new release of Cypress, Walnut, AlpineUser, or TSetter, do the Bringover, boot your Client volume, and take a new checkpoint.

See Karen Kolling or Mark Brown.

[Indigo]<Cedar>Documentation>WalnutDoc.*
[Indigo]<Cedar>Documentation>AlpineDoc.*
[Indigo]<Cedar>Documentation>Catalog.*