-- HowToUseAlpine.msg

Subject: Instructions for using Alpine
To: MBrown.pa
cc: MBrown.pa

Welcome to the community of Alpine users!

The Alpine server is called "Luther.alpine".

The Alpine server has a notion of file ownership, and enforces disk quotas on a per-owner basis.  An owner is denoted by an RName, e.g. "MBrown.pa".  To create a personal file on the Alpine server, your RName must be established as an owner, and (unlike IFS!) the act of creating the file must not put you over your quota.  The fact that I am sending you this message probably means that I have already established you as an owner.  If you run out of space, I may be able to increase your quota.

The Alpine server does not provide text names for files.  However a simple package (run on the workstation) provides the equivalent of the Alto directory system on a per-owner basis.  A typical file name is "[Luther.alpine]<MBrown.pa>Walnut.segment".

The Alpine server does not have a Telnet "executive" interface (you can't talk to it via Chat).  It also does not support the FTP protocol (you can't talk to it via the FileTool).  However a simple package allows you to copy files to and from Alpine, delete files, list your directory, and determine how far you are from exceeding your Alpine disk quota.  The package is callable from the interpreter.  Here is a sample session:

&1 ← AlpineCmds.List["[Luther.alpine]<MBrown.pa>"]
("List.mesa", "Rope.mesa", "Walnut.segment")

&2 ← AlpineCmds.Delete["[Luther.alpine]<MBrown.pa>Rope.mesa"]
{does not return a value}

&3 ← AlpineCmds.List["[Luther.alpine]<MBrown.pa>*.mesa"]
("List.mesa")

&4 ← AlpineCmds.Copy[to: "[Luther.alpine]<MBrown.pa>Rope.mesa", from: "Rope.mesa"]
{does not return a value}

&5 ← AlpineCmds.Copy[to: "Walnut.segment", from: "[Luther.alpine]<MBrown.pa>Walnut.segment"]
{does not return a value}

&6 ← AlpineCmds.ReadQuota["[Luther.alpine]<MBrown.pa>"]
[pageLimit: 6000, spaceInUse: 3130]

Note that the List procedure allows '* to be embedded within the "simple" file name only, not within the server name or the owner name.

Cypress knows how to access files stored on Alpine.  This means that you can store your Walnut database ("Walnut.segment"), and other databases, on Alpine.  You cannot usefully store your Walnut log on Alpine because FileIO cannot create a stream to Alpine.


Recommended operating procedures:

1) "Bringover /a /p <PreCedar>Top>AlpineUser".

2) "Run AlpineUserImpls".

3) If your Walnut database is not yet on Alpine, do
  ← AlpineCmds.Copy[to: "[Luther.alpine]<MBrown.pa>Walnut.segment", from: "Walnut.segment"].  Then change MBrown.profile to say Walnut.WalnutSegmentFile: "[Luther.Alpine]<MBrown.pa>Walnut.segment", and Walnut.WalnutLogFile: "Walnut.DBLog".

4) "Walnut".  The Walnut control viewer should appear.


Notes:

Do NOT checkpoint after performing "Run AlpineUserImpls".  After a rollback, you must "Run AlpineUserImpls" before invoking any Walnut command.  You may include Walnut in your checkpoint by performing "Run Walnut" instead of "Walnut" before taking the checkpoint.  Then perform "Run AlpineUserImpls; Walnut" after a rollback.

If Alpine is unavailable for some reason, it is easy to return to using the local disk for your Walnut database.  Just change your profile to say Walnut.WalnutSegmentFile: "Walnut.segment" and rollback.  After an Expunge, you must execute ← AlpineCmds.Copy[to: "Walnut.segment", from: "[Luther.alpine]<MBrown.pa>Walnut.segment"], otherwise you'll have to scavenge in order to use the local disk again.

One symptom of an Alpine crash is a total lack of response in Walnut.  There may be no uncaught signal.  The reason is that RPC does not time out long calls.  For now, the only way to be sure is to go look at the server (its terminal is in the nursery; to wake up the display hold the space bar down for a second or two).
 
The procedures in AlpineCmds are not designed to handle exceptional cases.  For instance, if you exceed your quota with Copy, you will get an uncaught signal.  When you get an uncaught signal, try to understand whether it represents a problem of this sort (the argument to the signal is often descriptive).  If not or you can't tell, please call me.

Cypress and Walnut are not yet designed to handle Alpine exceptions.  The most frequently occurring Alpine error is Unknown [transID or openFileID]; this signifies a transaction abort that was not handled gracefully.  This may mean a server crash or may mean a spontaneous abort (due to lock conflict or other reason.)  You will have to roll back.


Our warranty:

It is our hope that even in its present embryonic state, Alpine provides a useful service to its clientele.  We shall make reasonable efforts to make the Alpine server available at all times, and to preserve the files that you store on the Alpine server.  However, we may find it convenient to lose files rather than recover them with bit-tweezers, and we reserve the right to do so until further notice.

	--mark