Contents 
 1 Introduction 
   1.1 Hello . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
   1.2 What's in the Topics  . . . . . . . . . . . . . . . . . . . 1
   1.3 The Registered Version  . . . . . . . . . . . . . . . . . . 2
   1.4 Format of this manual . . . . . . . . . . . . . . . . . . . 2
   1.5 Setting the Programs Up . . . . . . . . . . . . . . . . . . 3
   1.6 Using the Package . . . . . . . . . . . . . . . . . . . . . 3
     1.6.1 From Cix  . . . . . . . . . . . . . . . . . . . . . . . 3
     1.6.2 Offline . . . . . . . . . . . . . . . . . . . . . . . . 3
 2 Online Help 
   2.1 General Help  . . . . . . . . . . . . . . . . . . . . . . . 5
   2.2 Specific Help . . . . . . . . . . . . . . . . . . . . . . . 5 
 3 The Conferencing System 
   3.1 What's Available  . . . . . . . . . . . . . . . . . . . . . 6
     3.1.1 On Cix Itself . . . . . . . . . . . . . . . . . . . . . 6
     3.1.2 Locally on CixRead  . . . . . . . . . . . . . . . . . . 7
   3.2 Moving Between Conferences and Topics . . . . . . . . . . . 8
   3.3 Reading Messages and Moving Within a Topic  . . . . . . . . 10
   3.4 Replying to Messages in Topics, and posting your own  . . . 14
   3.5 Finding Information in Topics . . . . . . . . . . . . . . . 15
   3.6 Files (flists)  . . . . . . . . . . . . . . . . . . . . . . 16
   3.7 Housekeeping  . . . . . . . . . . . . . . . . . . . . . . . 17
                   
                                   i

   3.8 Miscellaneous . . . . . . . . . . . . . . . . . . . . . . . 20
     3.8.1 External message storage  . . . . . . . . . . . . . . . 20
     3.8.2 Who . . . . . . . . . . . . . . . . . . . . . . . . . . 20
     3.8.3 Conference descriptions . . . . . . . . . . . . . . . . 20
     3.8.4 Participant lists . . . . . . . . . . . . . . . . . . . 21
     3.8.5 Moderating  . . . . . . . . . . . . . . . . . . . . . . 22
   3.9 Tokens  . . . . . . . . . . . . . . . . . . . . . . . . . . 23
   3.10 Ranges . . . . . . . . . . . . . . . . . . . . . . . . . . 24
 4 Electronic Mail 
   4.1 Reading Mail  . . . . . . . . . . . . . . . . . . . . . . . 25
   4.2 Replying and Sending Mail . . . . . . . . . . . . . . . . . 27
   4.3 Housekeeping  . . . . . . . . . . . . . . . . . . . . . . . 29
     4.3.1 Mail Flags  . . . . . . . . . . . . . . . . . . . . . . 29
   4.4 Mailboxes . . . . . . . . . . . . . . . . . . . . . . . . . 32
   4.5 Miscellaneous . . . . . . . . . . . . . . . . . . . . . . . 32
     4.5.1 Inbaskets and Outbaskets  . . . . . . . . . . . . . . . 32
     4.5.2 Hardcopy  . . . . . . . . . . . . . . . . . . . . . . . 33
     4.5.3 Filing  . . . . . . . . . . . . . . . . . . . . . . . . 33
     4.5.4 Binmail Directories . . . . . . . . . . . . . . . . . . 34
     4.5.5 Returning to the Conferencing System  . . . . . . . . . 34
     4.5.6 Mail Aliases  . . . . . . . . . . . . . . . . . . . . . 34 
 5 Miscellaneous 
   5.1 Quitting CixRead  . . . . . . . . . . . . . . . . . . . . . 35
   5.2 Running Other Programs  . . . . . . . . . . . . . . . . . . 35
   5.3 Upload Script Control . . . . . . . . . . . . . . . . . . . 36
   5.4 Resumes . . . . . . . . . . . . . . . . . . . . . . . . . . 37
   5.5 System Status . . . . . . . . . . . . . . . . . . . . . . . 37
   5.6 Editing files . . . . . . . . . . . . . . . . . . . . . . . 37
   5.7 Menu bar and Desk Accessories . . . . . . . . . . . . . . . 38
   5.8 Pausing . . . . . . . . . . . . . . . . . . . . . . . . . . 38
   5.9 Shelling out  . . . . . . . . . . . . . . . . . . . . . . . 38

                                   ii 

   5.10 Searching files  . . . . . . . . . . . . . . . . . . . . . 39
   5.11 Notification of downloads of resumes, flists, mail, etc  . 39
   5.12 Selecting alternative message bases  . . . . . . . . . . . 40
   5.13 Message Caching  . . . . . . . . . . . . . . . . . . . . . 40
   5.14 Deferring Commands . . . . . . . . . . . . . . . . . . . . 41
   5.15 Suspending Topics  . . . . . . . . . . . . . . . . . . . . 41 
 6 Customising CixRead 
   6.1 Environmental Variables . . . . . . . . . . . . . . . . . . 42
   6.2 The Option Menu . . . . . . . . . . . . . . . . . . . . . . 44
     6.2.1 Available options . . . . . . . . . . . . . . . . . . . 44
   6.3 Function Keys . . . . . . . . . . . . . . . . . . . . . . . 50
     6.3.1 The Dialog Box  . . . . . . . . . . . . . . . . . . . . 50
     6.3.2 Setting Keys from the Command Line  . . . . . . . . . . 50
     6.3.3 Parameters  . . . . . . . . . . . . . . . . . . . . . . 51
     6.3.4 Auto-executing Function Keys  . . . . . . . . . . . . . 51
   6.4 Command Aliasing  . . . . . . . . . . . . . . . . . . . . . 52
     6.4.1 Parameters  . . . . . . . . . . . . . . . . . . . . . . 53
     6.4.2 Overriding Aliases  . . . . . . . . . . . . . . . . . . 53
   6.5 CixRead Scripts . . . . . . . . . . . . . . . . . . . . . . 54
     6.5.1 Running a script  . . . . . . . . . . . . . . . . . . . 54
     6.5.2 Commands  . . . . . . . . . . . . . . . . . . . . . . . 54
     6.5.3 Parameters  . . . . . . . . . . . . . . . . . . . . . . 57
     6.5.4 Variables . . . . . . . . . . . . . . . . . . . . . . . 57
     6.5.5 Special Parameters  . . . . . . . . . . . . . . . . . . 57
     6.5.6 Accessing Environment Variables Within Scripts  . . . . 60
     6.5.7 Special Functions (tilde functions) . . . . . . . . . . 60
     6.5.8 Operators . . . . . . . . . . . . . . . . . . . . . . . 73
     6.5.9 Expressions . . . . . . . . . . . . . . . . . . . . . . 74

                                  iii

     6.5.10 Comments . . . . . . . . . . . . . . . . . . . . . . . 74
   6.6 Special Script Files  . . . . . . . . . . . . . . . . . . . 75
     6.6.1 Profile . . . . . . . . . . . . . . . . . . . . . . . . 75
     6.6.2 Logout.run  . . . . . . . . . . . . . . . . . . . . . . 75
     6.6.3 Function Keys . . . . . . . . . . . . . . . . . . . . . 75
     6.6.4 Restore . . . . . . . . . . . . . . . . . . . . . . . . 76
   6.7 Signature Files . . . . . . . . . . . . . . . . . . . . . . 77 
 7 The Editors 
   7.1 External Editors  . . . . . . . . . . . . . . . . . . . . . 78
   7.2 The Internal Editor . . . . . . . . . . . . . . . . . . . . 79
   7.3 The Command Line  . . . . . . . . . . . . . . . . . . . . . 80
     7.3.1 The History Buffer  . . . . . . . . . . . . . . . . . . 80 

 Appendices
   A Coredumps . . . . . . . . . . . . . . . . . . . . . . . . . . 81 
                                   iv


 1 Introduction 
  1.1 Hello 

Welcome to CixRead, the offline reader for the Atari ST, TT and Falcon
computers. This is one of a suite of several programs designed to make
the use of CIX both easier and cheaper. Cixcomm, written by Andr 
Willey, automates the interaction with CIX. Whilst CixRead can be run
independently of Cixcomm, it should be considered a necessity. In
addition there are a an assortment of support tools available.

  1.2 What's in the Topics 

The following topics make up the atari.st.olr conference:
  Programs - This is where CixRead's executables can be found, along
             with various support programs. 
  General  - For general chatter, and comments on the programs 
  Tests    - For testing your scripts 
  Wishlist - This is where to ask for improvements to CixRead 
  Bugs     - This is where to report any bugs you might find 
  Problems - This is a read only topic where I put the answers to any
             commonly asked questions 
  Usenet   - This is where you should make any comments or suggestions
             regarding CixRead's Usenet facilities 
  Cixcomm  - This is where you should make any comments or suggestions
             about Andre's Cixcomm. 
  Scripts  - This is where you should upload any CixRead macro file you
             think other people might find useful. 
  Developers - This is mainly intended for chat about the inner workings
             of the programs between the developers 
  Manual   - This is where the manual (1st Word Plus/Ascii version) will
             be uploaded to. Also look out for announcements of updates
             to the manual. 
  Docs.latex - Ditto for the LaTeX version. 
  Chatter    - For general chatter about anything other than OLRs

                                            1

  1.3 The Registered Version 

CixRead is distributed via the atari.st.olr conference. The
version in this conference only allows you membership of 5
conferences unless a key file is present. To register your copy of
CixRead and receive a key file, send a cheque for 20 made payable 
to Kevin O'Donovan to
 
    Kevin O'Donovan,
    32 Inchcape Road,
    Childwall, 
    Liverpool,
    L16 3ND.

Anyone sending 25 or more will receive a laser printed version
of this manual by snail mail.

  1.4 Format of this manual 

The general format of this manual is as follows: 
The various commands are described under their relevant sections. For
each command there are three headings and a description. The first
heading gives the full name of the command, and any arguments it can
take. Arguments are given as follows:
  Words in capitals are commands or tokens, and should be typed as shown,
   eg ALL, FROM, TO. 
  Words not in capitals surrounded by angle brackets should be replaced
  by the relevant information when you issue the command,
   eg < x > , < message number > , < searchstring > . 
  Arguments enclosed by square brackets are optional parameters and can
  be omitted if not needed,
   eg [ < x > ], [ < string > ], [FROM < x > TO < y > ]. 
  Arguments separated by a vertical bar indicate that you should supply
  either one of them.

Secondly the minimum abbreviation for the command is given. Most
commands can be abbreviated to their first two letters (eg SEARCH
becomes SE, SEA, SEAR, etc), though where this remains ambiguous a
third letter is required.  Thirdly the values returned by the command
are given. This is only of interest to you if you are writing CixRead
scripts, so if you are a beginner ignore them for now.  Finally a
description of what the command does is given.

                               2

  1.5 Setting the Programs Up

If you are setting the package up for the first time, download 
the file atariolr.tos from atari.st.olr/programs, run it and 
follow the instructions found therein.

If you are upgrading part of the package simply copy the new 
versions of any files found in the archive over the existing 
files in your CixRead directory. Be sure to upgrade all of the 
files at the same time, and follow any special instructions that 
may be included.


 1.6 Using the Package
  1.6.1 From Cix

Follow the instructions in the cixcomm documentation.

  1.6.2 Offline

After CixComm has finished, it will run CixRead for you. To jump straight in, 
just press return, and the first unread message will be displayed. Most commands
from Cix are duplicated, so you should start to feel at home right away.
The more advanced features are documented in the rest of this 
manual.



2 Online Help

CixRead provides an online help facility. The help facility is context
sensitive, so you will only be able to obtain information on commands
that are available to you when you get the help.

 2.1 General Help

If you are just browsing, or are unsure of the command to use, simply
type `help' or press the help key, and a description of all currently
available commands will be displayed.

 2.2 Specific Help

If you want to know more about a specific command type `help < command
> ' and help on that command will be displayed. You can also type the
command on the command line and press help anywhere within the word
you want help on. If you supply a partial command, help will give
details of all commands that match the string you entered. For
example, `help t' will give help on all commands beginning with a `t'.

                                     5

3 The Conferencing System
 3.1 What's Available
  3.1.1 On Cix Itself

One of the most frustrating aspects of Cix for the newcomer, must be
trying to find out exactly what is available and where. Most of us
will probably have been told (hopefully politely) at one time or
another that our question might more appropriately have been asked
elsewhere.  CixRead offers the following two commands to ease this
problem.

  Command: SHOW ALL
  Abbrev : SH AL
  Returns: 0 on success, -1 if no list, 1 if user requests download

This command displays a complete list of the conferences available on
Cix and their descriptions.  For this command to work, such a list
must be available offline. If none is available you will be asked if
you want to download one. If you reply yes, it will be downloaded when
you run the script. If you already have such a file, you can use it
instead. Simply rename it to `conflist.lst', and copy it to your
CixRead directory. Note: the full Cix conference list was about 60k in
length last time I checked, however it is very useful to have a copy
offline, so even if you only have a slow modem think about downloading
it.

  Command: FIND < search string >
  Abbrev : FIN
  Returns: number of matches, or -1 if no list

This command searches through a downloaded Cix conference list for any
occurrences of the string < search string > in the conference name or
description. The search string can either be a single word, eg `FIND
atari', or a group of words, in which case you must enclose the string
within quotes, eg FIND "red cars". Wild cards are not supported,
however since the search will match parts of words as well as full
words, this is not such a loss.

One other command is available for interacting with the conference
list. It is described below:

  Command: GET CONFLIST
  Abbrev : GE CO
  Returns: 0 for success, -1 for failure

This command will cause a new conference list to be downloaded. It is
useful when you decide your existing list is out of date. Whenever
CixRead downloads a conference list, the date is placed at the start
of the list, so you will know when it was downloaded. The date is
taken from your computer clock.

                                6

  3.1.2 Locally on CixRead
The show command can also be used to obtain information about your
offline database.

  Command: SHOW [NEW]
  Abbrev : SH NE
  Returns: number of topics displayed, or -1 for failure

For each topic existing offline the show command displays the number
of messages available and the number unread. It also displays the
total number of messages unread over all topics, and the number of
confs existing offline. If the `NEW' paramater is used only those
topics with unread messages will be displayed.
                               7

 3.2 Moving Between Conferences and Topics

  Command: < CR >
  Abbrev : < CR >
  Returns: 0 on success, -1 on failure

From the Main prompt, this will cause you to be joined to the next
topic with unread messages.  If none exist, you will be returned to
the Main prompt.  From the Read prompt, this will try to display the
next unread message in the current topic.  If none exist you will be
joined to the next topic in which some do, or returned to the Main
prompt if all messages have been read.

  Command: < conference > [ < topic > ]
           < conference > [/ < topic > ]
  Abbrev :
  Returns: 0 on success, -1 on failure

This is a shortened form of the join command. It is only available if
you have issued an ` opt autojoin y ' command (see the options section
for more details). You should be aware when attempting to use this
command that Cix will first attempt to match the string you supply
against aliases, and then against known commands.

  Command: JOIN < conf erence > [ < topic > ]
           JOIN < conf erence > [/ < topic > ]
  Abbrev : J
  Returns: 0 on success, -1 on failure

This is the basic command for moving around the conferencing system.
It allows you to explic- itly specify the conference and topic you
wish to join. If you do not specify a topic, CixRead will display a
list of the available topics in the conference you requested, and
prompt you for the one you wish to join. If the conference or topic
you supply is not available offline, you will be given the option of
joining it at your next logon.

  Command: NEXT
  Abbrev : NE
  Returns: 0 if a topic is joined in current conference, 1 if a new
           conference is joined first, else -1 if no topic joined

The next command marks all messages in the current topic as read, and
joins you to the next available topic.

                               8


  Command: SWITCH [ < topic > ]
  Abbrev : SW
  Returns: 0 for success, -1 for failure

Switch allows you to join another topic within the current conference.
If you do not specify a topic, CixRead will display a list of the
available topics in the current conference, and prompt you for the one
you wish to join.

  Command: TNEXT
  Abbrev : TN
  Returns: 0 if a topic is joined in current conference, 1 if a new
           conference is joined first, else -1 if no topic joined

This joins you to the next available topic. Unlike next, your message
pointers for the current topic are unaffected.

                             9

 3.3 Reading Messages and Moving Within a Topic

These are the commands that allow you to read messages within a topic.
They can be split up into two groups, those that update the message
pointer and those that do not. The message pointer for a topic
indicates to CixRead the next messag that you have yet to read in
that topic.

  Command: < CR >
  Abbrev : < CR >
  Returns: 0 on success, -1 on failure

Displays the next unread message in the current topic. If there are no
messages available in the current topic, you will be joined to the
next topic with an unread message, and the message will be displayed

  Command: < message >
  Abbrev : < message >
  Returns: 0 if message available, -1 if not, -2 if out of range

Displays the message numbered < message > if it is available. Does not
update message pointers.

  Command: -
  Abbrev : -
  Returns: 0 if message available, -1 if not, -2 if out of range

Displays the previous message if it is avalable. Does not update
message pointers.

  Command: +
  Abbrev : +
  Returns: 0 if message available, -1 if not, -2 if out of range

Displays the next message if it is available. Does not update message
pointers.

  Command: --
  Abbrev : --
  Returns: number of original if available, or minus the number if it isn't

If the current message is a comment, then this displays the original
message. Does not update message pointers.

                              10

  Command: ++
  Abbrev : ++
  Returns: number of comment if available, -1 otherwise

Displays the next comment to the currently displayed message if it is
available. Does not update message pointers.

  Command: AGAIN
  Abbrev : AG
  Returns: current message number, or -1 for failure

Redisplays the last message you read. 

  Command: BACK
  Abbrev : BA
  Returns: the message number, or -1 for failure

Used after the root or original commands, this redisplays the message
you were viewing when you issued that command. In the following
example, message #60 is a comment to message #55. You are currently
viewing message #60:

          ORIGINAL - This displays message #55
          BACK     - This displays message #60

Does not update message pointers.

  Command: CURRENT
  Abbrev : CU
  Returns: the current message number, or -1 on failure

Displays the message at the current message pointer, and updates the
current message pointer (but doesn't change it).

  Command: FIRST
  Abbrev : FIR
  Returns: the resulting message number, or -1 on failure

Displays the first available message in the current topic. Message
pointers are updated.

                             11


  Command: LAST
  Abbrev : LA
  Returns: the resulting message number, or -1 on failure

Displays the last available message in the current topic. Message
pointers are updated.

  Command: ORIGINAL
  Abbrev : OR
  Returns: number of original if available, or minus the number if it isn't

If the current message is a comment, then this displays the original
message. Does not update message pointers.

  Command: READ [ < message > ]
  Abbrev : REA
  Returns: the message number if available, -1 if not.

Displays message number < message > , or if < message > is not
supplied redisplays the last message viewed. Does not update message
pointers.

  Command: RECENT
  Abbrev : REC
  Returns: the resulting message number, or -1 on failure

Displays the message specified by your recent value. Updates message
pointers.

  Command: ROOT
  Abbrev : RO
  Returns: the number of the root message, or minus the number of the last
           message in the chain if the chain is broken.

This command allows you to view the first message in a thread. If the
first message is not available off line, the last available message
will be displayed, and you will be informed that the chain is broken.
This command does not update your message pointers.

                              12

  Command: SKIP [BACK] < x > SKIP TO < message >
  Abbrev : SK, SK BA, SK TO
  Returns: resulting message number, -1 if not available, -2 if
           outside available range

This command allows you to jump to specific messages, skip over
messages you don't wish to view, or skip backwards a number of
messages to view them again. In all cases message pointers are
updated.
        SKIP < x > skips over < x > messages and displays the next
                   message.
        SKIP BACK < x > skips back over < x > messages and displays
                   the next message.
        SKIP TO < message > skips directly to message number
                  < message > and displays it if it is available.

  Command: SKIP TO ROOT
           SKIP THREAD
  Abbrev : SK TO RO, SK TH
  Returns: resulting message number, -1 if not available, -2 if outside
           available range

These commands allow you to move around within threads. SKIP TO ROOT
skips to the first message in the current thread. SKIP THREAD skips
over the current thread, and marks all its messages as read. Only
works in ref mode

                             13

 3.4 Replying to Messages in Topics, and posting your own

  Command: COMMENT [ < conference > = < topic > ]
  Abbrev : CO
  Returns: 0 on success, -1 on failure, or -2 if aborted

This is used to post a comment to the message currently being viewed.
If the optional <conference > = < topic > argument is supplied, the
message will be posted in that topic with a title `Ref: Message xx in
< originalconf > = < originaltopic > '. If only a topic name is
provided, the current conference is assumed.

  Command: REPLY
  Abbrev : REP
  Returns: 0 on success, -1 on failure, or -2 if aborted

This is used to reply directly to the poster of a conference message
via Cix's internal mail system. The line `Ref: Your message < x > in <
conference=topic > ' will be included at the start of the message,
where < x > is the message you are replying to, and < conference=topic >
is the name of the conference and topic the message you are replying to
was in.

  Command: SAY [ < conf erence=topic > ]
  Abbrev : SA
  Returns: 0 on success, -1 on failure, or -2 if aborted

If no parameters are given, this will post a message in the current
topic. If a parameter is given, it will be used as the conference and
topic in which the message is to be posted. This is useful if you do
not have the relevant topic offline. Note that CixRead does not check
that you have supplied a valid topic name, so be careful. You will be
asked to confirm the message's destination before it is added to the
script. If you are posting a message to a specific topic, you will be
given the option of resigning from it once the message has been posted
(useful if you have asked for replies by mail). If only a topic name
is provided, the current conference is assumed.

                           14
 3.5 Finding Information in Topics 

  Command: SEARCH [ < string > [ < range > ]]
  Abbrev : SE
  Returns: The message number in which a match occurs, or -1

This command is used to search all or, if a range is specified, some
of the messages in the current topic for an occurence of < string > .
When a match is found, the message that contains it is displayed and
you are returned to the read prompt. If you now type `search' ithout
any parameters, the search will be resumed from the next message using
the same range and search strings. A search can be interrupted at any
time by pressing a key. < string > can be a group of words, in which
case they should be enclosed in double quotes, eg SEARCH "test
string", or a single word, in which case the quotes are not needed.

< range > can be of the form `FROM highnumber TO lownumber ', in which
case the search will start at the high numbered message and search
backwards through the message base to the low numbered message. This
is particularly useful if you remember reading something in the last
couple of days, but don't know which message to search from. In this
case, just do a `SEARCH FROM FIRST TO LAST'.


  Command: SQUICK [ < string > [ < range > ]]
  Abbrev : SQ
  Returns: 0 on success, -1 on failure

This command more closely duplicates the standard Cix online search
command. The current topic is searched for the search string. When a
match is found, the relevant line of the message in which it occurs is
displayed, prefixed by the message number. The search continues until
all of the specified messages have been searched, or until a key is
pressed. < string > and < range > follow the same rules as described
for the SEARCH command.

                              15

 3.6 Files (flists)

Flists can be downloaded from Cix and handled by CixRead. Two types of
flist are catered for, standard flists, as normally viewed by most
users, and the raw moderator's flists. Except when explicitly telling
CixRead to download one of these using the `get' command, CixRead will
decide which one is appropriate from the command you give. The
following commands are used for viewing and manipulating flists.

  Command: EDIT FLIST
  Abbrev : ED FL
  Returns: 0 if save selected, else -1

This command allows you to edit the flist for the current topic. If
both a moderators and a standard flist exist, you will be asked which
you wish to edit. Note that if you are not the moderator you will not
be able to upload a moderators flist.

  Command: FFIND < string >
  Abbrev : FF
  Returns: 0 on success, -1 on failure, -2 if no flist

This will search a stavdard (non-moderator) flist for the search
string. If it occurs either in the filename or its description, the
corresponding line of the flist will be displayed.

  Command: FLIST
  Abbrev : FL
  Returns: 0 on success, -2 if no flist.

This command displays the flist for the current topic if it is
available. If it is not you will be given the option of downloading
one.

  Command: GET FLIST
  Abbrev : GE FL
  Returns: 0 if flist to be downloaded, else -1

This command will cause an flist for the current topic to be
downloaded when the script is run.

                              16

 3.7 Housekeeping

This section covers maintenance of your offline message base. Whilst
currently relatively limited, this section will be expanded in future
versions.

  Command: BUILD [QUIET]
  Abbrev : BU
  Returns: 0 on success, -1 on failure

Use this command to rebuild your message base for the current topic if
it appears to be corrupted. It uses only the information in the
message file, hence it should be able to recover from almost any
damage to the file. Note that any messages marked via the KEEP command
will no longer be marked. This is unfortunately necessary, as build
has to assume the index is unreliable. Version 4 of CixRead will no
longer have this restriction.  Build normally prints out progress
information as it runs. Supplying the parameter QUIET causes it to
only inform you of problems.

  Command: CHECK [QUIET]
  Abbrev : CH
  Returns: 0 on success, -1 on failure

Checks the current topics message file for any inconsistencies.
Doesn't check the index file. For a fuller test, use Andre's Cixtest
program.  Check normally prints out progress information as it runs.
Supplying the parameter QUIET causes it to only inform you of
problems.

  Command: DELETE [ < message > | < range > | THREAD]
  Abbrev : DE
  Returns: 0 on success, -1 if message is marked as kept, -2 if message
           is not available, 1 if message is already marked for deletion

This command marks messages for deletion. Deletion is not performed
until the current topic is left (for example, by joining another or by
quitting CixRead). This provides a more efficient delete (since
messages are deleted in batches) and allows you some time to abort the
delete.  Once a message is marked for deletion, a line indicating this
will appear in its header if it is displayed.  With no parameters,
delete marks the currently displayed message, and displays the next
message. With parameters, delete marks the specified message (or
messages). If deleting a thread, only those messages later in the
thread than the current message will be deleted. To delete an entire
thread, do a `SKIP TO ROOT' first.
                              17

  Command: KEEP [ < message > | < range > | THREAD]
  Abbrev : KE
  Returns: 0 on success, -2 if message is not available, 1 if message
           is already marked for keeping

Keep allows you to specify that certain messages are not to be deleted
(for example, if they contain important information). Once a message
has been marked for keeping, it cannot be deleted, even if
specifically deleted. It must first be `unkeeped' (see below). As with
delete, the list of messages to keep will not be updated until you
leave the current topic.  The command format is the same as for the
delete command. An indicator that a message is to be kept will be
displayed in the comment line.

  Command: RESIGN [ < conf name > [ < topicname > ]]
  Abbrev : RES
  Returns: 0 on success, -1 on failure

This command allows you to resign from topics or conferences. You are
given the option of resigning online (in which case your local message
base will be untouched), offline (in which case your local message
base will be deleted, but you will still receive more messages from
Cix), or both.  If you are in a topic and you provide no arguments,
CixRead will resign you from the topic you are in. If you supply just
a conference name, you will be resigned from that entire conference.
If you supply a conference and a topic, you will only be resigned from
that topic.

  Command: UNDELETE [ < message > | < range > | THREAD]
  Abbrev : UND
  Returns: 0 on success, -2 if message is not available, 1 if message
           is not marked for deletion

This command removes the specified message(s) from the delete list.
Note that it cannot undelete messages that have already been
physically deleted, only those that are marked for deletion. The
command format is the same as for delete.

  Command: UNKEEP [ < message > | < range > | THREAD]
  Abbrev : UNK
  Returns: 0 on success, -2 if message is not available, 1 if message
           is not marked for keeping

This command removes the specified message(s) from the list of those
to keep. The command format is the same as for delete.

Note that for all the keep/delete commands, if a range is specified as
opposed to a single message the return value refers to the last
message in the range.
                              18

  Command: SIZE
  Abbrev : SI
  Returns: total disc space used for current topic, or -1 on failure

This command provides a detailed breakdown off how much disk space
each topic in the current conference is using.

                              19

 3.8 Miscellaneous
  3.8.1 External message storage

CixRead allows two ways of storing messages external to itself,
printing them or saving them to a file

  Command: FILE [" < path > "][ < range > | THREAD]
  Abbrev : FIL
  Returns: 0 on success, -1 on failure

File copies the current message to your notebook (for more information
on your notebook, see the section on customising CixRead). If a path
is provided, this will be used instead of the notebook.  If a range is
supplied, all messages within this range will be filed. If the THREAD
option is used, all messages in the current thread starting from the
current message will be filed, in the same order as they would be read
in ref mode. To file an entire thread, do a `SKIP TO THREAD' before
filing.

  Command: PRINT [ < message > | < range > | THREAD]
  Abbrev : PR
  Returns: 0 on success, -1 on failure

This allows you to print either the current message, a specified
message, a range of messages or a thread. If a range or thread is
specified, printing can be interrupted by pressing a key.

  3.8.2 Who

  Command: WHO
  Abbrev : WH
  Returns: 0 on success, -1 on failure

This command displays the nickname of the person who posted the
current message - useful if the header has scrolled of the top of the
screen.

  3.8.3 Conference descriptions

Many conferences have a short descriptive message written by the
moderator. The following commands allow you to download and view this
message.
                             20

  Command: SHOW NOTE
  Abbrev : SH NO
  Returns: 0 on success, -1 if no list is available, 1 if user requests
           download.

Display the conference note for the current topic. If one is not
available, you will be given the option of downloading it.

  Command: GET NOTE
  Abbrev : GE NO
  Returns: 0 for success, -1 for failure

Forces downloading of a conference note. Useful if you think your
local copy is out of date.

  3.8.4 Participant lists

CixRead allows you to download and view a list of people who are
currently joined to a particular topic. Remember that this information
is subject to fairly frequent change.

  Command: SHOW PARTICIPANTS
  Abbrev : SH PA
  Returns: 0 on success, -1 if no list is available, 1 if user requests
           download.

Displays a list of people joined to the current topic. If one is not
available, you will be given the option of downloading it.

  Command: GET PARTICIPANTS
  Abbrev : GE PA
  Returns: 0 for success, -1 for failure

Forces downloading of a participant list.

                                  21

  3.8.5 Moderating

If you attempt to post a message to a read only topic, CixRead will
not let you. You can get round this restriction with the following
command.

  Command: MODERATOR
  Abbrev : MOD
  Returns: 0 on success, -1 on failure

This command will ask, for each topic in the current conference,
whether you wish to be a moderator. Currently the only effect of being
a moderator is that you can post messages in topics which are read
only if you moderate them. Future versions may extend this, and since
scripts have access to this variable, it is recommended that you mark
all topics which you moderate accordingly.

                                 22

 3.9 Tokens

Tokens can be used wherever a command expects a message number. The
tokens currently available are FIRST, LAST, CURRENT, and RECENT.

  FIRST   : This is the number of the first message in a topic
  LAST    : This is the number of the last message in a topic
  CURRENT : This is the value of the message pointer for a topic
  RECENT  : This is the number of the message < r > messages from the
            end of the current topic. < r > is a user defined value
            which defaults to ten. For details on altering this value,
            refer to the options section under `Customising CixRead'

                                 23

 3.10 Ranges

Many of the commands described will accept a range of messages as
their arguments. The general form of a range is:

    FROM <start> TO <finish>

or for any Australian users:

    TO <finish> FROM <start>.

Also, `ALL' can be used as shorthand for the range `FROM FIRST TO
LAST', ie every message in a topic.

If either the FROM or the TO part of a range is omitted, defaults will
be assumed. The default for FROM is the first message in a topic, the
default for LAST is the last message in a topic. For example,

    PRINT TO 24

will print all message from the first available to number 24.  The
start and finish values can be numbers or tokens, or combinations of
the two in expressions. For example,

    PRINT FROM FIRST+(LAST-RECENT)+12

would be valid.

                                  24


4 Electronic Mail

CixRead allows you to send and receive internal and external mail via
Cix.

 4.1 Reading Mail

  Command: < CR >
  Abbrev : < CR >
  Returns: memo number on success, -1 on failure

Pressing return will cause the next unread memo to be displayed. If
there are no unread memos this will be indicated.

  Command: < memo >
  Abbrev : < memo >
  Returns: memo number on success, -1 on failure

Displays memo number < memo > if it is available. 

  Command: AGAIN
  Abbrev : AG
  Returns: memo number on success, -1 on failure

Redisplays the last memo to be viewed. 

  Command: READ < memo >
  Abbrev : RE
  Returns: memo number on success, -1 on failure

Displays memo number < memo > if it is available 

  Command: READ ALL
  Abbrev : RE AL
  Returns: number of memos read, or -1 on failure

You will be given the option of reading each memo matching your
current filter settings. For each memo that matches, you will be given
a list of options. These currently allow you to read, delete, mark as
unread, mark for keeping, or skip that memo. More options may be added
in future versions. You can also quit at any point. Enter a `?' for
help.

                                25

  Command: SKIP
  Abbrev : SK
  Returns: memo skipped on success, -1 on failure

Skips over the next memo without reading it. The memo is not marked as
read.

                                26

 4.2 Replying and Sending Mail 

  Command: COMMENT [ALL | < address > ]
  Abbrev : CO
  Returns: 0 on success, -1 on failure, -2 if user aborts

Send a reply to the last memo to be displayed. Once you have prepared
your reply, you will be given the option of including the original
memo in your posting. If the ALL modifier is given, then a reply will
be sent to both the From: field of the memo, and the Reply-To: field.
This is useful for replying to a mailing list. If the < address >
field is supplied, then the reply is mailed to that address, rather
than the original poster. This is basically a FORWARD MAIL command.

  Command: MAIL [TO] < destination > [ < destination 2 > ] ...
  Abbrev : MA
  Returns: 0 on success, -1 on failure, -2 if user aborts

Send a mail message to the specified destination(s). This command is
used to send mail from a topic or the main prompt without first
entering the mail system. You will be prompted for a subject, and then
allow ed to enter the text of your message.

  Command: REPLY [ALL | < address > ]
  Abbrev : RE
  Returns: 0 on success, -1 on failure, -2 if user aborts

Send a reply to the last memo to be displayed. Once you have prepared
your reply, you will be given the option of including the original
memo in your posting. See also the description of the COMMENT command.

  Command: SAY [<destination>] [<destination 2>] [<destination 3>] ...
  Abbrev : SA
  Returns: 0 on success, -1 on failure, -2 if user aborts

Send a mail message to the specified destination(s). If you do not
supply any destinations, you will be prompted for at least one. You
will then be prompted for a subject, and then allowed to enter the
text of your message.

                               27

  Command: SEND [ < destination > ] [ < destination 2 > ]...
  Abbrev : SE
  Returns: 0 on success, -1 on failure, -2 if user aborts

Send a mail message to the specified destination(s). If you do not
supply any destinations, you will be prompted for at least one. You
will then be prompted for a subject, and then allowed to enter the
text of your message.

  Command: TO [ < destination > ] [ < destination 2 > ] ...
  Abbrev : TO
  Returns: 0 on success, -1 on failure, -2 if user aborts

Send a mail message to the specified destination(s). If you do not
supply any destinations, you will be prompted for at least one. You
will then be prompted for a subject, and then allowed to enter the
text of your message.

                            28

 4.3 Housekeeping

CixRead offers commands for viewing what messages you have offline,
and for deleting those you do not wish to keep.

 4.3.1 Mail Flags

With version 3.3.3 of CixRead a number of new flags were introduced to
mail to make your mail management less of a chore. At the moment, each
of these flags are mutually exclusive, but this may change in future
versions. The flags are as follows:

 NEW - the memo has just arrived and has never been read. The first
       time it is read, this flag will be reset.
 MARKED - the memo has been read, but you want to deal with its contents
       at a future date. This flag marks it as such.
 KEEP - the memo has something important in it, and you don't want it
       accidentally deleted. The delete command cannot touch this memo.
 DELETED - the item has been marked for deletion. The next time a PURGE
       is done, such memos will be permanently removed.
 NO FLAGS - the memo has been read

When you first read your mail you will be presented with new
mail. After all new memos have been read, you will be presented with
any memos that you have marked for further attention.

  Command: DELETE [ < message > | < ALL > ]
  Abbrev : DE
  Returns: number of messages deleted, or -1 if unavailable message requested

Marks a memo for deletion from your offline store. If no parameters
are given, the last message displayed is deleted. If a message is
specified, it will be deleted if available. If ALL is specified, a
description of each read memo that matches your filter settings will
be presented to you, and you will be given the option of reading it,
deleting it, or skipping it. Thus you can read a memo before you
decide to delete it.  Memos are not actually deleted immediately, but
are merely marked for deletion. They are only physically deleted when
a PURGE command is issued.

                                   29


  Command: FILTER
           FILTER NAME [= < string > ]
           FILTER SUBJECT [= < string > ]
  Abbrev : FI [NA | SU]
  Returns: 0 on success, -1 on failure

This command allows you to control which memos will be displayed to
you when you issue one of the commands described below. You are
allowed to `filter' memos from a specific person, or with a specific
subject. Memos are displayed if they contain < string > , so you could
search for all memos sent to you by anyone with, for example, an `a'
in their name, or the words `fwee bwian' in their subject line.  On
its own, FILTER displays a dialog box containing the current filters,
and allows you to edit them.

FILTER NAME= < string > tells CixRead to only show you memos from
people with < string > in their name/mail address. For example,
`FILTER NAME=wodewick' will cause only messages from people whose name
contains `wodewick' to be displayed. `FILTER NAME=uk.ac.liverpool.ibm'
will display only those messages sent to you from people on Liverpool
University's (now non-existent) IBM 3081.

FILTER SUBJECT= < string > tells CixRead to only display those memos
whose subject line contains < string >

In both the above commands, < string > is taken to be the part of the
command line from the `=' to the end of the line, *including* any
spaces.

FILTER NAME or FILTER SUBJECT will clear the corresponding filter. 


  Command: KEEP [ < x > | ALL]
  Abbrev : MAR
  Returns: 0 on success, -1 on failure

This command causes the message you are currently reading to be marked
for keeping. This effectively stops it from being deleted. If the ALL
paramater is given, you will be given the option of marking each
message that matches your filter settings. If a single message is
specified, that message will be marked.


  Command: MARK [ < x > | ALL]
  Abbrev : MAR
  Returns: 0 on success, -1 on failure

This command causes the message you are currently reading to be
marked. Useful if it contains something important that you want to be
reminded of next time you run CixRead. If the ALL paramater is given,
you will be given the option of marking each message that matches your
filter settings. If a single message is specified, that message will
be marked.

                                   30


  Command: PURGE
  Abbrev : PUR
  Returns: number of messages purged

This command causes the current mailbox to be purged. That is, all
messages marked for deletion will be removed from the mailbox, as will
any mailbox entries for which a corresponding memo file cannot be
found. This should be done periodically, as a mailbox can only hold
(by default) 500 messages.

  Command: SHOW [NEW | MARKED | DELETED | READ | ALL]
  Abbrev : SH
  Returns: number of memos displayed, or -1 on failure

Show on its own lists all memos in the current mailbox, except those
marked for deletion.  SHOW ALL does the same, except deleted memos are
shown as well. Each of the other options causes just that type of mail
to be displayed.

  Command: UNDELETE [ < message > | < ALL > ]
  Abbrev : DE
  Returns: number of messages undeleted, or -1 if unavailable message requested

Remove the deletion flag on each specified memo. 

  Command: UNKEEP [ < message > | < ALL > ]
  Abbrev : DE
  Returns: number of messages kept, or -1 if unavailable message requested

Remove the keep flag from each specified memo. 

  Command: UNMARK [ < message > | < ALL > ]
  Abbrev : DE
  Returns: number of messages marked, or -1 if unavailable message requested

Remove the mark flag for each specified memo.

                                   31

 4.4 Mailboxes

CixRead will allow you to have multiple mailboxes set up. This might
be useful if you want to collect all mail on a particular subject in
one place. The following commands are available for interacting with
mailboxes.

  Command: CD [ < directory > ]
  Abbrev : CD
  Returns: 0 on success, -1 on failure

Allows you to change to a different mailbox in the specified
directory. If you omit the directory field, you will be prompted for a
path via the fileselector.

  Command: MCOPY [ < directory > ]
  Abbrev : MC
  Returns: 0 on success, -1 on failure

This command copies the current memo in the current mailbox to the
mailbox in the specified directory. If you omit the directory field,
you will be prompted for a path via the fileselector.

  Command: MMOVE [ < directory > ]
  Abbrev : MM
  Returns: 0 on success, -1 on failure

This command copies the current memo in the current mailbox to the
mailbox in the specified directory. The original memo is then marked
for deletion. If you omit the directory field, you will be prompted
for a path via the fileselector.

  Command: NEWBASKET < directory >
  Abbrev : NEW
  Returns: 0 on success, -1 on failure

Allows you to create a new mailbox in the specified directory. You
will be prompted for the size of the mailbox to be created - this size
refers to the maximum number of memos that can be stored in that
mailbox at any one time. The default is 500.

 4.5 Miscellaneous
  4.5.1 Inbaskets and Outbaskets

CixRead keeps a record of your outgoing mail, as well as your
incoming. Whenever you send a memo, it is placed in your outbasket.
All commands are available when in both the inbasket

                                    32

and the outbasket, except you are not allowed to comment to your own memos. 

  Command: INBASKET
  Abbrev : IN
  Returns: 0 on success, -1 on failure

Tells CixRead to work with incoming mail. 

  Command: OUTBASKET
  Abbrev : OU
  Returns: 0 on success, -1 on failure

Tells CixRead to work with outgoing mail

  4.5.2 Hardcopy

CixRead allows you to print out your mail 

  Command: PRINT [ < memo > | ALL]
  Abbrev : PR
  Returns: memo number printed on success, -1 on failure

If no parameter is given, the last memo displayed will be printed. If
a memo number is given, this will be printed (if available). If ALL is
specified, you will be asked if you wish to print each of the memos
that match your filter setting

  4.5.3 Filing

CixRead allows you to file memos in the same way as conference messages. 

  Command: FILE [" < f ilename > "] [ < x > | ALL]
  Abbrev : FI
  Returns: memo number filed on success, -1 on failure

Files the current memo, a specified memo, or all memos mathching the
filter criteria to the specified file. If no filename is given, the
current notebook path will be used.

                                33
  4.5.4 Binmail Directories

These commands allow you to view or download your binmail directory. 

  Command: SHOW DIR
  Abbrev : SH DI
  Returns: 0 on success, -1 on failure, -2 if user requests download

Displays your binmail directory, if it is available offline. If it is
not present, you will be asked if it should be downloaded.

  Command: GET DIR
  Abbrev : GE DI
  Returns: 0 on success, -1 on failure

Forces a download of your binmail directory, even if one is already present.


  4.5.5 Returning to the Conferencing System

  Command: QUIT
  Abbrev : Q
  Returns: 0 on success, -1 on failure

Exits mail, and returns you to the conferencing system.

  4.5.6 Mail Aliases

The following command is quite new, and is not yet complete. Hence the
sketchy documentation:

  Command: MALIAS
  Abbrev : MAL
  Returns: 0 on success, -1 on failure

Adds a mail alias. A mail alias is a short hand form for a commonly
used address, for example, I have the alias `work' set up to be
`abaddon@uk.ac.liverpool.scm.suprenum'. This means that I can mail
myself by typing `mail work'. If I needed to send mail to a user named
`work', I can type `mail \work'. You can send mail to more than one
alias at once if you want, eg

   mail work andre@cix dave

where work and dave are aliases and andre@cix isn't, would be perfectly
valid.

                                  34

5 Miscellaneous

The following commands belong in the first half of the manual, but do
not fall under any of the previous headings.

 5.1 Quitting CixRead 

  Command: BYE
  Abbrev : BY
  Returns: nothing on success, -1 on failure

When you have finished a session wih CixRead, issue this command to
leave the program. If there is unread mail you will be reminded about
it

 5.2 Running Other Programs 

  Command: EXEC [ < program > ] [ < commandline > ]
  Abbrev : EX
  Returns: program return value

This command allows you to run other programs from within CixRead.
When the other program has finished running you should be returned to
CixRead (assuming the other program doesn't do anything naughty).  If
you type EXEC with no parameters, you will first be presented with a
fileselector. You should select the program you wish to run. After
this, you will be prompted to enter a command line into the dialogue
box that will be displayed. If you do not wish to pass a command line
to your program, simply press Return.  Alternatively you can supply a
filename as part of the command. If you do this, you will not be
prompted for a command line, so if you want one you should enter it
along with the program name.  The default path for programs is the
CixRead directory. If your program is not in this directory, you will
have to supply a path.

                                 35

 5.3 Upload Script Control

CixRead offers three commands for directly controlling your upload file. 

  Command: ## < string >
  Abbrev : ##
  Returns: 0 on success, -1 on failure

This command echoes the contents of < string > directly to your main
script file (normally reply.scp). Note that there is no space between
the `##' and the < string > .

  Command: #1 < string >
  Abbrev : #1
  Returns: 0 on success, -1 on failure

An alternative form for ##. 

  Command: #2 < string >
  Abbrev : #2
  Returns: 0 on success, -1 on failure

This command echoes the contents of < string > directly to your
secondary script file (normally reply2.scp). Note that there is no
space between the `#2' and the < string > .

  Command: %% < string >
  Abbrev : %%
  Returns: 0 on success, -1 on failure

This command echoes the contents of < string > directly to your
`CIXCOMM.BAT' file. Note that there is no space between the `%%' and
the < string > .

  Command: KILLSCRIPT
  Abbrev : KI
  Returns: 0 on success, -1 on failure, -2 if user aborts

This command allows you to clear your upload files and start new ones.
For each file that is not empty, you will be asked if you would like
it deleted. If you reply yes, then that file will be removed.

                               36

 5.4 Resumes

CixRead allows you to download and view peoples' resumes. 

  Command: SHOW RESUME [ < nickname > ]
  Abbrev : SH RE
  Returns: 0 on success, -1 on failure, -2 if user requests download

This command is used to view resumes. If the < nickname > parameter is
omitted, a list of available resumes will be displayed. If the resume
for < nickname > is not available, you will be asked if you wish to
download one.

  Command: GET RESUME < nickname >
  Abbrev : GE RE
  Returns: 0 on success, -1 on failure

This command allows you to download a resume. It is useful if you want
to update a resume you already have offline.


 5.5 System Status 

  Command: STATUS
  Abbrev : ST
  Returns: available disk space on success, -1 on failure

The status command displays information about CixRead and its
environment. The information displayed is the working directory, the
upload file path, the notebook path, and the version number and date.
Also displayed is the current drive, free memory, total disk space
available on the CixRead drive, and total remaining free.


 5.6 Editing files 

  Command: EDIT [ < filename > ]
  Abbrev : ED
  Returns: 0 on success, -1 on failure

This will run the currently selected editor on the file you specify.
If < filename > is flist, you will be allow ed to edit the flist for
the current topic.

                                   37

 5.7 Menu bar and Desk Accessories

Whilst in normal use CixRead does not provide a menu bar, it is
possible to call one up temporarily for access to desk accessories.

  Command: MENU
  Abbrev : ME
  Returns: 0 on success,-1 on failure

Displays a menu bar at the top of the screen. Normal access to CixRead
is suspended whilst the menu is present. The main purpose of the menu
is to provide access to desk accessories, hence there is not a great
deal of selections available from it. This may change in later
versions.  Currently the following options are available:

  About CixRead - displays a (rather pretty, if I do say so myself)
                  dialog box in the usual `about this program' style.
  Exit Menu     - removes the menu bar, and returns you to your last
                  position in CixRead
  Exit CixRead  - exits the program as though you had issued the BYE
                  command.


 5.8 Pausing

Sometimes, mainly in a script, you might want CixRead to display some
information, then wait until the user has finished with it. That is
the purpose of the following command.

  Command: PAUSE
  Abbrev : PA
  Returns: No return

Prints `Press return to continue..' and waits for the user to press
return. Mainly useful in scripts.

                                  38

 5.9 Shelling out

CixRead allows you to pass commands to a resident shell for execution.
For this feature to be any real use, you must run CixRead from a
suitable shell. From then on, you will be able to use any of the
commands available from the shell from within CixRead. There are two
modes of access to the shell.

  Command: ! < command >
  Abbrev : ! < command >
  Returns: Dependant on the command you called

This passes < command > to your shell, and returns whatever value the
command returns. 

  Command: SHELL
  Abbrev : SHE
  Returns: -1 if no shell available

This command puts you into shell mode. In this mode, every line you
type will be passed to the shell for execution. To get back to
CixRead, type `exit'.


  5.10 Searching Files

CixRead provides a simple command for searching files. 

  Command: FSEARCH < f ile > < string >
  Abbrev : FS
  Returns: number of occurences of < string > , or -1 on failure

This command searches the specified file for any occurences of 
< string > . Each time one is found, the line containing it is printed
to the screen.

 5.11 Notification of downloads of resumes, flists, mail, etc

It is quite easy to forget that you downloaded a resume or an flist
whilst offline, especially if you didn't upload the script in which
you did it until the next day. CixRead offers a command that will
alleviate this problem.

  Command: LOG [FILE | MAIL | ALL]
  Abbrev : LO
  Returns: 0 on success, -1 on failure

This command prints a summary of all the new mail, flists, resumes,
conference notes, etc that were downloaded in the last blink. If you
put this command in your profile, you will be reminded when you run
the reader that these new files exist. The command `LOG FILE' only
reminds you of new flists, etc, not of new mail. The command `LOG
MAIL' (not surprisingly) only tells you about new mail. Note that
there is a difference between new mail and unread mail. On its own,
`LOG' supplies information on everything.

                                  39

 5.12 Selecting alternative message bases

CixRead allows you to access alternative message bases using the
commands below. One possible use for this facility would be to allow
you to copy conferences or topics that you want to keep for reference
off your hard disk and onto a floppy, thus freeing disk space yet
still providing convenient access to the messages. I will at some
stage be providing a tool to automate the copying of messages between
different message bases.

  Command: HOME
  Abbrev : HO
  Returns: 0 on success, -1 on failure

Reset CixRead to use your original message base (ie the one that was
active when you ran CixRead).

  Command: PATH [ < path > ]
  Abbrev : PA
  Returns: 0 on success, -1 on failure

Tells CixRead to attempt to initialise itself from the the message
base at <path>. There must be a valid message base at <path>, ie a
conflist.dat file, and folders for any conferences referenced within
the file. The path must be terminated with a ` \ '.  If no path is
given, you will be presented with a fileselector, with which you can
select a suitable path.

 5.13 Message Caching

When reading messages in a conference, CixRead will attempt to read in
several messages from disk at a time. This is designed to speed up
access to the messages, and to reduce the amount of access to your
disk drive. The actual number of messages CixRead will read at one
time is specified using `OPT CACHESIZE'

  Command: CACHESTATS
  Abbrev : CA
  Returns: Current size of cache in bytes

You can see how successful the cache has been using this command. It
displays the current size of the cache, and the number of hits and
misses so far. A hit occurs when CixRead tries to access a message
that is already in the cache; a miss occurs when a message not in the
cache is accessed (and consequently the cache needs to be refilled
from disk).

                                 40

 5.14 Deferring Commands

You can tell CixRead to execute commands at off-peak times using the
DEFER command modifier. The format is

  DEFER < command >

Any CixRead command can used with the DEFER modifier, however only
those that call for direct interaction with Cix will behave
differently. For example, DEFER FUL big.file would cause big.file to
be downloaded at cheap rate times, no matter when you next log in.

This command only works if you are using Cixcomm with CixRead.

 5.15 Suspending Topics

Cixread now lets you suspend topics. This means that if a topic
suddenly starts receiving a lot of traffic which you don't want to
read, you can stop receiving it for a few days until it quietens down,
without having to resign from it. The commands are:

  Command: SUSPEND
  Abbrev : SU
  Returns: Number of topics suspended Lists all topics currently suspended,
           and how long they are suspended for.


  Command: SUSPEND < topic > [ < days > ]
  Abbrev : SU
  Returns: 0 on success, 1 on failure

Suspend the named topic for the specified number of days. If the <
days > argument is omitted, then the topic will be suspended
indefinetely.

  Command: RESUME < topic >
  Abbrev : RESU
  Returns: 0 on success, 1 on failure

Stop suspending the specified topic immediately.

                                   41

6 Customising CixRead

CixRead allows you a great deal of control over its environment, from
simply altering the default paths used by the program, to adding
entire new commands via the script language This section describes the
various ways in which you can customise the program to fit your needs.

 6.1 Environmental Variables

CixRead uses several environmental variables. These are special
variables defined in your shell (be it a desktop, a CLI, or Cixcomm),
that are passed onto programs launched from the shell (some are also
used by the shell itself, however that's another story). Perhaps the
most commonly used variable is PATH. This is used to define a sequence
of locations (on a hard disk perhaps) where a CLI should look for
programs you tell it to run. Unfortunately, in there infinite wisdom,
Atari did not see fit to include the option to set these variables fom
the desktop.  There are ways around this though:

 1. Buy Neodesk 3, especially if you have a hard disk. This allows you
    to set up to ten environmental variables.
 2. Use some form of CLI that supports them. Possibilities include the
    craft shell, Batcher (from Hisoft), Neodesk's CLI, etc.
 3. Use environ.prg (in the flist). Don't know a great deal about this
    program, but apparently it lets you add variables to the GEM desktop.
 4. Use Cixcomm, which allows you to set the variables in your setup file.

The environmental variables used by CixRead are listed below:

  1. CIXREAD= <drive>:\<path>\

  This variable is used by both the splitter and the reader. It gives
  the location that the splitter should split to, and the reader should
  read from. If it is omitted, the splitter and the reader will default
  to a directory n CIXREAD n on the drive upon which they are run.

  CAVEATS Path should be no more than one directory level deep.

  2. REPLY= <drive>:\<path>\

  This is the path to your upload file, ie the Cix script
  that places all of your messages in the correct topic. This is
  generated by CixRead.

  3. NOTE= <drive>:\<path>\<filename>

  This is the path and filename of your notebook file (the place things
  are written to when you issue the `FILE' command. The default is
  `NOTEBOOK.TXT' in your CixRead folder.

                                   42

  4. SCRATCH= <drive>:\<path>\<filename>

  This variable is used by the splitter only. If it is present, it
  tells the splitter where to find the scratchpad file you downloaded
  from CIX containing your messages. If you do not supply this variable,
  CixRead will look for a file `SCRATCHP' first in the root directory of
  the drive you run the splitter from, then in the directory the
  splitter is run from.

  5. CIXREAD_SCRIPTS= <drive>:\<path>\

  If this is set, then CixRead will look for scripts on the path
  specified instead of the default.

  6. TMP= <drive>:\<path>\

  Tells CixRead where to create any temporary files it needs to create.
  Certain commands might run faster if this points to a ram disk. The
  command `opt temppath' will overide this variable, but only for the
  editor's temporary files.

                                   43

 6.2 The Option Menu

The option menu consists of a list of commands for altering various
parameters of CixRead.  The commands can be entered in two ways:

  1. Typing `option < optionname > < value > ' from any prompt except
     the options prompt will set the appropriate option and return you
     to your previous prompt. For example,

        OPTION TERSE NO

     will turn terse mode off.

  2. Typing ` < optionname > < value > ' from the option menu will set
     the appropriate option, and drop you out of the option menu.


  6.2.1 Available options

  Command: ALIAS YES | NO
  Abbrev : AL
  Returns: 0 if set to NO, 1 if set to YES

If this is set to YES, then CixRead will automatically echo the
expansion of any aliases it comes across to the screen before
executing them. This may be useful if things aren't behaving quite as
you'd expect them to.

  Command: AUTOJOIN YES | NO
  Abbrev : AU
  Returns: 0 if set to NO, 1 if set to YES, -1 on failure

If this is set to yes, then CixRead will interpret any commands that
it is does not recognise as either aliases or built in commands, as
the name of a conference/topic. It will then attempt to join this
conference. Be aware that CixRead will first try and match your input
with both aliases and its own commands, and only then will it try and
do a join conference.

  Command: CACHESIZE < x >
  Abbrev : CA
  Returns: 0 if successful, else -1

This command allows you to specify how much memory CixRead will set
aside for caching messages. The default is 10K It is suggested that
you experiment with this setting to determine what gives the best
performance for your system, particularly if you have a floppy based
setup.  Increasing the cache size will mean fewer disk accesses when
reading messages, searching in conferences, etc, but making it too
large will cause a noticeable delay whenever the cache is

                                    44

refilled. Play with it, and see what suits you best - the CACHESTATS 8
command might prove helpful. The default size is 10K. A size of zero
switches caching off altogether.

  Command: CC [ < nickname > ]
  Abbrev : CC
  Returns: 0

This causes any mail you send to be CC'd to the specified nickname.
OPT CC on its own switches off this feature.

  Command: CR YES | NO
  Abbrev : CR
  Returns: 0 if set to NO, 1 if set to YES, -1 on failure

This option controls whether linefeed characters sent to the printer
will be translated to carriage return/line feed combinations [YES], or
just sent as linefeeds [NO]. If your printer prints each line of a
message starting from the position underneath the last character of
the previous line instead of in column 0 when you use the PRINT
command, you should set this option to YES

  Command: EDIT
  Abbrev : ED
  Returns: 0 on success, -1 on failure

This command will display a dialogue box that allows you to set all of
the various editor parameters in one go.

  Command: EDIT YES | NO
  Abbrev : ED
  Returns: 0 for internal, 1 for external, -1 on failure

This selects whether one of CixRead's internal editors will be used
[NO], or whether an external editor will be used [YES].

  Command: EDITPATH < path >
  Abbrev : ED
  Returns: 0 on success, -1 on failure

Selects an external editor defined by < path > . Also tells CixRead to
use the external editor.

  Command: EXPERT YES | NO
  Abbrev : EX
  Returns: 0 if set to NO, 1 if set to YES, -1 on failure

Selects or deselects expert mode. Usually CixRead will ask you to
confirm anything that will alter its message base. If expert mode is
selected, CixRead will assume that you knwo what you are doing, and
not ask for confirmation.

  Command: FKEYS
  Abbrev : FK
  Returns: 0 on OK, 1 on SAVE, 2 on QUIT, -1 on failure

Displays a dialogue box for setting function keys. See the function
key instructions for more details. The return values indicate what
button was used to exit the dialogue.

  Command: HEADERS YES | NO
  Abbrev : HEA
  Returns: 0 if set to NO, 1 if set to YES, -1 on failure

If this is set to YES, then only the first line of every conference
message will be displayed. This is useful in scripts that display
messages in the course of their execution. For example a script that
did a repeated search would normally need to be supervised in case a
message that filled the screen was displayed (since the system would
then pause and wait for user input). With this option switched on this
is no longer a problem.

  Command: HISTORY < x >
  Abbrev : HI
  Returns: < x > , or -1 on failure

Sets the size of the command history buffer to < x > lines. See the
section on editors for more details about the command history buffer.

  Command: JOIN < x >
  Abbrev : JO
  Returns: < x > , or -1 on failure

If you try to join a conference or topic that is not available
offline, CixRead will give you the option of trying to join it next
time you log on. This option sets the maximum number of messages that
you will receive in each topic when joining a conference online for
the first time.

                                 46


  Command: NOTEPATH [ < path > ]
  Abbrev : NO
  Returns: 0 if notepath was set, -1 if not

Selects a file for CixRead's notebook. If a path is not given in the
command, a fileselector will be displayed for you to select a notebook
file.

  Command: OPTION [ < option name > ] [ < value > ]
  Abbrev : OP
  Returns: varies, generally positive or zero on success, negative on failure

Without parameters, this takes you to the option menu. With
parameters, the appropriate option is set.

  Command: PAGE [ < x > ]
  Abbrev : PA
  Returns: < x > , or -1 on failure

Sets the pagelength used by CixRead to < x > lines. This is the number
of lines of text that CixRead will display before displaying the
`more?' prompt and pausing. If you do not supply a parameter < x > ,
the current pagelength will be displayed, and you will be prompted for
a new one.

  Command: QUIT
  Abbrev : QU
  Returns: 0 on success, -1 on failure

Drops you out of the options menu, back to the prompt you were at previously. 

  Command: RECENT [ < x > ]
  Abbrev : REC
  Returns: < x > , or -1 on failure

Sets your recent value to < x > messages. This value is used by
CixRead to calculate, for example, what message to skip to when you
issue a `skip to recent' command. The message number will be the
message which is < x > messages less than the last in the topic. For
example, if the last message in a topic is #193, and your recent value
is ten (the default), your recent message will be #183. If you do not
supply a parameter < x > , the current recent value will be displayed,
and you will be prompted for a new one.

                                    47

  Command: REF [OFF | FORWARDS]
  Abbrev : REF
  Returns: 0 for OFF, 1 for FORWARDS, -1 on failure

Turns read reference mode off, or sets the type of read reference mode
to use. The only mode currently supported is FORWARDS. In this mode,
you will read right to the end of each branch in every thread before
reading the next branch. For example, you are currently reading
message #20. This has to comments, messages #24 and #31. Message #24
has one comment, message #42. You will be presented with the messages
in the order #20, #24, #42, and #31.

  Command: SCRIPTPATH [ < path > ]
  Abbrev : SC
  Returns: 0 if path set, -1 otherwise

Selects CixRead's upload file. If a path is not given in the command,
a fileselector will be displayed for you to select an upload file.

  Command: SIGN YES | NO
  Abbrev : SI
  Returns: 0 for NO, 1 for YES, -1 on failure

If set to YES, CixRead will automatically append the correct signature
file 9 to every message you post

  Command: TEMPPATH < path >
  Abbrev : TEM
  Returns: 0 on success, -1 on failure

Selects a path for temporary files for the editor. CixRead changes its
path to this path before executing the editor, so if your editor is
unable to find its configuration files, resource files, etc, you
should set this to the editor's directory

  Command: TERSE YES | NO
  Abbrev : TER
  Returns: 0 for NO, 1 for YES, -1 on failure

Selects or deselects terse mode. In terse mode message headers are
smaller, and prompts are abbreviated. CixRead's default mode is terse.
Try both and see which you prefer.

                                9

  Command: TEST YES | NO
  Abbrev : TES
  Returns: 0 for NO, 1 for YES, -1 on failure

This switches on several debugging features of CixRead 

  Command: TIMER [ < x > ]
  Abbrev : TI
  Returns: < x > , or -1 on failure

Sets the printer time out value to < x > seconds. If CixRead does not
receive confirmation from your printer that a character has been
received in < x > seconds, it will timeout, and you will be returned
to the command line. Setting a timeout value of zero will result in an
infinite timeout period. You can manually timeout the printer after 3
seconds of inactivity by pressing a key.

  Command: TT YES | NO
  Abbrev : TT
  Returns: 0 for NO, 1 for YES, -1 on failure

This command tells CixRead that you are running on a TT.

                               49

 6.3 Function Keys

CixRead allows you to set up to 40 function key definitions, each of
which can optionally include a carriage return for immediate
execution. You can set the keys via a dialogue box or using a command
line. The 40 keys are made up from combinations of the 10 function
keys and the shift, control and alternate keys.

  6.3.1 The Dialog Box

Type `opt fkeys' to activate the dialog box. It should be instantly
familiar to anyone who's used Uniterm, Simon Poole's comms package. An
editable area is provided at the top of the screen for each of the ten
function keys. You can enter a string for each key into its respective
area.  Along the bottom of the dialogue box are two groups of buttons.
The four on the left are used to indicate whether the currently
displayed keys correspond to the function keys on their own, the
function keys with `Shift' pressed, the function keys with `Control'
pressed, or the function keys with `Alternate' pressed.  The three on
the right have the following functions:

  OK returns you to the CixRead command line. The function keys you
     have defined will be present for the current session (until you type
     `bye' or reset the computer), but will not be loaded for future
     sessions
  SAVE acts as for `OK', except that the key definitions are also
     saved to a file `fkeys.run' in your scripts folder. This file will be
     executed every time you run CixRead, installing the function keys you
     have defined. Note that the `fkeys.run' script is run before your
     profile, so function keys defined in your profile will overwrite any
     that are also defined this way.
  QUIT returns you to the CixRead command line, ignoring any changes
     you may have made to the function keys.

  6.3.2 Setting Keys from the Co  ϑ pO  O    O O  OO function keys from the command
line. The parameter < x > in each case represents the function key you
wish to set, where < x > = 1 sets F1, < x > = 5 sets F5, and < x > = 0
sets F10.

  Command: AF<x> = < string >
  Abbrev : AF
  Returns: 0 on success, -1 on failure

This command sets the string that will be displayed when you press
function key < x > with the alternate key held down. Note that there
is no space between the `=' and the < string > .

                                   50


  Command: CF<x> = < string >
  Abbrev : CF
  Returns: 0 on success, -1 on failure

This command sets the string that will be displayed when you press
function key < x > with the control key held down. Note that there is
no space between the `=' and the < string > .

  Command: FN<x> = < string >
  Abbrev : FN
  Returns: 0 on success, -1 on failure

This command sets the string that will be displayed when you press
function key < x > with no otherkeys held down. Note that there is no
space between the `=' and the < string > .

  Command: SF<x> = < string >
  Abbrev : SF
  Returns: 0 on success, -1 on failure

This command sets the string that will be displayed when you press
function key < x > with the shift key held down. Note that there is no
space between the `=' and the < string > .

  6.3.3 Parameters

The various `$' parameters can be included in function key
definitions. These will be expanded to their current values when the
key is pressed. For example, fn1=resign $t would expand to `resign
cix/problems' if you were in that topic when you pressed F1.

  6.3.4 Auto-executing Function Keys

A function key can be set up so that it will behave as though you had
pressed return after typing in the function key string. To do this,
the last two characters in the function key definition should be `\n'.
Using the above example again, the command to define the key would be

  fn1=resign $t\n.

As in the previous example, this would expand to `resign conf/topic'
when you press F1, however in this case the command would be executed
immediately - you would not have to press Return.

                               51

 6.4 Command Aliasing
CixRead allows you to define a short form for commands that you
execute a lot, or that you feel are too long. This is done using the
alias command. Aliasing is very similar in implementation to Cix's
macro facility. The command can be used in three formats:

  Command: ALIAS < alias word > < full string >
  Abbrev : AL
  Returns: returns 0 on success, -1 on failure

This sets up the string < alias word > to be equal to < full string >.
For the rest of the current session, entering < alias word > will
cause CixRead to react as though you had typed < full string > .

Note that < alias word > is considered to start from the first non
space character after the ALIAS command word, and finish at the next
space, ie it can only be one word. The rest of the command line is
taken to be the < full string > . Note also that aliases are case
sensitive, that is `fDl' is not the same as `fdl'. Finally, aliases
are checked for before CixRead commands are checked for, so it is
possible to define an alias as an existing CixRead command, stopping
the CixRead command from being executed.

Some examples of aliases are:
   alias fdl run fdl.run - whenever you type `fdl', the CixRead script
                           `fdl.run' will be executed.
   alias bigtext exec fsw.ttp /b - whenever you type bigtext, the
                           program `fsw.ttp' will be executed with the
                           parameter `/b', turning on big text (assumes
                           fsw is in the CixRead folder)
   alias news join cix/news - whenever you type news, you will be joined
                           to cix/news 


  Command: ALIAS < alias word >
  Abbrev : AL
  Returns: 0 on success, -1 on failure

If the alias < alias word > is defined, this will undefine it. 


  Command: ALIAS
  Abbrev : AL
  Returns: number of aliases found, or -1 on failure

This command lists all of the currently defined aliases.

                                  52

   6.4.1 Parameters

The various `$' parameters can be included in alias definitions.
These will be expanded to their current values when the alias is
processed. For example,

alias ful ##ful $f

would display a fileselector and expand to

##ful <drive>:\<path>\<filename>

(not that this command would mean much to Cix... )

   6.4.2 Overriding Aliases

If a command starts with a `/', it will not be tested for alias
expansion - this allows you to alias a command to something different,
but still use the original command when needed by prefixing it with
`/'. Eg, if you had done an `alias join myjoin', typing `join' would
run the command `myjoin', but typing `/join' would run the original
join command.

                                53

 6.5 CixRead Scripts

Perhaps the most powerful way in which you can customise CixRead to
your own taste, the script facility allows you to create new commands,
or modify the effects of existing ones. CixRead scripts are similar to
the batch files found under MSDOS, or the script files found on Unix
systems. They allow you to group a set of CixRead commands together,
and execute them in one go. Complex commands can be written in a BASIC
like language which includes conditional commands, loop commands,
numeric and string variables, parameters, and a large number of
special variables that allow you to access the internals of CixRead.
Scripts can be created using a normal text editor, such as Tempus, or
CixRead's full screen editor. They should be placed in the scripts
directory within your CixRead folder. For example, if you are using
the default location for CixRead, they will be stored in the directory
/CIXREAD/SCRIPTS n Scripts should have the file extender `.RUN',
and the name that you wish to call them by.

For example, if you had a script to upload files to Cix, you might
call it `FUL'. The filename you should save it under would be
`FUL.RUN'. Its full path would be \CIXREAD\SCRIPTS\FUL.RUN

You can also run scripts that are not in your scripts directory by
giving their full path to the RUN command, eg:

RUN D:\SOME\OTHER\PATH\TEST.RUN

   6.5.1 Running a script

To run a script, use the CixRead command RUN, followed by the name of
your script, and any parameters it requires. Alternatively, you can
use the shorthand @ < scriptname > . For example, if you have a script
called test, you might run it with the command:

RUN test one two 3

or

@test one two 3

This would run the script `test', with the three parameters `one',
`two', and `3'.

   6.5.2 Commands

Essentially any command that you would normally enter from the command
line can be included in a script. Many useful scripts might simply
consist of two or three CixRead commands chained together in this way.
In addition to the normal CixRead commands, there are 7 extra
commands, not available from the command line. These are described
below:

                                        54


  Command: BREAK
  Abbrev : BREAK
  Returns: no return

Causes Cixread to continue execution after the end of the current
REPEAT or WHILE loop.

  Command: CONTINUE
  Abbrev : CONTINUE
  Returns: no return

Causes the script to continue execution at the start of the current
REPEAT or WHILE loop.

  Command: ECHO < string > ECHO ON | OFF
  Abbrev : ECHO
  Returns: no return

This controls output to the screen during execution of a script. If a
line `ECHO ON' is encountered in a script, CixRead will start echoing
all lines it encounters in the script to the screen, useful for
testing your scripts. The line `ECHO OFF' will stop commands being
echoed to the screen. The default is not to echo commands.

The command ECHO < string > will cause < string > to be echoed to the
screen. < string > is taken to start from the first character after
the space after the echo command, up to the end of the line. CixRead
variables and parameters (see later) can also be included in the line
to be echoed. < string > will be echoed whether or not echo is set to
on or off.

  Command: EXIT [ < returnvalue > ]
  Abbrev : EXIT
  Returns: specified by user

Causes the current script to finish. Control will be returned either
to the command line or to the script that called the current script,
as appropriate. If < returnvalue > is given, then the variable $r will
be set to this value, else it will be set to zero.


                                 55


  Command: IF < expression >
            < commands >
           [ELSE ]
            [ < commands > ]
           ENDIF
  Abbrev : IF, ELSE, ENDIF
  Returns: no return

The IF command allows you to execute commands if certain conditions
are met. If < expression > (see later for details on expressions)
evaluates to TRUE (non-zero) the com- mands will be executed. The
optional ELSE statement allows you to specify a set of commands that
will be executed if < expression > is FALSE, ie either the first set
or the second set of commands will be executed, depending on the value
of < expression > .

  Command: REPEAT < commands > UNTIL < expression >
  Abbrev : REPEAT, UNTIL
  Returns: no return

The REPEAT command allows you to specify a set of commands that are to
be executed repeatedly until a condition is satisfied. The command(s)
between the REPEAT and the UNTIL will be executed until < expression >
is TRUE. Note that unlike the next command, WHILE, the command(s) will
always be executed at least once.

  Command: WHILE < expression >
             < commands >
           WEND
  Abbrev : WHILE, WEND
  Returns: no return

Like the REPEAT command, this construction allows you to specify a set
of commands that will be executed repeatedly. Unlike REPEAT,
< expression > is evaluated before any of the commands are executed, so
if it is FALSE the commands will never be executed. If it is TRUE, the
commands will be executed until < expression > is FALSE when the start
of the loop is reached.

                                 56

   6.5.3 Parameters

CixRead allows you to pass parameters into your scripts. These are
referenced within the script as $1, $2, $3, ... $9, ie you can have up
to 9 parameters to a script. Also, $0 will contain the name of the
script. The example below illustrates the use of parameters, as well
as a few of the commands described above. The scripts name is test (ie
it is stored as test.run)

echo My name is $0.
echo
IF ($1+$2)<20
echo $1 + $2 is less than 20
ELSE
echo $1 + $2 is 20 or more
ENDIF

If we run this with `run test 1 13', we would get the output shown below:

My name is test
1 + 13 is less than 20


   6.5.4 Variables

In addition to the user supplied parameters, ten string variables and
ten integer variables are provided. The string variables are $s0 to
$s9, and the integer variables are $v0 to $v9. You can assign a value
to a string variable using $s0="example string" (for string variable
zero), and to an integer variable using $v0=12. These variables are
set to empty strings or zero respectively when CixRead starts, however
they do retain their values between consecutive scripts. In other
words, if your script exits with $v4 equal to five, it will still be
equal to five when the next script is run.

   6.5.5 Special Parameters

CixRead offers a selection of special parameters that allow you to
interact with its internals.  Parameters are also available to get
text input from a user, and to handle a GEM fileselector.  Like the
variables and the script parameters, these consist of a letter or word
prefixed by a `$'. The list below describes the available parameters.

$F - draws a GEM fileselector and accepts user input. On return, $F
     will expand to the full path and filename selected by the user, or an
     empty string if the Cancel button on the fileselector was pressed.

                                  57

$FLIST - expands to a 1 if the current topic has an flist online, else 0.

$H - expands to the current time and date in the format
       DDD MMM dd hh:mm:ss YYYY
     where DDD is the day of the week, MMM is the month, dd is the day of
     the month, hh:mm:ss is the hours:minutes:seconds, and YYYY is the year,
     for example,
       Wed Sep 04 15:13:22 1985

$I - accepts a line of text from the user. A ` > ' will be printed at
     the left of the screen, and the system will pause and wait for input.
     The input() function provides a superior method of doing this.

$M - this will expand to the number of the conference message
     currently being viewed, or -1 if the user is not in a topic.

$MOD - this exapnds to a one if you are the moderator of the current
       topic, else to a zero

$NOTE - expands to the current notebook path

$O - if the message currently being viewed is a comment, this will
     expand to the message number of the original. If the current message
     is not a comment, or the user is not in a topic, this will expand to
     -1.

$P - this will expand to the current path that CixRead is now in, and
     the filename minus the extender of the files used by the current
     topic. For example, if you were in the topic frogs/spotted, this would
     probably expand to: <drive>:\cixread\frogs.000\spotted where
     drive is the drive letter of the drive you are running CixRead on.

$R - this expands to the value returned by the last CixRead command to
     be executed. The values returned by each command are detailed in the
     descriptions of each command.

$RDONLY - this expands to a one if the current topic is read only, or
     to a zero if it is not

$REPLY - expands to the current upload script path.

$ROOT - expands to the path of the currently active message base.

$T - this expands to the name of the conference and topic the user is
     currently viewing, or an empty string if not in a topic.

$W - this tells you what the current prompt level is, ie
       0 = > currently at the Main: prompt - ie not in a topic
       1 = > currently in a topic, but not in ref mode
       2 = > currently in the mail system
       3 = > currently at the options menu
       4 = > currently in a topic in ref mode

$WHO - expands to the name of the person who posted the message you
     are currently viewing.

$X - this expands to a one if the user is in expert mode, and to a zero if not.

                                     58

$# - expands to the number of parameters passed on the command line to
     the current script.

$$ - expands to a single `$' character.

These parameters, and the standard script parameters ($0 - $9) should
not be considered as variables. They are in fact macros, and are
simply expanded within the current line of input.  The most important
effect of this is seen when assigning one of the above to a string
variable.  For example,

   $s1 = $t

might expand to

   $s1 = atari.st.olr/programs

This would cause a syntax error, since the topic name is not enclosed
in quotes. The correct form would be

   $s1 = "$t"

which would expand to

   $s1 = "atari.st.olr/programs"

which is correct.

It is also possible to apply the modifiers ` < ' and ` > ' to many of
the above parameters. These have the effect of extracting different
parts of the results. Below is a description of each of the possible
uses of this.

   $H> - the current time
   $H< - the current date
   $I> - this will return the part of the users input following a '\'
         character. If no such character is present, the whole of the users
         input will be returned.
   $I< - this will return the part of the users input up to and including a
         `\' character. If no such character is present, an empty string will
         be returned.
   $F> - this will return just the filename part of the string returned by
         a fileselector. If no filename is present, this will return an empty
         string.
   $F< - this will return the path part of the string returned by a
         fileselector, terminated by a `\'.
   $P> - this will return the generic filename used by files of a particular
         topic.
   $P< - this will return the current path used by CixRead, terminated with
         a `\' character.
   $T> - this will return the current topic name.
   $T< - this will return the current conference name.
                                     59

These modifiers can also be applied to the parameters $0-$9 and the
string variables $s0-$s9, in which case they will attempt to split the
corresponding string into path and filename parts.

   6.5.6 Accessing Environment Variables Within Scripts

You can read the environment from within a script using the special notation:

  ${variable name}

For example, to set string variable 1 to be equal to the PATH variable,
you would use:

  $s1 = "${PATH}"

   6.5.7 Special Functions (tilde functions)

This section of the manual describes a set of special functions for
use in CixRead scripts. All of the functions begin with the tilde
character, hence the name. The functions are divided into three
general areas: file handling, string manipulation, and miscellaneous.
Note that, like the various $variables, these functions are handled as
macros. This means that if you wish to assign the result of function
to a string variable, you must enclose it in quotes. For example, to
place the length of a string into an integer variable, use $v1 =
~length("string"), but to place the length into a string variable (ie
converting it to a string), use $s1 = "~length("string")".

The descriptions that follow come in four parts. Firstly the name of
the function is given, along with a list of parameters. Next the
parameters are described. Note that parameters described as strings
must be enclosed in quotation marks. The third field gives a list of
possible errors. These are returned in the variable $r, and are in
addition to whatever the function expands to. Lastly a description of
the function is given.

                                 60

File Handling: The following functions allow you to manipulate files
from within CixRead scripts. Please note that these are only meant to
be used with small files. In practice, this means that the function
lof(), loc(), and fseek() are only accurate up to 32Kbytes. To be
frank, if you need to interact with files any bigger than that, you're
probably better off writing a dedicated program to do the work.

CixRead allows you to have up to ten files open simultaneously, using
streams numbered 0 to 9. Each file can be opened either for reading,
or for writing (appending). If you don't want to append to a file,
delete it first.

=====
FUNCTION: open(mode,stream,filename)
PARAMETERS: mode: string, "I" for reading, "O" for writing
            stream: integer, selects stream number for this file, 0-9
            filename: string, the name of the file to open
RETURNS: 0 no errors
         -1 general error, file could not be opened (doesn't exist?)
         -2 mode is not I or O
         -4 Invalid stream number
DESCRIPTION: Open the file given by f ilename in the mode specified by
mode , and assign it to stream stream . Expands to an empty string.

                                61

=====
FUNCTION: close(stream)
PARAMETERS: stream: integer, the stream to close
RETURNS: 0 no errors
        -1 general error
        -3 file is not open
        -4 invalid stream
DESCRIPTION: Close the file specified by stream .


=====
FUNCTION: erase(filename)
PARAMETERS: filename: string, file to delete
RETURNS: 0 no errors
        -1 general error
DESCRIPTION: Erase the specified file

                                  62

=====
FUNCTION: flush(stream)
PARAMETERS: stream: integer
RETURNS: 0 no errors
         -1 general error
         -3 file not open
         -4 invalid stream
         -5 attempted to flush a file opened for reading only
DESCRIPTION: Flush the contents of the specified stream to the disk.
Only available on files open for writing (obviously)

=====
FUNCTION: exists(filename)
PARAMETERS: filename: string
RETURNS: no returns
DESCRIPTION: Expands to 0 if the file does not exist, or 1 if it does.


                                         63

=====
FUNCTION: read(stream)
PARAMETERS: stream: integer
RETURNS: 0 no errors
         -1 general error
         -3 file not open
         -4 invalid stream
         -7 file opened for writing
DESCRIPTION: Expands to a line read from the current location in the
specified file.


=====
FUNCTION: write(stream,line)
PARAMETERS: stream: integer
            line: string
RETURNS: 0 no errors
         -1 general error
         -3 file not open
         -4 invalid stream
         -6 file opened for reading
DESCRIPTION: Writes line to the end of the specified file.

                                  64

=====
FUNCTION: lof(stream)
PARAMETERS: stream: integer
RETURNS: 0 no errors
         -1 general error
         -3 file not open
         -4 invalid stream
DESCRIPTION: Expands to the current length of the specified file.


=====
FUNCTION: loc(stream)
PARAMETERS: stream: integer
RETURNS: 0 no errors
         -1 general error
         -3 file not open
         -4 invalid stream
DESCRIPTION: Expands to the offset of the file pointer into the specified file.

                                   65

=====
FUNCTION: fseek(stream,offset,mode)
PARAMETERS: stream: integer
            offset: integer
            mode: integer
RETURNS: 0 no errors
         -1 general error
         -3 file closed
         -4 invalid stream
         -7 file opened for writing
         -8 bad value for mode
DESCRIPTION: Move the file pointer for the specified file to the
position specified by offset . mode specifies the location to take
the offset from, as follows:

     mode     take offset from
       0        start of file
       1        current position
       2        end of file

This function is only available for files opened for reading.


================================================
                                     66

String Manipulation: CixRead offers a group of functions for
interacting with strings. These are described below:

=====
FUNCTION: mid(string,start,count)
PARAMETERS: string: string
            start: integer
            count: integer
RETURNS: 0 no errors
         -1 string contains less than count characters
DESCRIPTION: Expands to the substring of string , starting from
character number start and containing count characters.


=====
FUNCTION: left(string,count)
PARAMETERS: string: string
            count: integer
RETURNS: 0 no errors
DESCRIPTION: Expands to the leftmost count characters of string .

                                      67

=====
FUNCTION: right(string,count)
PARAMETERS: string: string
            count: integer
RETURNS: 0 no errors
DESCRIPTION: Expands to the rightmost count characters of string .


=====
FUNCTION: contains(string1,string2)
PARAMETERS: string1: string
            string2: string
RETURNS: n as described below
DESCRIPTION: Expands to zero if string 1 does not contain string 2, or
the position of the first occurence of string 2 within string 1 if it
does. This is also returned in $r.

                                     68

=====
FUNCTION: length(string)
PARAMETERS: string: string
RETURNS: n as described below
DESCRIPTION: Expands to the length of string . This is also returned in $r.




=====
FUNCTION: word(string,count)
PARAMETERS: string: string
            count: integer
RETURNS: 0 no errors
DESCRIPTION: Expands to word number count from the string string .


================================================
                                   69

Miscellaneous: That is, functions that don't fit under the other headings:

=====
FUNCTION: yes(prompt)
PARAMETERS: prompt: string
RETURNS: 0 user replied "no"
         1 user replied "yes"
DESCRIPTION: Prints the string prompt to the screen, and waits for the
user to reply. Expands to 0 if the user replies "no", or 1 if the user
replies "yes". This is also returned in $r.


=====
FUNCTION: view(filename)
PARAMETERS: filename: string
RETURNS: 0 File viewed OK
         1 An error occurred
DESCRIPTION: This function allows you to display a file to the screen
with paging controlled by the user.

                                      70

=====
FUNCTION: input(prompt)
PARAMETERS: prompt: string
RETURNS: 0 No error
DESCRIPTION: Prints the prompt and waits for user input. Expands to
the line of text entered by the user.




=====
FUNCTION: editor(message)
PARAMETERS: message: string
RETURNS: 0 No error
DESCRIPTION: Invokes the internal editor from within your script. The
text given in message will be displayed on the editor's status bar.

                                         71

=====
FUNCTION: editfile(file,message)
PARAMETERS: file: string
            message: string
RETURNS: 0 No error
DESCRIPTION: As for the editor() function except this function will
automatically load in the named file on startup.


=====
FUNCTION: dumpedit(filename)
PARAMETERS: filename: string
RETURNS: 0 No error
DESCRIPTION: Writes the contents of the edit buffer to the named disk
file. In other words this is the command that actually stores the data
you've just collected from the user. If the file exists, the edit
buffer will be appended to it.

                                         72

=====
FUNCTION: killedit()
PARAMETERS: none
RETURNS: 0 No error
DESCRIPTION: Kills the current edit buffer (ie returns its resources
to CixRead). The contents are lost.

   6.5.8 Operators

Numeric operators: CixRead offers the following operators when
working with numbers and numeric variables.

=   : assign the value on the right of the sign to the variable on the
    left. The right hand side can be a complex expression, eg

$v1 = $v1 + 4/5 - ((6 + 4) = ($v2/4))

+, -, /, * : add, subtract, divide or multiply the values on either
    side of the sign, eg $v1+5 ; 6/2

% : returns the remainder of the left side value divided by the right
    side, eg 6%4 is equal to 2

&, | : returns the bitwise AND, or the bitwise OR of its operands, eg
    15 & 3 = 3 (in binary 1111 AND 0011 = 0011)
    15 | 3 = 15 (in binary 1111 OR 0011 = 1111)

&&, || : returns the logical AND or the logical OR of two expressions.

== : TRUE if the left hand side is equal to the right hand side, eg,
    6 == 6 is TRUE, 6 == 3 is FALSE

!= : TRUE if its operands are not equal.

< , > , < =, > = : True if the left hand side is less than, greater
    than, less than or equal to, or greater than or equal to the right
    hand side.

                                    73

String operators: In the following examples, s1 and s2 are strings.

 s1 = s2 : set string s1 equal to string s2.

 s1 == s2 : TRUE if string s1 is equal to string s2.

 s1 != s2 : TRUE if string s1 is not equal to string s2.

   6.5.9 Expressions

Expressions can be of arbitrary complexity, and contain any of the
valid tokens. An expression is TRUE if it evaluates to non zero, else
it is FALSE. Brackets `(' and `)' can be used to group parts of
expressions, for example,

  6 + 4 * 5

would normally be evaluated as though it had been written

  6 + (4 * 5).

You can use brackets to force it to be evaluated as

  (6 + 4) * 5

   6.5.10 Comments

Any line in a script beginning with a `*' character will be treated as
a comment line, and ignored. Also leading spaces on a line are
removed, so you can use tabs or space characters to format your
scripts. Note that this does not apply to comment lines - the first
character in a comment line must be a `*'.

                                       74

  6.6 Special Script Files

There are 4 special script files that CixRead knows about. These are
described below.

   6.6.1 Profile

The file `profile.run', or just `profile' in your scripts directory is
a special script. It is executed whenever you run CixRead. This makes
it useful for setting up CixRead options or defining aliases. The
example below does this.

* set aliases
alias fdl run fdl.run
alias olr join atari.st.olr
* set pagelength to 22 lines
opt page 22
* set external editor to Tempus 2, and select it as the default
opt edit c:"tempus.prg
* set path where temporary files for editor will be stored
opt temp c:"work"
* select read ref mode forward
opt ref forward
* prompt to delete a previous upload file
killscript

   6.6.2 Logout.run

Like your profile, this script will be automatically executed by
CixRead, however this script will be executed whenever you exit
CixRead.

   6.6.3 Function Keys

The file `fkeys.run' in you scripts directory is run immediately after
your profile. It is used for function key definitions, and is normally
created automatically for you when you select `Save' from the set
function keys dialogue box. You can of course edit it yourself using a
text editor. NOTE: This file will be overwritten every time you select
`Save' from the set function keys dialogue box, so do not use it for
anything except setting function keys. Use the profile instead.  Also
note that any function keys defined in your profile will be
overwritten by keys defined in this file.

                                     75

   6.6.4 Restore

The file `restore.run' in your scripts directory is automatically
created by the splitter every time you run it. It contains a list of
instructions to return your message database to the state it was in
before you last ran the splitter, similar to the restore command
available on Cix itself. You can run it using either

   RUN RESTORE

to restore all topics, or

   RUN RESTORE < conference > / < topic >

to restore a single topic. Note that you must supply the full
conference and topic names for this to work.

                                   76

  6.7 Signature Files

CixRead allows you to automatically sign messages with one of two
predefined signature files.  You can have a short (maximum 80
characters) signature for use in topics, and a longer (maximum 1K)
signature for mail. You should prepare these using a standard text
editor. They should both go in your CixRead directory. The topic
signature should be saved as `cixread.sig' and the mail signature
should be `mail.sig'

There are three ways of including them in messages:

 1) Use the special keys in the editor.
 2) Put `OPT SIGN YES' in your profile, and the correct signature will
    automatically be appended to anything you post
 3) A line containing `#sig' (and nothing else) will be expanded to
    the relevant signature wherever it is found in a message

Remember - a long signature, whilst undoubtedly very pretty, is
unlikely to earn you many friends on Cix.

                                      77

 7 The Editors

CixRead provides a choice of an internal full screen editor or your
favourite external editor for editing messages, and a fully editable
command line with history recall for entering commands.

  7.1 External Editors

You can instruct CixRead to use the editor of your choice when editing
messages, files, etc.  This allows you to use a much more
sophisticated editor, but it does mean it will need to be loaded into
memory every time you use it, and it will not be as well integrated
with CixRead as the internal editor. You pays your money and you takes
your choice...

There are two commands associated with the external editor:

 1) opt edit <path> - this should be the full path and filename of the
                      editor you wish to use.

 2) opt temp <path> - this is the path you wish the editor to create its
                      temporary files in.  You may find that this needs
                      to be set to the path of your editor, especially
                      if it uses Gem.  If the environment varialbe TMP
                      is present, CixRead will use this as the path, although
                      an opt temp statement will take precedence.

Both commands can be placed in your profile for convenience. You can
also use opt edit without a path argument to set all of the options
via a dialog box.  If you are commenting or replying to a message, you
will find that the relevant message should be loaded into the editor
for you to edit.

If you wish to use signature files with the external editor, you
should issue an opt sign y command to have them automatically appended
to your postings.

                                    78

  7.2 The Internal Editor

This section is currently being rewritten.

                                    79

  7.3 The Command Line
The command line gives full editing facilities, and the ability to
recall a previous command line for editng/reentry.

   7.3.1 The History Buffer

CixRead will remember any lines you have previously entered, and
allows you to recall them at will. The up and down arrow keys can be
used to scroll through previous command lines. Cursor up moves you
backwards through the history buffer, whilst cursor down moves you
forward. Pressing `Escape' will clear the current line.

You can alter the number of lines CixRead will remember using the `opt
history' command.  The commands are stored in a circular buffer, so
once the buffer is full the earliest commands will start to be
overwritten.

More than one command can be included on a single line by seperating
them with `;'s. You can also in fact build a mini-script on a single
line this way, eg

  echo start; $v1=0; while $v1<10;echo $v1;$v1=$v1+1;wend;echo finished

is a valid command line. 

                                       80

Appendix A Coredumps

CixRead supports a (very) rudimentary coredump facility. In the event
of CixRead crashing, you will be presented with an alert box
containing some processor information at the time of the crash. This
information is useful to me for fixing the bug that caused the crash,
especially if it is a bug that I am unable to reproduce on my machine,
so please report it online. The alert box may give you the option of
continueing, in which case you will restart at the main prompt.
Proceed with caution, as the crash may have damaged the program (the
version in memory, not the disk version).

Also, CixRead now produces a coredump file on crashing. Unix users
will be happy to know that this is only about 600 bytes in length. The
file is written to /cixread/core. It contains more detailed
information on the state of the processor when the crash occured.  In
addition to the above, if a crash occurs when you are editing a file
with the internal editor, the file will be saved to disk, and you will
be able to load it back into the editor and continue.

                                   81
