                Installation Notes for CixComm version 1.15
                ===========================================

                      Copyright (c) Andr Willey, 1992




Before You Start
================

The latest versions of CixComm are much more intelligent than earlier
releases, and require virtually no setting up on the part of the user. Of
course, there are a myriad of wonderful options available to you once you're
used to the system, but the default settings should you up and running
immediately. There is no longer any need for the first time user to create
environment variables, alter CIX's online profile settings, or hand-edit any
default files - it's all automatic.


First, if you have already installed kebab's Cixread program, simply copy
the two CixComm files, along with the XYZ.TTP file-transfer utility
(available from atari.st.olr/programs), into the same directory (folder)
that contains your CIXREADx.PRG and SPLITx.TOS programs.

If you haven't installed Cixread as yet, download both the main Cixread
program and the Splitter utility from atari.st.olr/programs, and put them
into a new folder. Then copy the CixComm files (plus XYZ.TTP) into the same
folder.

You should now have at least the following files in your new folder:

    CIXCOMM.PRG
    CIXCOMM.RSC
    XYZ.TTP
    CIXREADx.PRG
    CIXREAD.RSC
    SPLITx.TOS

Before you can actually log on to CIX, CixComm needs to know your own CIX
username (e.g. kebab, andre, gminnerup, etc) and your personal password.
These will be requested when you first run CixComm. Once you have entered
these details, save your new settings back to the disk file `DEFAULT.CCD'.
For security reasons, your password will be saved in an encrypted form.

If you make a mistake, you can edit the information later via CixComm's
`Configuration Editor', obtained by pressing the `Clr/Home' key from the
Terminal screen.


Note: The `Edit Phone Numbers' option in the Configuration Editor currently
contains all four CIX phone numbers. The first two lines are used to access
CIX's various high-speed modems, while the final two provide access the
general purpose 2400/MNP modems. If you are only using a 2400 baud modem,
please delete the first two phone numbers in order to avoid tying up CIX's
high-speed access ports.



Your First session
==================
Congratulations! You are now ready to undertake your first automated
CixComm/Cixread session. When you run CixComm, it will ask which operation
you require. Click on `Logon' and sit back and relax while CixComm does all
the work for you.

If everything goes according to plan, the system will now log on to CIX,
download your new mail and conference messages, then logoff and split the
messages into a form that Cixread can understand. Finally it will run the
Cixread program to allow you to browse through your messages. Whenever you
create any replies, these will be stored ready for your next online session,
when they will be sent automatically to CIX.


If you have any questions or problems, please post a message in
atari.st.olr/cixcomm, or e-mail me as andre@cix. I'll do my best to sort
things out for you as quickly as possible.



CixComm Configuration Data (.CCD) files
=======================================

CixComm Configuration Data files are used to provide CixComm with the
information it needs to communicate with CIX, and to locate other files and
folders.

These `.CCD' files are pure ASCII text files, consisting of a sequence of
english-like setup instructions which may be edited via a standard text
editor, or alternatively from within CixComm's own Configuration Editor. To
access the CixComm Configuration Editor, simply press the `Clr-Home' key
from within the Terminal screen.

Note: If you prefer to use a word processor, please make sure that you save
the file as "pure ASCII text", not as a word processor document with
included style tags.

The format of a .CCD file is simple: Most instructions consist of just two
lines - a command line which starts with a `%' character, followed by a
separate line (sometimes multiple lines) containing the required setting(s).
Comments may be added by inserting one or more lines which start with a `;'
character, and any empty lines in the file will be ignored.

DEFAULT.CCD is the configuration file which will normally be used by
CixComm, and it should be located in the same directory as the CIXCOMM.PRG
program file.

Advanced User Note: If you are using a `CIXCOMM=' environment variable from
your desktop, the DEFAULT.CCD file must be located within that specified
directory.


The following configuration file commands and instructions are supported by
CixComm version 1.15 and above:


%CixComm Parameter File
-----------------------

    This is just a header line to confirm that this is a .CCD file, and must
    always be the very first line. No parameter line should follow it.


%Environment
------------
Default: None defined

    Environment variables are a way of informing a number of different
    programs about some piece of information which is important to all of
    them; perhaps the location of a data file or a pathname.

    This command allows you to define up to 10 environment variables which
    are then used by CixComm. They are also made available to other programs
    which are run from within CixComm (such as CIXREADx.PRG or the
    Splitter).

    The standard environment variable format consists of a name (in
    uppercase only), followed immediately by an `=' sign, then the variable
    contents themselves.

    For example, assuming that you have a CIXCOMM folder on drive E:, and
    your CIXREAD folder on drive D:, you might define the following
    environment variables:

        %Environment
        CIXCOMM=E:\CIXCOMM\
        CIXREAD=D:\CIXREAD\
        REPLY=E:\CIXCOMM\REPLY.SCP
        SCRATCH=E:\CIXCOMM\SCRATCHP

    This setup will keep all your support files neatly within the CIXCOMM
    folder, except for the Cixread message base itself which is on drive D.
    Actually, in the above example the last two lines are redundant since if
    no such variable exists, the values for `REPLY=' and `SCRATCH=' default
    to the files REPLY.SCP and SCRATCHP in the current CixComm folder.


%RS232-Port number
------------------
Default: 0

    This is used on MEGA-STE and TT computers ONLY, and allows you to tell
    CixComm which RS232 port to use. On a TT, these are numbered from 1 to
    4. Set this value to zero if using a standard ST, or to use the default
    port setting on a MEGA-STE/TT.


%Flow control
-------------
Default: RTS

    Allows you to change the flow control mode between your computer and
    your modem. May be set to `OFF' for no flow control, `XON' to use
    Xon/Xoff flow control, `RTS' to use CTS/RTS flow control, or `ALL' to
    use both the Xon/Xoff and CTS/RTS modes. The CTS/RTS flow control option
    is *highly* recommended; use the others at your own peril.

    IMPORTANT: There are bugs in the TOS routines which handle CTS/RTS flow
    control. When using this facility, please ensure you have an appropriate
    patch program in your AUTO folder (see separate section on flow control
    at the end of this document).


%Cursor Flash rate
------------------
Default: 35,8

    This is gwyn's personalised command! It defines the rate of the flashing
    cursor, in normal and auto-sequence modes respectively. A value of zero
    indicates a steady (non-flashing) cursor. Otherwise, the larger the
    number the slower the flash rate will be.


%Startup
--------
Default: PROMPT

    This command defines how you wish CixComm to behave when you load it.
    The options are `CIXREAD', `TERMINAL', `AUTO' or `PROMPT'.

    If set to 'CIXREAD', your session will start by entering Cixread to scan
    your current message base. If set to `TERMINAL' you will be taken
    straight to the Terminal screen with no automatic operations performed.
    If set to `AUTO' (the most powerful option, and the one I recommend for
    general use) then the full sequence of
    logon/script/download/split/Cixread/etc cycle will commence.

    If set to `PROMPT', you will be shown an alert box from which you may
    manually choose any of the above three options.


%Autotimer
----------
Default: 00:00-24:00

    Additional option which controls the operation of the `AUTO' %Startup
    setting. It limits the times of day at which CixComm will automatically
    log on to CIX. This facility is useful if you wish to ensure that
    CixComm only phones CIX at cheap rates. For example, a setting of
    `18:00-8:00' would only allow the AUTO system to phone CIX between the
    hours of 6 pm and 8 am. A phone-bill masochist might use a setting of
    `09:00-13:00', which would force CixComm to phone during the peak rates
    of 9 am to 1 pm. The default setting allows CixComm to phone CIX at any
    time of the day or night.

    You can override this option by pressing the `F1' key manually.


%Initialise modem sequence
--------------------------
Default: Not defined

    This is optional, and allows you to specify a Hayes-type command
    sequence to send to your modem before it attempts to dial in to CIX.
    Usually these settings would be in battery-backed memory in the modem,
    so most people will not need to use this command.


%Escape code
------------
Default: 43

    This defines the ASCII number of the escape code used by your modem to
    quit from online operation back to its command mode. The default for
    most Hayes compatible modems is 43, which issues the well-known `+++'
    string.

    Note: This system can be overridden by the DTR option in the %Hangup
    modem command below.


%Hangup modem
-------------
Default: AT H

    This specifies the command to tell your modem to hang up the phone line
    (usually this would be `AT H'). If your modem will hang up the phone
    line when the RS232 DTR line is lowered, set this option to `DTR', and
    the Escape code (above) & hangup sequence will be ignored.


%Connect
--------
Default: CONNECT

    This tells CixComm what single response to expect from your modem to
    indicate that it has connected correctly to CIX's modem. In most cases,
    this would simply be `CONNECT' so that all possible variations of
    connection are detected.

;
%Failed
-------
Default: NO CARRIER|BUSY|NO ANSWER|NO DIALTONE|ERROR

    This tells CixComm what responses it can expect from your modem to
    indicate that the connection to CIX's modem has not been established.
    There are often a number of possible failure messages, so enter up to
    six responses, with `|' characters between each one. e.g.

        %Failed
        NO CARRIER|BUSY|NO DIALTONE|ERROR


%Phone number dial sequences
----------------------------
Default: All CIX phone numbers, at 19200 baud

    You may define up to ten Hayes-type dial commands to instruct your modem
    to dial CIX's phone numbers. Comment out any numbers you don't wish to
    access (using `;'), and remove the `081' codes if they are not needed.
    Each number is followed by an appropriate RS232 baud rate - however if
    your modem can speed-buffer you should set all of these to the highest
    speed it will handle (usually 19200).

    For example if you have a 2400 bps modem but are using a 9600 baud link
    between your ST and the modem, your phone number list would look like
    this:

        %Phone number
        AT D 081 390 1244   <9600>
        AT D 081 399 5252   <9600>

    If you have set up a Mercury access code (see below), place a `$' sign
    at any point where you wish your Mercury code to be inserted. The above
    number sequence would thus look like this:

        %Phone number
        AT D $ 081 390 1244   <9600>
        AT D $ 081 399 5252   <9600>

    IMPORTANT: Since most people now use these higher computer-to-modem baud
    rates, it is very important to ensure that your ST and modem are set up
    to use `CTS/RTS' handshaking (refer to `%Flow' to set this mode). Some
    ST's have bugs in this section of the operating system which need a
    patch program in the AUTO folder. See section on flow control at the end
    of this document for more information.


%Mercury
--------
Default: None

    If you have an account with Mercury Communications, and wish to use this
    to connect to CIX, you can store your Mercury customer number in your
    .CCD file. Then, whenever a `$' sign is found in a phone number entry,
    it will be replaced by this series of Mercury digits.

    Don't forget that this string forms part of the dial sequence, so you
    must include all the digits (including the initial 131, and any pauses
    your exchange requires). e.g.:

        %Mercury
        131,,1234567890

    (where 1234567890 is your Mercury PIN number)

    If you save a .CCD file from within CixComm's own Configuration Editor,
    this line will be encrypted for security reasons.


%Retry times
------------
Default: 3

    If the current phone number doesn't work (e.g. if it is engaged), it
    will be retried this number of times before moving on to the next number
    on the list. Once the end of the list has been reached, CixComm will
    start again at the first entry until the value given for the total
    number of attempts has been reached (see below).


%Delay
------
Default: 2

    This option allows you to alter the number of seconds of delay between
    retry attempts to each phone number. The default setting is to retry
    immediately (2 seconds), but you may like to change this to around a
    minute if you get a lot of busy lines.


%Total Attempts
---------------
Default: 100

    This options allows you to alter the total number of dialler retries
    allowed before CixComm gives up and reports an error.


%Username
---------
Default: Aw, C'mon!

    This line contains your own personal CIX username (e.g. andre, kebab,
    etc.)


%Password
---------
Default: Aw, C'mon!

    This line contains your own personal CIX password. (Note: it is case
    sensitive).

    If you save a .CCD file from within CixComm's own Configuration Editor,
    this line will be encrypted for security reasons.


%Zmodem-Download program (with optional parameters)
---------------------------------------------------
Default: File XYZ.TTP in the current directory, with parameter `-s'

    This identifies the path and filename of the external file transfer
    program you wish to use for downloading, along with any required
    parameters. When called, these parameters will be passed to the zmodem
    program, followed by a default path in which to store the downloaded
    files.

    Normally this program would be XYZ.TTP (version 2.01 is available from
    the FLIST in atari.st.olr/programs), using the parameter -s. For
    example, if your Zmodem program was on drive D:, in the folder COMMS,
    you might use the command:

        %Zmodem-Download
        D:\COMMS\XYZ.TTP -s

    Note: The Zmodem program must be capable of returning a status value,
    indicating the success or failure of the download. CixComm assumes any
    non-zero value means an error has occurred.


%Zmodem-Upload program (with optional parameters)
-------------------------------------------------
Default: File XTY.TTP in current directory, with parameters `-u -s'

    This identifies the path and filename of the external file transfer
    program you wish to use for uploading, along with any required
    parameters. When called, these parameters will be passed to the zmodem
    program, followed by the full path and name of the file to be uploaded.

    Normally this program would be XYZ.TTP (version 2.01 is available from
    the FLIST in atari.st.olr/programs), using the parameters      -u -s.
    For example, if your Zmodem program was on drive D:, in the folder
    COMMS, you might use the command:

        %Zmodem-Upload
        D:\COMMS\XYZ.TTP -u -s

    Note: The Zmodem program must be capable of returning a status value,
    indicating the success or failure of the upload. CixComm assumes any
    non-zero value means an error has occurred.

%Z-Download-Path
----------------
Default: Current directory

    This defines the default path to which any files downloaded by the auto-
    Zmodem system will be saved.

    Note: This path is not used to locate the scratchpad file, which instead
    has its own environment variable (see above).


%Z-Upload-Path
--------------
Default: Current directory

    This defines the default path from which files will be uploaded when
    using the auto-Zmodem system. You may optionally append a filename to
    this path, which will then appear in the filename line of the file
    selector box which appears when an upload is requested.

    Note: This path is not used to locate the REPLY.SCP file, which instead
    uses its own environment variable (see above).


%Options
--------
Default: OPT TERS,COM N,UP W,DO Z,SCRATCHN $$$,MIS Y,
         FILE S Y,ED V,TERM WID 200,AN N,REC 10,AU Y,Q

    When you logon to CIX there are certain options which must be set in
    order for CixComm and Cixread to work correctly (such as using Zmodem
    file transfers, and enabling CIX's TERSE mode). This special commandline
    allows you to set any of these facilities, and it will be automatically
    executed as part of every logon cycle (unlike the %Message command which
    is only executed when you begin an Auto-sequence download session).

    The above default line may look complicated, but it breaks down into a
    set of simple (if highly abbreviated!) commands. Note: Any commands
    which are already part of your online CIX profile may be safely removed
    from this commandline.

    The default commandline consists of the following OPTION commands:

        TERSE
        COMPACT NO
        UPLOAD WZMODEM
        DOWNLOAD WZMODEM
        SCRATCHNAME $$$
        MISSING YES
        FILE SINGLE YES
        EDIT VERBOSE
        TERMINAL WIDTH 200
        ANSI NO
        RECENT 10
        AUTORECENT YES
        QUIT

    Note1: The string `$$$' will be automatically replaced with the name of
    your Cixread scratchpad file. In this way, CIX will always be able to
    send you the correct scratchpad filename.


    Note2: You may also like to add the command ZWINDOW 0 (abbreviated to ZW
    0) which forces Zmodem to transmit continuous blocks data. This is
    generally faster on a clean phone line, or if you are using an error
    correcting modem (e.g. MNP or V42).


%Message
--------
Default: STORE

    This defines an online CIX command which will be executed before the
    auto-sequence operations are carried out. This facility is useful if you
    want to perhaps issue a STORE command before each session in case of
    errors. I currently have mine set to do a MAIL OUT QUIT, which lets me
    know whether my outgoing mail messages have been read.


%Clear-Mail
-----------
Default: NONE

    This option allows you to automatically remove old (i.e. read) entries
    from your online mail inbasket and/or outbasket. Set to `IN' to clear
    the inbasket only, `OUT' to clear the outbasket only, `BOTH' to clear
    both, or `NONE' (surprise, surprise!) to clear neither.


%Usenet             (only available in registered release of CixComm)
-------
Default: NONE

    This option controls the automatic Usenet downloading system. It has
    four options, `NONE', `SHOW', `ALL' or `AUTO'. If you select `NONE then
    the Usenet system is disabled. If you select `SHOW' then a display of
    unread Usenet messages will be given at the start of every session. If
    you select `ALL' then all unread Usenet messages will be included in the
    scratchpad file when it is downloaded.

    Finally, and most comprehensively, the `AUTO' option may be used to
    selectively download just the messages you are interested in. In this
    case, each online session will cause all of the subject lines from
    unread Usenet messages to be added to a file called USENET.HDR. While
    offline, you can press the `F6' key to select which of those messages
    you want to download, and CixComm will create a script called
    GET_NEWS.SCP. This file will then be used during the next session to
    automatically download the required Usenet messages.


%Usenet-All         (only available in registered release of CixComm)
-----------
Default: Not defined

    Following this command are up to ten lines containing the names of
    selected Usenet newsgroups. If the Usenet `AUTO' mode has been enabled
    (see above), any new messages in these groups will be automatically
    flagged for downloading during the next session. Of course, you can
    still disable specific messages which you don't require by de-selecting
    them from the Usenet dialogue box.


%Usenet-Parameters             (only available in registered version)
------------------
Default: 0

    Selects the startup settings for the Usenet message selector screen. At
    present, only one button is controlled via this command: Use a value of
    '1' to activate the `Select entire threads?' button, or a value of '0'
    to disable it.


%Normal-Function Key settings (only useful in the registered version)
-----------------------------
Default: The default set of CixComm Function Keys

    The following lines specify up to ten CixComm `batch-mode' commands
    which are assigned to Function Keys 1 to 10 (there are three other
    commands to assign the Shift, Control and Alternate Function Keys). Each
    line contains the Function Key number, followed by a space, then the
    command itself. For example:

        %Function Key definitions
        1 SEND SCRATCHSIZE
        4 WAIT 20 Main:
        5 BATCH E:\CIXCOMM\GET_MAIL.BAT
        8 RUN D:\PROGRAMS\DISKSTAT.PRG
        10 UPLOAD D:\COMMS\FILE.PRG

    These commands may be then invoked by pressing the appropriate Function
    Key. The full set of commands for the batch-control system is documented
    elsewhere. Only one command is allowed per Function Key. Since this
    command could be the BATCH <batchfile> command (which executes a
    previously prepared batchfile from disk) this limitation is not all that
    important.

    Note: The first Function Key is a special case in that it is run
    automatically when you load CixComm with the %Startup mode set to
    `AUTO'. Thus if you change this command you can alter the entire CixComm
    startup sequence to your own requirements.


%Shift-Function Key settings   (only available in registered version)
----------------------------
Default: None

    Assigns batch-commands to the Shifted versions of Function Keys 1 to 10.
    Accessed by pressing the appropriate Function Key while holding down the
    `Shift' button. (See above for a fuller description of setting Function
    Keys)


%Control-Function Key settings (only available in registered version)
------------------------------
Default: None

    Assigns batch-commands to the Control versions of Function Keys 1 to 10.
    Accessed by pressing the appropriate Function Key while holding down the
    `Control' button. (See above for a fuller description of setting
    Function Keys)


%Alternate-Function Key settings         (only in registered version)
--------------------------------
Default: None

    Assigns batch-commands to the Alternate versions of Function Keys 1 to
    10. Accessed by pressing the appropriate Function Key while holding down
    the `Alternate' button. (See above for a fuller description of setting
    Function Keys)


%Editor
-------
Default: Not defined

    This optional line specifies the path and filename of your preferred
    external editor or word processor (e.g. Tempus, First Word, Protext,
    etc). If defined, the editor may then be called by pressing the `F9'
    key. This allows you to edit your REPLY.SCP files before uploading, for
    example.


%Archiver
---------
Default: Not defined

    This is another optional feature. If present, it specifies the path and
    filename of your ARC.TTP program, which will be used to de-arc your
    scratchpads after downloading.

    Note: Do not use this option if you have an MNP5 or V42 modem since they
    automatically compress the data for you. In such cases, ARCing your
    scratchpad is usually counter-productive.


%EndCixComm
-----------

    This command acts as a terminator for the .CCD file, and has no
    parameters. Anything after this line will be ignored.



Using "Install Application" with CixComm's .CCD files
=====================================================

If you wish, you can use GEM's "Install Application" system to supply new
.CCD filenames for CixComm to use instead of the DEFAULT.CCD file. From the
desktop, install CIXCOMM.PRG to run whenever you double-click on a .CCD
file. On TOS 2.0 and above, or if you are using Neodesk 3, you may also drag
the required .CCD file onto the CIXCOMM.PRG program icon in order to run it
- or even place the .CCD file onto your desktop display, so it is always
ready for use.

If you are using a command-line interpreter, you can give the name of the
required .CCD file as a parameter when you run CixComm. For example, type a
command line like:

    CIXCOMM.PRG D:\COMMS\CUSTOM.CCD


By using any of the above methods it is possible to create multiple .CCD
files for use on different occasions - for example, one to download Usenet
messages, another to clear your CIX mail inbasket and outbasket, a third to
download mail but not conference messages, etc.


Some notes on CTS/RTS Flow Control
==================================

The whole area of CTS/RTS hardware flow control is a bit of a minefield on
ST computer. There are bugs in most versions of the TOS operating system
which can cause this type of flow control to fail. The only versions of TOS
which are known to work correctly are TOS 1.2, TOS 1.6/1.62 and TOS
2.06/3.06 onwards

One tell-tale sign of these bugs is absurdly fast data rate when a Zmodem
upload commences, followed by lots of error messages. If this happens to
you, the bugs can be corrected by placing an appropriate patch program into
the AUTO folder on your boot disk. These programs can be downloaded from
atari.st/listings or atari.st.olr/programs.

The most universally reliable patch seems to be HS_FIX10.PRG. However, this
does not work on the earliest version of TOS (v1.0), so if you have that,
try using TURBOCTS.PRG or CTSFIX.PRG instead. If you are using TOS 1.4,
please use the TOS14FIX.PRG program. If you are using TOS 2.05, 3.01 or
3.05, please use the SERPTCH2.PRG program.




                                               Andr Willey, 7th August 1992
