WalnutKeyboardDoc.tioga
Swinehart, November 4, 1992 11:44 am PST
Willie-s, May 11, 1992 8:22 pm PDT
WalnutKeyboard
Dan Swinehart
© Copyright 1989, 1992 Xerox Corporation. All rights reserved.
Abstract: WalnutKeyboard provides operations for reading Walnut mail through a Command Tool interface (useful for remote access via methods such as NetCommander). A related operation provide a "more" command analogous to the Unix "more".
Created and Maintained by: Dan Swinehart:PARC:Xerox
Keywords: mail, remote access, Command Tool, Walnut
XEROX  Xerox Corporation
   Palo Alto Research Center
   3333 Coyote Hill Road
   Palo Alto, California 94304

For Internal Xerox Use Only
1. WalnutKeyboard
Syntax
Parameters:
<set> := <message set name> | <database nickname>.<message set name>1
<source> := <set> | from <set> | <source> <range> | <source> <filter> | it2 | them2
<destination> := to <set>
<message number> := <integer>3
<range> := <message number> | [ <message number> .. <message number> ]
<filter> := with <all the remaining text in the command line>4 |
all5 | read5 | unread5 | transferred5 | before <date>11 | after <date>11 | <filter>*
Commands:
WKDBs -- prints the registered Walnut databases
WKSets <database nickname>6 -- prints the messages sets within the named database
WKListTOC <source>7,8 -- prints the table of contents of the named message set
WKSameTOC9 <source> -- prints the table of contents of the named message set
WKDisplay <source> -- displays the contents of message or range of messages
WKMove <source> <destination>10 -- moves the indicated messages to the destination set
WKCopy <source> <destination>10 -- copies the indicated messages to the destination set
WKDelete <source> -- copies the indicated messages to the destination set
WKTransfer <source> <destination> -- adds a copy of the message(s) to the destination message
   set, in any open database
WKPoll -- pushes the "new mail" button, if any active Walnut viewer has one.
WKLogin -- see discussion
WKSelect <source> <destination> -- set the default values
   to be used for message sets and/or database names
WKFlush -- Flushes all message set caches.
Walnutkeyboard <nickname> <root file name> -- registers a new Walnut database
Notes:
1. Message set names may be quoted ("quoted"). Therefore, message sets with "." or "-" in their names may be represented. Also, message sets whose names are also keywords can be differentiated in this way.
2. WalnutKeyboard remembers the <source> value or values for the last completed command. Either of these keywords will cause it or them to be used again for the current one. You can include additional filter values as modifiers to the previous range.
3. This number represents the index of the message within its message set, as listed by the most recent WKListTOC command. Recent new mail, WKMove/Copy, or Walnut window activity can invalidate these indices without warning.
4. See the filter discussion later for usage. The "with" parameter must appear as the last parameter in the command line.
5. See the filter discussion for usage.
6. Defaults are supplied for most commands. The currently selected (via WKSelect) source and destination will be used if those values are omitted. For all but the Move, Copy, and Delete commands, the entire message set will be assumed as the range. Whenever a filter is specified, the entire message set is the default range for all commands.
7. With the exception of the "with" filter, which must appear last, parameters are self-identifying and may appear in any order.
8. If a range is given, only messages within that range are listed, displayed, or moved; otherwise, the entire message set is enumerated. Only those messages matching the filter, if supplied, will be printed.
9. WalnutKeyboard caches (remembers) the list of messages within each message set. It will forget its cached values, and consult Walnut again to refresh them, only when you issue the WKListTOC command. This permits you to perform a series of Display, Move, Copy, and Delete operations based on the message indices provided in the last TOC listing. It is also much faster than consulting Walnut. WKSameTOC provides a new TOC listing without refreshing. Note: There's evidence that since the port to PCedar, neither operation will refresh the message set cache; use WKFlush to forget everything if nothing else works.
10. For Move and Copy commands, both message sets must reside in the same database (enforced). Use WKTransfer to move between databases.
11. Date should be a double-quoted date string in some easily recognized format. These commands are useful in conjunction with WKTransfer, in order to move between databases only those messages with message ID's earlier or later than the specified day (times are ignored). E.g., WKTransfer after "6/30/92" from ms1 to db2.ms1. Only the last "before" or "after" specification is honored. You can't use both to get "between."
Defaults:
Initial root file name: root file name defined by the User Profile entry "Walnut.WalnutRootFile.
Initial database nickname (corresponding to initial root file name): "default".
Initial source and destination message sets: "Active".
Discussion
This document is written as if the purpose of WalnutKeyboard and the use of its commands were obvious. Well, OK: the reason it was written was to permit one to dial up one's Cedar machine and read one's mail. If you can Telnet (TCP/IP or XNS) to a RemoteCommander within a Cedar world running Walnut, you can get to your Walnut mail. A few points need to be discussed, however.
WalnutKeyboard permits the examination of any active Walnut databases—any for which Walnut viewers currently exist within the Cedar world you've connected to. (Walnut is too tied up with Viewers to have permitted operation in non-viewers worlds.) To avoid the need to identify lengthy root file names for each command, there is a registration process that associates a "nickname" with the root file name of every database to be examined. Since I have a Walnut database containing older messages, I need to type "WalnutKeyboard old /tilde/swinehart/oldmail/walnut.root". The default database is nicknamed "default" and is associated with the walnut database identified in the user profile.
At the moment, this process of name registration and the process of creating the associated active Walnut viewer on the workstation are separate -- the user must do both before the database is available.
All of the query commands permit full qualification of database and message set names. However, it is also possible to select a database, a source message set name, and a destination message set name, that will subsequently be used if the corresponding parameter is omitted. Use the WKSelect command for this. When WalnutKeyboard is started, the selected database is "default" (your ordinary root database) and the selected source and destination message set is "Active".
The "with" filter provides a sort of "poor man's Wallaby." As WKListTOC or WKSameTOC enumerate a table of contents, they print out only those table of contents entries that include the entire filter text as a substring. This comparison is case-insensitive. The user may then inspect these messages by referring to their message numbers in WKDisplay commands.
The other filters further limit the presentation of TOC entries. "unread" includes only messages that you have not yet read. Conversely, "read" includes only those that you have read. I don't know what happens when you specify both. "transferred" includes only those that have been the source of a transfer to another database using WKTransfer -- useful as the argument of a WKDelete, after a wholesale transfer. I was too chicken to make the delete automatic. "all" specifies the entire message set as a range, even in commands where the entire range is not the default.
Walnut, if so directed, checks for new mail and monitors the need to push the Retry or Quit buttons at approximately ten minute intervals. WKPoll will check for new mail on demand.
The normal way of using WalnutKeyboard is to user XNS chat or TCP/IP telnet to connect to a NetCommander listener running in a Cedar Viewers (X or Raw) world. See the NetCommander documentation for more information. It includes a rudimentary security provision, so the facility isn't too dangerous.
The "WK" prefix preceeds all the WalnutKeyboard commands in order to group them for the "?" command. You may wish to define more pleasing aliases for them.
Acknowledgements
Walnut was real easy to drive from this program; most of the credit for that goes to Willie-Sue Orr. I wrote the first version of this program, but Rick Beach added the original version of the "with" filter, cleaned up some of the command syntax and error handling, and has provided other useful suggestions and provocations, most of which prompted additional improvements.
2. More
Syntax
More -- enables the <CR> and <DEL> interruption options, discussed below.
More <number> -- pauses every <number> lines, as if <CR> had been used to suspend printing.
Discussion
"More" is a Command Tool filter. This means that the user invokes it, along with some other command, in such a way that the output of that other command serves as input to "More", which then provides its output to the command tool or to some further filter.
Typical usage might be:
WKListToc Old.Active|More
or
WKDisplay 15|More 10
The first form simply enables the user-interrupt facility described below. The second form enables user interrupts as well as setting a ten-line limit on the number of lines that will be printed without pausing for user confirmation. Thus, a small display device may be used to read extensive output from a program invoked from the Command Tool.
Whenever output has been suspended, the user may type <CR> to resume output, or <DEL> to abort the command.
In order to suspend output, the user types <CR>. It may take a few lines before printing ceases. In order to abort the command, the user types <DEL>. Sometimes suspending output (by waiting for the next automatic pause or by typing <CR>) before issuing the <DEL> works better.
N.B.: This command is implemented quite naively. Its character-at-a-time handling of the primary input and output streams is guaranteed to slow things down, and in particular can interact poorly with network terminal access protocols.