-- WalnutOnAlpineDoc.tioga
-- Last edited by vanLeunen, August 15, 1983 10:08 pm
Storing Your Walnut Information on Alpine
This document is in three sections, the first for people who have never run Walnut at all (and who therefore have neither Walnut.segments nor Walnut.DBLogs), the second for people who have run Walnut with both their Walnut.segments and their Walnut.DBLogs stored locally, the third for people who have run Walnut with their Walnut.segments stored on Alpine and their Walnut.DBLogs stored locally.  Each section is completely self-contained.
If you have never run Walnut at all ...  2-7.
If you have run Walnut with both your segment and your log on your local disk ...  8-14.
If you have run Walnut with your segment on Alpine and your log on your local disk ...  15-21.
If you have never run Walnut at all ...
Using this document  2.
Walnut logs and segments  2.
Why store your Walnut information on Alpine  2-3.
Apply for an Alpine account  3.
Be sure you have correctly installed the right versions of Walnut & Co.  3.
Change your User.profile  4.
Go for it  4.
Setting access  4-5.
Doing expunges  5.
If Alpine goes down  5.
Proper aborts  5-6.
Checkpointing Walnut  6-7.
New releases  7.
If things go wrong  7.  
For further reference  7.
Using this document
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 logs and segments
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.
Why store your Walnut information on Alpine
(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.
Apply for an Alpine account
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.
Be sure you have correctly installed the right versions of Walnut & Co.
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:
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 >
(Your mail world might include other things as well.)  Save the file.
(2)  Do an SModel of that file:

&n SModel /a ***.df
 SModel, Version Of ... etc. etc. etc.
Total elapsed time for SModel 00:03:09.
(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).

&n BringOver /a [Ivy]<~~~>***.df
 BringOver, Version Of ... etc. etc. etc.
Total elapsed time for BringOver 00:02:33.
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.)

Change your User.profile
Add to your User.profile the entries:
Walnut.WalnutSegmentFile: "[Luther.Alpine]<~~~.pa>Walnut.Segment"
Walnut.WalnutLogFile: "[Luther.alpine]<~~~.pa>Walnut.DBLog"
Walnut.EnableTailRewrite: TRUE
(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.
Go for it
Do

&n Walnut; WalnutExpunge
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.
Setting access
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:

&n Run AlpineUserImpls
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.

&n _ AlpineCmds.SetReadAccess[file: "[Luther.alpine]<~~~.pa>Walnut.segment", list: LIST["owner"]]

&n _ AlpineCmds.SetReadAccess[file: "[Luther.alpine]<~~~.pa>Walnut.DBLog", list: LIST["owner"]]

&n _ AlpineCmds.SetModifyAccess[file: "[Luther.alpine]<~~~.pa>Walnut.segment", list: LIST["owner"]]

&n _ AlpineCmds.SetModifyAccess[file: "[Luther.alpine]<~~~.pa>Walnut.DBLog", list: LIST["owner"]]

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.
Doing expunges
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.
If Alpine goes down
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

&n WalnutScavenge
WalnutScavenge takes a long time but does you the favor of calling the Walnut registered command when it is done.
Proper aborts
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.
Checkpointing Walnut
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:
PreRun: BugBane.bcd UserExecutive.bcd
and add a CommandsFrom entry of the form: 
CommandsFrom: ***.commands
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 AlpineUserImpls
Run Cypress
Run TSetter
Run WalnutSend
Run Walnut
"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:

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

&n Walnut
(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).
New releases
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.
If things go wrong
See Karen Kolling or Mark Brown.
For further reference
[Indigo]<Cedar>Documentation>WalnutDoc.*
[Indigo]<Cedar>Documentation>AlpineDoc.*
[Indigo]<Cedar>Documentation>Catalog.*
If you have run Walnut with both your segment and your log on your local disk ...
Using this document  8.  
Walnut logs and segments  8.
Why store your Walnut information on Alpine  8-9.
Apply for an Alpine account  9.
Be sure you have correctly installed the right versions of Walnut & Co.  9-10.
Copy your Walnut information to Luther.alpine  10-11.
Change your User.profile  11.
Go for it  11.
Tidy up  11.
Doing expunges  11-12.
If Alpine goes down  12.
Proper aborts  12.
Checkpointing Walnut  12-13.
New releases  14.
If things go wrong  14.
For further reference  14.
Using this document
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 logs and segments
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.
Why store your Walnut information on Alpine
(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.
Apply for an Alpine account
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.
Be sure you have correctly installed the right versions of Walnut & Co.
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:
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 >
(Your mail world might include other things as well.)  Save the file.
(2)  Do an SModel of that file:

&n SModel /a ***.df
 SModel, Version Of ... etc. etc. etc.
Total elapsed time for SModel 00:03:09.
(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).

&n BringOver /a [Ivy]<~~~>***.df
 BringOver, Version Of ... etc. etc. etc.
Total elapsed time for BringOver 00:02:33.
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.)
Copy your Walnut information to Luther.alpine
If you have just rolled back or booted, it should be safe to do:

&n Run AlpineUserImpls
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.)

&n _ AlpineCmds.Copy[to: "[Luther.alpine]<~~~.pa>Walnut.DBLog", from: "***.DBLog"]
 {does not return a value}

&n _ AlpineCmds.Copy[to: "[Luther.alpine]<~~~.pa>Walnut.segment", from: "***.segment"]
 {does not return a value}
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.

&n _ AlpineCmds.List["[Luther.alpine]<~~~.pa>"]
Should return:

("Walnut.segment", "Walnut.dblog")

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.

&n _ AlpineCmds.SetReadAccess[file: "[Luther.alpine]<~~~.pa>Walnut.segment", list: LIST["owner"]]

&n _ AlpineCmds.SetReadAccess[file: "[Luther.alpine]<~~~.pa>Walnut.DBLog", list: LIST["owner"]]

&n _ AlpineCmds.SetModifyAccess[file: "[Luther.alpine]<~~~.pa>Walnut.segment", list: LIST["owner"]]

&n _ AlpineCmds.SetModifyAccess[file: "[Luther.alpine]<~~~.pa>Walnut.DBLog", list: LIST["owner"]]

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.
Change your User.profile
Add to your User.profile the entries:
Walnut.WalnutSegmentFile: "[Luther.Alpine]<~~~.pa>Walnut.Segment"
Walnut.WalnutLogFile: "[Luther.alpine]<~~~.pa>Walnut.DBLog"
Walnut.EnableTailRewrite: TRUE
(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.
Go for it
Do

&n Walnut; WalnutExpunge
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.)
Tidy up
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.
Doing expunges
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.
If Alpine goes down
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

&n WalnutScavenge
WalnutScavenge takes a long time but does you the favor of calling the Walnut registered command when it is done.
Proper aborts
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.
Checkpointing Walnut
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:
PreRun: BugBane.bcd UserExecutive.bcd
and add a CommandsFrom entry of the form: 
CommandsFrom: ***.commands
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 AlpineUserImpls
Run Cypress
Run TSetter
Run WalnutSend
Run Walnut
"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:

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

&n Walnut
(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).

New releases
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.
If things go wrong
See Karen Kolling or Mark Brown.
For further reference
[Indigo]<Cedar>Documentation>WalnutDoc.*
[Indigo]<Cedar>Documentation>AlpineDoc.*
[Indigo]<Cedar>Documentation>Catalog.*
If you have run Walnut with your segment on Alpine and your log on your local disk ...
Using this document  15.
Walnut logs and segments  15.
Why store your Walnut information on Alpine  16.
Apply for quota and backup on Alpine  16.
Be sure you have correctly installed the right versions of Walnut & Co.  16-17.
Copy your Walnut log to Luther.alpine  17.
Change your User.profile  18.
Go for it  18.
Tidy up  18.
Doing expunges  18-19.
If Alpine goes down  19.
Proper aborts  19.
Checkpointing Walnut  19-20.
New releases  20-21.
If things go wrong  21.
For further reference  21.
Using this document
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 logs and segments
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.

Why store your Walnut information on Alpine
(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.
Apply for quota and backup on Alpine
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.
Be sure you have correctly installed the right versions of Walnut & Co.
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:
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 >
(Your mail world might include other things as well.)  Save the file.
(2)  Do an SModel of that file:

&n SModel /a ***.df
 SModel, Version Of ... etc. etc. etc.
Total elapsed time for SModel 00:03:09.
(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).

&n BringOver /a [Ivy]<~~~>***.df
 BringOver, Version Of ... etc. etc. etc.
Total elapsed time for BringOver 00:02:33.
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.)
Copy your Walnut log to Luther.alpine
If you have just rolled back or booted, it should be safe to do:

&n Run AlpineUserImpls
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.)

&n _ AlpineCmds.Copy[to: "[Luther.alpine]<~~~.pa>Walnut.DBLog", from: "***.DBLog"]
 {does not return a value}
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.

&n _ AlpineCmds.List["[Luther.alpine]<~~~.pa>"]
Should return:

("Walnut.segment", "Walnut.dblog")
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.

&n _ AlpineCmds.SetReadAccess[file: "[Luther.alpine]<~~~.pa>Walnut.segment", list: LIST["owner"]]

&n _ AlpineCmds.SetReadAccess[file: "[Luther.alpine]<~~~.pa>Walnut.DBLog", list: LIST["owner"]]

&n _ AlpineCmds.SetModifyAccess[file: "[Luther.alpine]<~~~.pa>Walnut.segment", list: LIST["owner"]]

&n _ AlpineCmds.SetModifyAccess[file: "[Luther.alpine]<~~~.pa>Walnut.DBLog", list: LIST["owner"]]

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.
Change your User.profile
In order to use Alpine to store your Walnut segment, you already had the entry:
Walnut.WalnutSegmentFile: "[Luther.Alpine]<~~~.pa>Walnut.Segment"
in your User.profile.  Now you need to say also:
Walnut.WalnutLogFile: "[Luther.alpine]<~~~.pa>Walnut.DBLog"
Walnut.EnableTailRewrite: TRUE
(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.
Go for it
Do

&n Walnut; WalnutExpunge
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.)
Tidy up
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.
Doing expunges
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.
If Alpine goes down
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

&n WalnutScavenge
WalnutScavenge takes a long time but does you the favor of calling the Walnut registered command when it is done.
Proper aborts
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.
Checkpointing Walnut
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:
PreRun: BugBane.bcd UserExecutive.bcd
and add a CommandsFrom entry of the form: 
CommandsFrom: ***.commands
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 AlpineUserImpls
Run Cypress
Run TSetter
Run WalnutSend
Run Walnut
"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:

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

&n Walnut
(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).
New releases
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.
If things go wrong
See Karen Kolling or Mark Brown.
For further reference
[Indigo]<Cedar>Documentation>WalnutDoc.*
[Indigo]<Cedar>Documentation>AlpineDoc.*
[Indigo]<Cedar>Documentation>Catalog.*
�Ê"˜J˜Jš
œ5˜5Ihead2š
Ïx)˜)Iblock˜¸K˜-K˜XK˜^
head˜'Iindent˜N˜N˜1N˜N˜KN˜N˜
N˜N˜N˜N˜N˜N˜N˜N˜—˜N•Index"***" 2403 VersionStamp "jnp_"
˜‹—˜N˜¢N˜•N˜Â
—˜+Nš
Ϭ
˜¨
Nš
œw˜wN˜?N˜&—˜N˜Š—˜GNš
œ§˜§š
œ]˜]N˜.N˜-N˜1N˜.—N˜E˜J– "***" 4769 VersionStamp "p^Io'"
šÏbœ˜Jš
œN˜N—N–"***" 4964 VersionStamp "jQ{."
šœžœr˜z˜=J– "***" 5396 VersionStamp "1i;^L"
šœ
žœ˜!Jš
œT˜T—Nš
œ¸
˜¸
N˜µ
N˜`N˜1I	pagebreak˜—˜˜%Nš
œA˜ANš
œ;˜;Nš
œ˜—Nš
œ9˜9Nš
œk˜kN˜:N˜ê
—˜	˜Jšžœ˜—Nšœ3Ïiœ˜ONš
œ–˜–—˜˜§
Jšœ
žœ˜—Nšœ`Ÿœ˜‹
˜{Jšœ
žœ_˜bJšœ
žœ]˜`Jšœ
žœa˜dJšœ
žœ`˜c—N˜¥
—˜Nš
ϊ
˜ä
Nš
œ’˜’Nš
œ>˜>N˜°—˜NšœÙ
Ïeœ¢˜ÿNš
œœ˜œ˜ùJšžœ˜—Nš
œq˜q—˜
N˜‡—˜N˜cN˜†N˜©N˜�š
œµ˜µNš
œ%˜%—š
œ*˜*N– "***" 12849 VersionStamp "}cNX"
š
œ˜—N–""***" 12868 VersionStamp "^GT^I?"
š
œ˜N˜¸
–!"***" 13085 VersionStamp "'Pe^S"
˜CNš
œ˜Nš
œ˜Nš
œ˜Nš
œ˜Nš
œ
˜
—NšœB œ›˜âNš
œ©˜©˜´
Jšžœ˜—˜fJšžœ˜
—Nš
œu˜uNš
œQ˜Q—˜š
œ˜˜˜N˜.N˜-N˜1N˜.—N˜N˜³—˜N˜ —˜N˜x—˜QN˜N˜N˜1N˜N˜NN˜5N˜N˜N˜N˜N˜N˜N˜N˜N˜N˜—˜N– "***" 15560 VersionStamp "jnp_"
˜‹—˜N˜¢N˜•N˜Â
—˜+Nš
Ϭ
˜¨
Nš
œw˜wN˜?N˜&—˜N˜Š—˜GNš
œ§˜§š
œ]˜]N˜.N˜-N˜1N˜.—N˜E˜J– "***" 4769 VersionStamp "p^Io'"
šžœ˜Jš
œN˜N—N–"***" 4964 VersionStamp "jQ{."
šœžœr˜zN˜M˜=J– "***" 5396 VersionStamp "1i;^L"
šœ
žœ˜!Jš
œT˜T—Nš
œ¸
˜¸
N˜µ
N˜`N˜1—˜-˜@Jšœ
žœ˜—Nšœ`Ÿœ˜‹
–@"***" 19239 VersionStamp "YeKt"
"***" 19307 VersionStamp "YeKt"
˜ŠJ–#"***" 19638 VersionStamp "Z^K^V^N"
šœ
žœP˜SJš
œ˜J–!"***" 19751 VersionStamp "U(8^L"
šœ
žœT˜WJš
œ˜—N˜wNš
œ—
˜—
˜NJšœ
žœ-˜0—˜Jš
œ#˜#—L˜˜Ò
Jšœ
žœ_˜bJšœ
žœ]˜`Jšœ
žœa˜dJšœ
žœ`˜c—N˜¥
—˜˜%Nš
œA˜ANš
œ;˜;Nš
œ˜—Nš
œ9˜9Nš
œk˜kN˜©N˜ê
—˜	˜Jšžœ˜—Nšœ3Ÿœ˜ONš
œ—˜—N˜c—˜N˜½
—˜Nš
ϊ
˜ä
Nš
œ’˜’Nš
œ>˜>N˜°—˜NšœÙ
 œ¢˜ÿNš
œœ˜œ˜ùJšžœ˜—Nš
œq˜q—˜
N˜‡—˜N˜cN˜†N˜©N˜�š
œµ˜µNš
œ%˜%—š
œ*˜*N– "***" 27659 VersionStamp "}cNX"
š
œ˜—N–""***" 27678 VersionStamp "^GT^I?"
š
œ˜N˜¸
–!"***" 27895 VersionStamp "'Pe^S"
˜CNš
œ˜Nš
œ˜Nš
œ˜Nš
œ˜Nš
œ
˜
—NšœB œ›˜âNš
œ©˜©˜´
Jšžœ˜—˜fJšžœ˜
—Nš
œu˜uNš
œQ˜QO˜—˜Nš
œ˜˜˜N˜½
N˜N˜³—˜N˜ —˜N˜x—˜VN˜N˜N˜0N˜)N˜ON˜*N˜N˜N˜N˜N˜N˜N˜N˜N˜N˜—˜N–#"***" 30374 VersionStamp "Jnp\177"
˜�—˜N˜¢N˜•N˜Â
O˜—˜+Nš
Ϭ
˜¨
Nš
œw˜wN˜?N˜&—˜$N˜¥—˜GNš
œ§˜§š
œ]˜]N˜.N˜-N˜1N˜.—N˜E˜J– "***" 4769 VersionStamp "p^Io'"
šžœ˜Jš
œN˜N—N–"***" 4964 VersionStamp "jQ{."
šœžœr˜zN˜M˜=J– "***" 5396 VersionStamp "1i;^L"
šœ
žœ˜!Jš
œT˜T—Nš
œ¸
˜¸
N˜µ
N˜`N˜1—˜%˜@Jšœ
žœ˜—Nšœ`Ÿœ˜‹
˜†Jšœ
žœP˜SJš
œ˜—N˜sNš
œ“
˜“
˜KJšœ
žœ-˜0—˜Jš
œ#˜#—˜Ò
Jšœ
žœ_˜bJšœ
žœ]˜`Jšœ
žœa˜dJšœ
žœ`˜c—N˜¥
—˜˜ONš
œA˜A—˜0Nš
œ;˜;Nš
œ˜—Nš
œ9˜9Nš
œk˜kN˜›N˜ê
—˜	˜Jšžœ˜—Nšœ3Ÿœ˜NNš
œ—˜—N˜c—˜N˜¬
—˜Nš
ϊ
˜ä
Nš
œ’˜’Nš
œ>˜>N˜°—˜NšœÙ
 œ¢˜ÿNš
œœ˜œ˜ùJšžœ˜—Nš
œq˜q—˜
N˜‡—˜N˜cN˜†N˜©N˜�š
œµ˜µNš
œ%˜%—š
œ*˜*Nš
œ˜—Nš
œ˜N˜¸
˜CNš
œ˜Nš
œ˜Nš
œ˜Nš
œ˜Nš
œ
˜
—NšœB œ›˜âNš
œ©˜©˜´
Jšžœ˜—˜fJšžœ˜
—Nš
œu˜uNš
œQ˜Q—˜Nš
œ˜˜˜N˜½
N˜N˜³—˜N˜ —˜N˜x——…—·<Ãd