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.