1/7/91  forum transaction specifiers

Transaction specifiers are used by the list, print, write, delete,
retrieve, reset, and reply requests to refer to transactions in a
meeting.  They are composed of transaction numbers, keywords, the
arithmetic operators + and -, person_ids, control argument selections,
and qedx-type regular expressions.  In addition, the keywords may be
used as requests and active requests to return transaction numbers.


Specifier Classes:
Transaction specifiers are divided up into four classes: transaction
numbers and keywords, regular expressions, person_ids, and date ranges.
In addition, there are control arguments which additionally restrict
which transactions are selected. If specifiers for more than one class
are present, a transaction must satisfy at least one specifier in each
class.  For instance, the request line:

      list 100:last -from Pattin -after 10/5/82 -subject /FOO/

will select all transactions numbered higher than 100 which were
entered by the participant Pattin after 10/5/82 which contain the
string "FOO" in the subject.


Transaction numbers and keywords:
Transaction numbers are integers asssigned by forum when it
enters a transaction into the proceedings.  Transactions may be
linked together (through the use of the 'reply' request) and may
be addressed using this linking information.  There  are  several
keywords which can be used to refer to transactions symbolically:


   unprocessed, u
     refers to the unprocessed transaction.
   first, f
     refers to the first transaction in the proceedings.
   last, l
     refers to the last transaction in the proceedings.
   next, n
     refers to the transaction immediately after the current
     transaction.
   previous, p
     refers to the transaction immediately before the current
     transaction.
   current, c
     refers to the transaction last listed, printed, written,
     or reset to.


   highest, last_seen
     refers to the highest-numbered transaction printed or written.
   all, a
     refers to all transactions (equivalent to first:last).
   firstref, fref
     refers to the first transaction in the current chain of
     transactions.
   lastref, lref
     refers to the last transaction in the current chain of
     transactions.
   nextref, nref
     refers to the next transaction in the current chain of
     transactions.


   previousref, pref
     refers to the previous transaction in the current chain of
     transactions.
   beforeref, bref
     refers to all previous transactions in the current transaction
     chain.
   restref, rref
     refers to all remaining transactions in the current transaction
     chain.
   allref, aref
     refers to all transactions in the current chain of transactions.


For the following group, 'seen' means that the transaction has been
printed, written, or explicitly marked as seen by the switch_on request.

   seen
     refers to all transactions marked as having been seen.
   first_seen, fs
     refers to the first transaction marked as having been seen.
   last_seen
     refers to the highest-numbered transaction marked as having
     been seen.
   next_seen, ns
     refers to the next transaction after the current one which is
     marked as seen.
   previous_seen, ps
     refers to the first transaction before the current one which is
     marked as seen.


   new
     refers to transactions entered after your last_seen transaction
     which were not entered by you.
   unseen
     refers to all transactions not marked as having been seen.
   first_unseen, fu
     refers to the first transaction not marked as having been seen.
   last_unseen, lu
     refers to the highest-numbered transaction not marked as having
     been seen.
   next_unseen, nu
     refers to the next transaction after the current one which is
     not marked as seen.
   previous_unseen, pu
     refers to the first transaction before the current one which is
     not marked as seen.


There is also a special transaction specifier "chairman_message"
("cmsg") which may be used with the "print", "write", and "delete"
requests to denote the chairman's greeting message.

All keywords except for 'unproc', 'all', 'new', 'restref', 'allref',
'seen', and 'unseen' may be used in place of actual transaction
numbers, and may be combined with either of the simple operators '+' or
'-', as in 'l-4' 'nref+1' and so on.  Leading '+' and '-' are used to
reference from the current transaction, '-4' is the same as
'current-4'.  A range of transactions may be specified by two
transaction numbers or keywords separated by a colon (:), as in
'first:last', 'c-3:nref' and so on.


Usage of keywords as requests:
All of the keywords except for 'unprocessed' and 'chairman_message' may
be used as requests and active requests.  They return a list of the
transaction numbers that the keyword represents.  All of the keywords
that use reference chains and the keywords 'next', 'previous',
'next_seen', 'previous_seen', 'next_unseen', and 'previous_unseen' may
be given an argument to use as the 'current' transaction.  Thus, 'aref
4' would return a list of all transactions which reference transaction
4.


Regular expressions:
Simple regular expressions are character strings enclosed in slashes
(/).  The control arguments '-subject (-sj)' and '-text (-tx)' may be
given immediately before a regexp.  They specify that matching is to be
done only against the subject or text respectively.  By default,
matching is done against both the subject and the text.  For example:

   /FORTRAN/

specifies all transactions which contain the string 'FORTRAN'.  The
null regexp "//" signifies that last regular expression used.

Because of the syntax of the request language, regular expressions
which contain special characters such as space, quote, and parentheses
must be quoted.


Person_ids:
The -from person_id (-fm personid) can be supplied in order to indicate
that only transactions authored by the person identified by the
person_id be selected.  The selection:

      -from York

selects all transactions entered by the participant York.


Date/Time Selection:
The following control arguments are available to select transactions
based on the date_time that the transaction was entered.  The strings
DT, DT1, and DT2 are standard Multics date_time strings acceptable to
the convert_date_to_binary_ subroutine.  Type "..  help
date_time_strings.gi" for information on date_time strings.

-after DT, -af DT
   selects all transactions entered on or after the the date specified.
   The time of day is ignored.
-after_time DT, -aft DT
   selects all transactions entered after the date_time specified.


-before DT, -be DT
   selects all transactions entered before the date specified. The time
   of day is ignored.
-before_time DT, -bet DT
   selects all transactions entered before the date_time specified.
-between DT1 DT2, -bt DT1 DT2
   selects all transactions entered between the dates specified,
   inclusive.  The times of day are ignored.
-between_time DT1 DT2, -btt DT1 DT2
   selects all transactions entered between the date_times specified,
   inclusive.
-date DT, -dt DT
   selects all transactions entered on the day specified.


Notes:
Several requests will operate on deleted transactions when the
-include_deleted or -only_deleted control arguments are used. Forum
considers only those transactions which the user can read, so for
participants other than the chairman, only deleted transactions entered
by that participant are considered.


Care must be exercised when using the -only_deleted control argument
in combination with specifier keywords.  The keywords are evaluated
among the deleted transaction only, thus

  last -only_deleted

selects the last deleted transaction that the user may read, but

  last-30:last -only_deleted

selects all deleted transactions from 30 transactions before tha last
deleted transaction.  It does not select all deleted transactions from
the last 30 transactions in the meeting.

Type 'help trans_specs_ex' for examples of transaction specifiers.
