Stars of Shareware: Animation & Sound/SOS-ANIM_SOUND.ISO/best_50/ody200.zip/ODYDOC.LZH/ODY200SH.DOC

Text File | 1993-11-29 | 87KB | 1,843 lines

                      ODYSSEY SHAREWARE USA VERSION
                      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
                               Release 2.00
                               ~~~~~~~~~~~~
                             October 27, 1993
                             ~~~~~~~~~~~~~~~~







                       Program and this document are:
              Copyright (C) 1991, Don Milne and Micropack Ltd.
                See README.TXT file for registration details.

    Published and exclusively distributed in the US and North America by:
         TRIUS, Inc., P.O. BOX 249, N. Andover, MA  01845-0249

                 Published and distributed in the UK by:
        Shareware Publishing, 3A Queen St, Seaton, Devon, EX12 2NY






LIMITED LICENSE
~~~~~~~~~~~~~~~
Notice that Odyssey Shareware Version, is Copyright (C) Don Milne and
Micropack Ltd. You do NOT own the software, you have a limited right to
use and evaluate the software for a period of 30 days. Use of Odyssey
for longer than 30 days requires that you register your copy.

You MAY NOT:

   o Make changes to the software or documentation provided.
   o Attempt to disassemble, or otherwise reverse engineer the software.
   o Sell, Rent, Lease etc this software to others.
   o Bundle it with other products which you sell.

You MAY:

   o Evaluate the software for 30 days.
   o Make backup or other copies of the software as required in order
     to fully evaluate it.
   o Give (not sell!) copies to friends, or upload to bulletin boards.


STATEMENT OF WARRANTY
~~~~~~~~~~~~~~~~~~~~~
This software is provided to you as is. Neither TRIUS, Inc. , Shareware
Publishing nor the authors make any warranty that ODYSSEY SHAREWARE
VERSION is suitable for your application. Under no circumstances will
TRIUS, Shareware Publishing or the authors be held responsible for any
loss or damage suffered by any user arising out of the supply, use or
operation of this software, whether or not such such loss or damage be
direct, consequential or otherwise.

This software is protected by United Kingdom Copyright Law and by
international treaty provision. You may use the software only under the
terms described in the license statement.



NOTE: FOR SPACE REASONS, THIS MANUAL IS DRASTICALLY ABBREVIATED,
COMPARED TO THE PRINTED VERSION. ON REGISTRATION YOU WILL OF COURSE
RECEIVE A FULL, PROFESSIONALLY TYPESET AND BOUND, 400+ PAGE MANUAL.

=============================================================================
=============================================================================

INTRODUCTION TO ODYSSEY (SHAREWARE VERSION)
-------------------------------------------

Odyssey is supplied as two files (or as one ZIP containing these two
files) :-

            ODYxxxx.LZH
            INSTALL.EXE

The first file is a compressed archive containing all the Odyssey
programs, data files and example scripts (the xxxx marks where a version
number will appear). The second file is the Odyssey installation
program.

You will use INSTALL to unpack all the Odyssey files into an Odyssey
directory on your hard disk or second floppy. However, whatever target
you unpack Odyssey files onto, it must have at around 700K bytes
available disk space, which means that you cannot unpack the Odyssey
files onto a 360K disk. You can unpack the files onto a 3.5 inch floppy,
or a high density (AT format) 5.25 inch floppy, both of which have
adequate capacities. If you have problems installing Odyssey then you
should contact TRIUS, Inc, or Shareware Publishing for support. A hard
disk is strongly recommended for practical use of Odyssey.

To install Odyssey you should follow these instructions:-

    1. Insert the Odyssey master disk in your floppy drive, either
       drive A or drive B, then close the drive door.

       If you downloaded the software from a BBS and have it on your
       hard disk then ignore this instruction, however if the files
       came in archived form (.ZIP etc), then you do need to unpack
       the archive using the correct unpacking tool.

    2. If the files are on a floppy then log to that drive by typing the
       drive letter, a colon, and then press the <enter> key. For example,
       if you put the Odyssey disk in drive A, then you should type:-

            A: <enter>

       If you have done this correctly then the DOS prompt should change to
       "A>" (or possibly "A:\>" on some systems).

       If you have the install files on your hard disk then change to the
       directory containing those files, e.g.:-

            cd \comms\download


    3. Run the Install program, by typing "INSTALL" (without the quotes),
       then press the <enter> key.

    4. When INSTALL runs, it asks you which directory it should use ie.,
       where it should install the Odyssey files. If yours is a typical
       system then the default of "C:\ODYSSEY" offered is probably
       acceptable. You can however enter any directory name you wish,
       provided that you enter it in the above format, remembering to
       include both drive letter and directory path. If you wish to install
       the files in the root directory of a disk (e.g. on drive B) then you
       should enter "B:\". The target directory need not be the directory
       containing the install files.

   5. INSTALL will then proceed to unpack all of the Odyssey files, copying
      them into the directory you named. If the named directory did not
      already exist then INSTALL creates it. INSTALL will keep you informed
      of its progress as it unpacks the files.

   6. Finally, all the Odyssey files will be unpacked, and INSTALL will
      proceed to ask you some basic questions about your hardware, which
      you should answer. When this is done INSTALL will create an Odyssey
      configuration file for you, and you are then ready to go. The
      questions you are asked are discussed in the following section.

Now that Odyssey has been installed, you should store your Odyssey disk
in a safe place. This will be a backup in case your files are
accidentally deleted.

When Odyssey is properly installed you should examine the directory and
find a file called READ.ME. This file will contain any information on
changes to the software since the manual was printed.


INSTALL QUESTIONS AND ANSWERS
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Before answering any of the INSTALL questions, you should first make
sure that your modem is attached to your PC, and is powered up. If you
have an internal card modem then your modem is already connected and
powered. Doing this allows INSTALL to check for itself which port your
modem is connected to. However, this check may not work properly if you
have an improper cable with an external modem (see below). If you do not
intend to use Odyssey with a modem then you can ignore this instruction.

    Possible modem detected on COM2
    Use which Comm Port? (1,2): 2

This is the first question asked by INSTALL. You will be shown a list of
numbers in brackets, each number indicating the presence of a comm port.
If INSTALL thinks it has detected a modem on one of these ports then it
will offer that port number as the default choice. You can press <enter>
to accept the default, or you should type one of the valid comm port
numbers shown - no other number will be accepted. In the example prompt
shown above, two comm ports have been recognised, and a possible modem
has been detected on COM2. Odyssey itself can be configured to use comm
ports which have non-standard locations in memory, so you can always
change the selected port once you get through the basic installation
procedure.

If you have a modem attached and powered, but INSTALL does not display a
default port number, then it is likely that DSR is not being held high,
either because the cable is incorrect, or because the modem is
configured wrongly (in the case of the DSR signal, this is not fatal,
but may indicate other configuration problems with your modem), or it
may also mean that your comm port is non-standard in some way, possibly
by being at a non standard address in memory.

    Select your modem :

Odyssey displays this prompt immediately before displaying a menu of
modem which Odyssey has preset configurations for. You can scan up and
down the list of modems with the arrow keys, and if you see your modem
you simply highlight it and press the <Enter> key. If your modem is not
in the list then the best choice is "Hayes Generic".

| NOTE: Odyssey keeps modem configuration details in an editable ASCII text
| file called ODYSSEY.MDM - the pick list mentioned above is extracted from
| this file. If your modem was not present, and you are not a comms novice,
| then you might like to examine this file, and perhaps even create a new
| entry suitable for your own modem. If so, we would be grateful if you let
| us have the details, so that other users may benefit from your effort.
| Run the supplied MODEMCFG program to select a new modem outside the
| INSTALL program, or use the "eXchange modem" option in Odyssey's
| Setup/Modem menu.

    Use Tone or Pulse dialing? [T/P] :

Enter T or P in answer to this question, depending on whether your
exchange allows tone dialing or not. If you do not know then P (for
Pulse dialing) usually works on public exchanges, even when they also
support tones. If your phone is a push button type, and you can hear
tones as you dial, and you get connections very quickly, then you almost
certainly have tone dialing. If you get no tones as you dial, and the
phone whirs and clicks for several seconds after you finish, then you
probably still have pulse dialing. In the latter case, you should
perhaps consider asking your local telephone company whether tone
dialing is available, since the much faster dial and connect sequence is
more pleasant to use.

    Should Odyssey use color? [Y/N] :

You will not see this question if you have a mono display adapter in
your PC. Odyssey can detect for itself whether your display adapter is
mono or color, however it cannot tell if you actually have a color
monitor. Your answer to this question will settle the issue. Enter Y if
you can use color, or N if not.

Now that these questions have been answered, Odyssey installation is
complete, and you may now run the program by typing "ODY" at the DOS
prompt.


RUNNING ODYSSEY FOR THE FIRST TIME
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
THE OPENING DISPLAY
~~~~~~~~~~~~~~~~~~~
You run Odyssey by typing "ODY" at the DOS prompt. You could also supply
a script name on the command line, and Odyssey would execute that script
once it starts up, however when running Odyssey for the first time you
are unlikely to have a script you wish to run.

When Odyssey runs, it briefly displays a logo on the screen while it
initialises the serial port, after which the screen clears and you are
ready to go! In the shareware version there is an additional screen
describing the license terms and telling you how to register. You must
press a key in order to clear this screen. When you have done so the
logo will disappear, leaving you looking at the main terminal screen,
which is mostly blank, except for the top and bottom lines of the
display.

The top line of the display is the menu line, showing the main menu
options. This menu can be disabled in the setup section if you wish, and
this is sometimes necessary when the remote host with which you
communicate expects a 24 line terminal. To begin with however you will
probably want to keep this line present as an aide-memoire.

Also present on the menu line is a clock showing the time of day. This
clock uses DOS to get the time, so if DOS shows an incorrect time then
so will Odyssey.

The bottom line of the display is the status line, and this shows some
basic information about the current state of software and hardware, as
described in the following paragraphs.

The leftmost field shows the Odyssey version number, but when a script
is running, the script name is shown here instead.

To the right of the version number is a field which should currently be
blank, but which will contain the symbol "DCD" when you establish a
connection to a remote machine (DCD = Data Carrier Detected). If your
status line already shows DCD, and you are not currently connected to a
remote host, then either your cable or modem configuration is incorrect.
Some modems come configured by default with their DCD signal held
permanently high, which supposedly makes life easier for poor comms
software, but in reality causes as many problems as it solves,
especially for Odyssey, which needs the DCD signal to tell it when to
start software MNP, when a call has arrived during host mode, and
several other things. You should correct this problem as soon as
possible if you have it.

If you do have the DCD problem, then you are also likely to have a
related problem, which is that many such modems also come configured to
ignore the DTR signal from the PC (DTR = Data Terminal Ready). The RS232
standard requires that if the terminal or PC drops DTR for half a
second, then the modem should treat this is an instruction to hang up
the line. If your modem is configured to ignore DTR then you will not be
able to hang up the line from the PC keyboard (using ALT-H).

Both of the above problems are solved by changing your modem
configuration, either through switch settings, or using a modem command.
You should consult your modem manual for these commands. The exact
wording will naturally depend on the modem, but for the DCD problem you
should look for a command which instructs the modem that "DCD follows
true state of carrier", and for the DTR problem you should look for the
command which tells the modem that it should "interpret DTR according to
CCITT/RS232/EIA standards".

To the right of the DCD field is another field which should currently be
blank, but if you suffer the DCD fault then it may temporarily contain
"MNP5", because this is the field used to inform you when Odyssey is
maintaining an error corrected link (MNP = Microcom Network Protocol).
The digit at the end of this field tells you which class of MNP has been
established, and will always be either 2, 4 or 5 in the current version
of Odyssey.

To the right of the MNP field is the baud rate field, and displays the
current terminal speed and parity setting. For example "2400N" means
2400 bits per second, no parity. "1200E" would mean 1200 bits per
second, even parity.

To the right of the baud rate field is the "Log" field. Odyssey has the
ability to capture (log) any text which it receives to a text file,
stored on disk. When you run Odyssey for the first time this field will
contain "Log: No File", meaning that no log file is currently active.
When you open a log file (ALT-L) then the name you gave to the log file
will be shown here.

The next field shows the terminal emulation currently selected. Odyssey
defaults to a terminal type "TTY", which basically means a dumb ASCII
terminal. Other possible emulations include ANSI or VT100, but whichever
terminal is currently selected, its name is shown here. Terminal
emulations can be selected from the keyboard (via a menu), or by a
script, or can be attached to a dialing directory entry.

To the right of the terminal emulation field is the line quality field,
active only when you are on-line, and then only when software MNP is
being used. Since you are off-line at the moment this field should be
blank. When it is active the field will contain the symbol "LQ:xxx"
where xxx is a number which expresses the line quality as a percentage.
By "line quality" we mean how "noisy" the line is. In other comms
packages noisy lines manifest themselves as spurious characters on the
terminal screen, however this does not happen in Odyssey when MNP is
being used, so the line quality percentage is a valuable guide to the
actual conditions. A line quality of 100% means a perfectly clean line,
while a low percentage means a poor connection, which may show itself as
poor throughput and a jerky display. If your line quality drops much
below 90% then you would probably be best advised to drop the connection
and redial, hoping for better luck next time.

The last field on the line is an on-line clock (blank when you first run
Odyssey). When you make a connection to a remote machine this clock will
reset itself to zero, and thereafter will show elapsed hours, minutes
and seconds since the connection was established.


ONLINE HELP
~~~~~~~~~~~
If you press the F1 key now, you will be presented with a window
containing help information about the keys you can press from the
terminal screen. Generally speaking, you can press F1 anywhere within
Odyssey, and you will be presented with help information which is
specific to the Odyssey section which you happen to be using at that
moment - this feature is often called "Context Sensitive Help". These
help windows are available in addition to single line help, which
appears on the bottom line of the display when you invoke most Odyssey
features. Single line help normally contains only the briefest of guides
to the keys which can be pressed at that point in the program. For an
explanation of those key presses you would consult the F1 help.

When you press F1 and a help window pops up, you then have the option of
pressing the F1 key again, which will display an index of help topics.
This index allows you to navigate your way through the help system,
which is a useful way of exploring many Odyssey features, as an
alternative to using the manual.


THE ESCAPE KEY
~~~~~~~~~~~~~~
To leave the help system you simply press the <Esc> key. Generally
speaking, the <Esc> key is always used in Odyssey to abandon the current
activity, whether you are in a menu, an editor, the dialing directory,
or in fact anywhere else.

The <Esc> key is also sometimes used as a "cancel" key, depending on the
context. For example, if you are editing a string at the time the <Esc>
key is pressed, then Odyssey treats this as an instruction to cancel the
edit, and restores the original contents of the string. The <Esc> key
also cancels currently executing scripts, file transfers, and dial
attempts. If more than one of these activities is in progress when the
you press <Esc>, then only the most recently begun activity is
cancelled.


THE MENUS
~~~~~~~~~
Odyssey has pulldown menus which you can access by typing the ALT key in
combination with the first letter of the menu name. For example to pull
down the "Setup" menu you hold down the ALT key and press 'S'.

Once a menu is displayed you can then use the left and right arrow keys
to move from menu to menu.

To select one of the options from a menu you simply move the highlight
bar to the option you want using the up and down arrow keys, and then
press <Enter>. If you do not understand the purpose of a menu option
then simply move the highlight bar to that option and press F1 for an
explanation.

An alternative way of selecting a menu option is to type the first
letter of that menu option, if it is highlighted. If you do this then it
is not necessary to press the <Enter> key. This method is not available
in all menus, since it was not always possible for us to invent a
sensible name which resulted in a unique first letter for each option.
In those menus there are no highlighted first characters.


QUICK KEYS ("Hot" keys)
~~~~~~~~~~~~~~~~~~~~~~~
Beside some menu options are symbols such as "ALT-x", where x is a
letter. This tells you that ALT-x is an alternative keyboard command
which, if pressed, produces the same result as selecting that menu
option. For example, if you display the File menu you will notice that
beside the "S -Dos Shell" option is the symbol "ALT-O". So, in this
example, ALT-O would drop you into the DOS shell (if you don't know what
that is, then don't worry, these topics are discussed later in this
manual when we come to describing the menus in detail). Remember that
ALT-O means that you hold down the ALT key while you press the 'O' key
(incidentally, if you just tried it, you type EXIT and <Enter> to get
back to Odyssey).

Most spare ALT-letter combinations have been assigned to major Odyssey
features, as alternatives to using the menus. These are often called
"hot" keys, and they allow fluent users to dispense with the menus for
most Odyssey tasks, except configuration (Setup). Generally speaking we
have tried to use the "obvious" ALT key for each function (for example,
ALT-E to edit), but naturally one or two of these mnemonics are somewhat
contrived, due to the shortage of available letters.

If you press F1 at the main terminal screen you will see a help window
which describes all of the available hot keys, and what they do.


THE FILE PICKER
~~~~~~~~~~~~~~~
If you press ALT-E now, you will enter the Odyssey message editor (this
is a Wordstar/Sidekick style editor which is fully described in a later
chapter). Once the edit window has popped up, press the F3 key - this is
the command to select a new file for editing. Instead of typing a
filename just type "*.*" and press <Enter>. Of course, you don't type
the quotes.

What you see is the file picker window. Generally, throughout Odyssey,
if you are asked to enter a filename you also have the option of
entering a wildcard file name, and the file picker will pop up showing
you a list of files in the current directory which match the wildcard
(if you don't know about wildcards then you should consult your DOS
manual).

Once the File Picker window is displayed, you can move from filename to
filename using the arrow keys, or you can press <Enter> to select a
file, or press <Esc> to leave the file picker without selecting a file.
In the latter case you will be back at the filename prompt again.


ODYSSEY CONFIGURATION
~~~~~~~~~~~~~~~~~~~~~
This section of the manual provides a brief guide to configuring Odyssey
for the first time, so that it works correctly with your equipment. It
is not a complete description of the Odyssey setup options, which are
covered in a later chapter (shareware users can consult the F1 help).

For most users, no Odyssey configuration will be necessary, the most
important items having been set up during installation. This will be
true if you have what we have regarded as typical equipment, i.e. a PC
with a hard disk, one or two comm ports, and a 2400 bps Hayes compatible
modem, either internal or external, and without any hardware MNP. This
chapter tells you what you should do if your equipment differs from this
standard in some way. You should avoid making changes to the default
setup until you are absolutely sure that you need to, and that you know
what all the settings do.

If you type ALT-S from the main terminal screen you will enter the
Odyssey "Setup" menu. From there it is possible to access sub menus
which control how Odyssey handles the serial port, display, file
transfer, and so forth.


IF YOU HAVE A NON-STANDARD SERIAL PORT
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you want to use Odyssey with a multi-port serial I/O card, and the
port you want to use is not mapped as COM1 or COM2, then you need to
enter the setup/comms submenu, by selecting "Comms Setup" from the Setup
menu. From there you select "Advanced Setup", and you will then be
presented with a table of base addresses and interrupt levels for the
eight comm ports which Odyssey can use (unused comm ports are set to
zero). From there you can move from field to field using the arrow keys,
and when you reach a field you want to change you simply overtype its
contents. The left column of numbers are the base addresses for each of
the serial chips, and the right column are the interrupt levels
(normally 4 or 3). The following table shows the default Odyssey
settings:-

          Port      Base Address      Int. Level

           1          03F8                4
           2          02F8                3
           3          03E8                4
           4          02E8                3
           5          0000                0
           6          0000                0
           7          0000                0
           8          0000                0


The first two rows define the two standard comms ports recognised by the
industry for IBM PC compatibles. The third and fourth rows define the
addresses most often used for two extra serial ports, however it cannot
be claimed that this "standard" is widely recognised. You will need to
check the manual for yourmulti-port board to determine the correct
addresses for the serial ports.

Notice that you have the complete freedom to change these fields as much
as you like. You could for example swap the first and second rows, and
Odyssey would then treat COM1 as COM2 and vice versa (not recommended).
This merely highlights the fact that as far as Odyssey is concerned, the
port numbers mean precisely what you say they mean, and nothing more.

Hit <Esc> twice when you have finished with this table, and you will be
back at the Setup menu. Type 'S' to save your changes to disk.


CHANGING THE DEFAULT FLOW CONTROL METHOD
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You may want to enable hardware flow control. There are several possible
reasons why this might be needed, for example:-

   o If you have a speed buffered V23 modem (Odyssey cannot  use  a  V23
     modem unless it is speed buffered).

   o If you have a multispeed modem, also with speed buffering, and  you
     wish to use all modem supported connect speeds without varying  the
     actual data rate between the modem and the PC.

   o If you have  a  modem  with  internal  error  correction  and  data
     compression, such as an MNP5, MNP7 or V.42bis modem.

In each of the cases mentioned above, flow control is required because
you will sometimes be sending characters to your modem faster than it
can transmit them, so the modem needs some way of telling you to stop
sending.

To change the flow control setting, select "Comms Setup" from the setup
menu, then type 'F'. The flow control option will change from "NONE" to
"XON/XOFF". Type 'F' again and the option will change to "RTS/CTS". This
is the hardware flow control setting.

Type <Esc> to leave the setup/comms submenu and 'S' to save your changes.

**NOTE**: You may also need to configure your modem for RTS/CTS flow
control, although most modems come configured that way by default. You
should check your modem manual if you are not sure. If you find that
after configuring Odyssey for RTS/CTS flow control you can no longer
communicate with your modem then it is likely that it is not configured
for hardware flow control. This means that you will have to set
Odyssey's flow control option back to "NONE" while you reconfigure your
modem, then perform the above steps again.


MODEM CONTROL
~~~~~~~~~~~~~
For most users, this part of the configuration process is only necessary
if your modem is not Hayes compatible. Some users however may want to
check the "Init string" and "Dialler init string" options. Most users
should not have to change any of these settings.

If your modem is not controlled by "AT" commands, then it is not Hayes
compatible. This is unfortunate, since it means that you need to make
quite complicated changes to Odyssey's modem control strings, which of
necessity requires that you have a good grasp of the requirements of
your modem. A careful read of your modem manual is called for.

Odyssey mainly uses its knowledge of modem control when dialing. It
needs to know how to get the modem ready to dial, how to send a dial
command, and how to recognise whether the dial command succeeded or
failed (i.e. whether or not a connection was established).

To change Odyssey's modem control strings you need to select "Modem
Control" from the setup menu. From top to bottom, the options in this
submenu are as follows (only those required to get you started are
described):-

   Dial Prefix.
       This is the string which Odyssey sends to the modem when it wants to
       dial a number. The prefix would normally be followed by the number
       to dial, and a possible suffix. On Hayes modems this prefix is
       "ATDT" or "ATDP" depending on whether you have tone or pulse
       dialing. You need to find the equivalent string in your modem manual.

   Dial Suffix.
       This is the string Odyssey uses to complete a modem dial command. On
       Hayes modems this is simply a carriage return, symbolised by the
       character '|' in Odyssey.

   Connect String.
       This is the string which the modem sends back to the terminal when
       it has successfully established a connection to a remote computer.
       On Hayes modems the connect string is a simple "CONNECT" (in actual
       fact, Hayes compatible modems faster than 300 bps send back "CONNECT
       xxxx", where xxxx is the connect speed, however you should NOT
       specify this as the connect string in Odyssey, otherwise Odyssey
       would not recognise other forms of the string, e.g. if you specified
       "CONNECT 2400", then Odyssey would never be able to establish a 1200
       bps link). Again, you need to find an equivalent connect string in
       your modem manual.

   Failure Strings.
       Odyssey allows up to six of these, and they contain the messages the
       modem sends when a dial attempt fails, perhaps because the number
       was engaged, or because it was a wrong number.

   Hangup Command.
       This is the command Odyssey uses to hang up the line if some part of
       the dial attempt was not successful (the MNP negotiation for
       example). If you leave this string blank then Odyssey will hang up
       by dropping DTR for half a second, which should work with most
       modems, whether Hayes compatible or not (if this does NOT work then
       you will have trouble with some Odyssey features, such as the ALT-H
       command).

   Init String.
       This is the only modem control string that is used outside the
       Odyssey dialler. If your modem needs to be reconfigured on startup
       for various options, or it does not reliably save its own
       configuration in non-volatile RAM between sessions, then you need to
       enter the initialisation string here. Odyssey sends this string to
       the modem every time it starts up.

   Dialler Init String.
       Odyssey sends this string to the modem before every dial attempt. If
       your modem needs some command prior to dialing (perhaps to reset the
       modem back to a default speed), then you put that string here. If
       your modem does not require such a command, then you MUST still
       enter something here. The actual command does not matter, provided
       that it produces some response from the modem. Anything harmless
       will do. Odyssey does not care what the response is, it simply uses
       this as a test that a modem is actually connected and ready before
       it wastes time trying to dial.

   Connect Timeout.
       When Odyssey issues a dial command to the modem, it starts a timer,
       and waits for a reply. If the timer expires without a reply having
       been received then Odyssey assumes that the dial command has failed,
       and sends a string to the modem to cancel the attempt (the hangup
       command). The connect timeout is the time in seconds that Odyssey
       allows for the response. The default is 45 seconds, which is enough
       for most circumstances, but longer may be necessary if you are
       making an international call, or you may want to make it shorter if
       you have tone dialing, and find that Odyssey is waiting an
       excessively long time to report failure when the dial attempt has
       been unsuccessful.

   Number of Redials
       The number of times Odyssey should attempt to dial any number.

   Pause between Dials
       When redialing, or stepping through a dial queue, Odyssey will wait
       this number of seconds between dial attempts.


DISPLAY SETUP
~~~~~~~~~~~~~
The only change that a new user might want to make to the display setup
is the "Snow Check" option. If you find that you get interference on the
display when Odyssey displays a window, then you might want to set this
option to "ON". Enabling snow checking will stop the interference, but
has a bad effect on the speed with which Odyssey can update the display.
You should therefore not enable this option unless it is really
required.


GENERAL SETUP
~~~~~~~~~~~~~
You may want to change the "Directory for downloads" option to a
directory of your choice. Note that if you name a directory using this
menu option that the directory MUST exist already. Odyssey will not
create it for you.


EDITOR SETUP
~~~~~~~~~~~~
You may want to reduce the editor buffer sizes using this sub-menu, if
you find that you are very short of memory (this often happens to users
who are especially fond of large TSR utilities).


SAVING YOUR CHANGES
~~~~~~~~~~~~~~~~~~~
The above paragraphs described all of the configuration changes which
might be necessary to get a new user off the ground, and ready to dial a
number. Most users will not have had to change anything. If you did,
then now is the time to save those changes. To do this simply pop up the
Setup menu and type 'S'.


MODEM CONFIGURATION
~~~~~~~~~~~~~~~~~~~
Your modem configuration may need to be changed before it can be used
successfully by Odyssey. This section lists some points to look out for.

    DCD Signals.
        Your modem must not be configured such that it holds the DCD signal
        permanently high. You can check this by running Odyssey and looking
        at the status line. If the status line shows the symbol "DCD", even
        when you are not connected to a remote computer, then your modem
        has DCD tied high, and this will need to be fixed by sending the
        appropriate command to your modem, or making a change to the modem
        switches (if your modem has switches). The modem manual will have
        details. If you cannot fix this problem then you will not be able
        to use Odyssey's software MNP, or host mode.

    DTR Signal.
        Your modem must not be configured to ignore the DTR signal from the
        PC. If you find that the ALT-H command in Odyssey does not drop the
        line, then your modem is probably configured to ignore DTR. Check
        your modem manual for the command or switch setting to fix this
        problem.

    Flow Control (Handshaking).
        Some modems have a software flow control option. If your modem is
        configured for XON/XOFF or ENQ/ACK flow control then you should
        disable this option, and set it to use hardware
        <$IRTS/CTS>(RTS/CTS) flow control instead. If you do not do this
        then Odyssey will be unable to transmit the characters used for
        flow control to a remote computer. This could prevent software MNP
        or file transfer from working correctly.


HARDWARE (MODEM) VS SOFTWARE (ODYSSEY) ERROR CORRECTION
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If your modem supports MNP or some other error correction protocol then
you will need to decide whether you wish to use Odyssey's MNP, or the
modem's own error correction. Generally, if the modem supports a lower
MNP class than Odyssey (i.e. lower than class 5), then you will want to
disable the modem's own error correction. This is needed because
Odyssey's MNP cannot work if the modem is intercepting the MNP protocol
information before Odyssey can see it.

If your modem supports MNP5 or better, then you will want to use the
modem's own MNP instead of Odyssey's, since the modem can use the MNP
synchronous mode option which is beyond the capability of the IBM PC
serial chip, and will therefore provide better performance. In this case
you should make sure that Odyssey is not configured for software MNP in
the Setup/Comms menu, or in any of the dialing directory entries.

**NOTE**: If your modem has hardware MNP5 (or better) then you should
remember to at least double the speed at which Odyssey communicates with
the modem. For example, if your modem is a V22bis (2400 bps) modem with
MNP5 then you should set the Odyssey baud rate to 4800 or 9600 bps,
otherwise the PC-modem link would be a bottleneck, nullifying the
performance improvements of the MNP data compression. You should NOT do
this if you are using Odyssey's software MNP.


COMMAND ECHO, AND OTHER MODEM SETTINGS
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The modem should be configured so that it echoes commands from the
terminal, and so that it produces verbal result codes. For a Hayes
compatible, the appropriate command is "AT E1 V1" <Enter>.

If your modem saves its settings in RAM between sessions, you may have
to enter a command to make any changes permanent. On some Hayes
compatible modems the correct command is "AT &W" <Enter>.

If your modem does not save settings in non-volatile RAM, and the
settings you need are not the default settings, then you may need to
place the above commands in the Modem Init String, which you can define
using the Setup/Modem submenu. For the above example, the correct Init
String would be "ATE1V1~|"


THE CABLE
~~~~~~~~~
This section naturally applies only to those users who need a cable,
i.e. those using external modems.

The correct pinout of cables to be used with external modems, or with
direct PC-to-PC connections is described in Appendix A. You should be
extremely wary of using cables which have previously been used for some
other task, perhaps for connecting your PC to a printer. These cables
typically have all sorts of wiring patches made to them to stop the PC
falling over because one or other pin was not held high. Modem
communications requires many more signals from the RS232 interface than
does a serial printer, so you should make sure that the cable you use
correctly makes these signals available to the PC. You are advised to
get a cable made up according to the appropriate diagram in Appendix A.

For those with PC/XT or PS/2 type serial ports (i.e. with standard 25
pin connectors) this is extremely easy, since the cable you require is
simply a flat ribbon cable with a snap on connector at each end. These
cables are cheap and easy to make up in a matter of minutes, your dealer
may be able to help you find someone who can make one.


CHECKING OUT THE INSTALLATION
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Once you have completed installation and configuration, it is time to
check that basic communication with the modem is working properly. To do
this you send a simple command to the modem. If your modem is a Hayes
compatible, then the following is an adequate test.

Make sure that your keyboard has CAPS LOCK set. Then type "AT" and press
<Enter> (do not type the quotes). The modem should respond with "OK". If
you do not get this response then check:-

      o That the modem is connected and powered.
      o That Odyssey is configured for the correct port number and
        baud rate.

If you do get the "OK" response, then your system is ready for use.


MAKING A FIRST CALL
~~~~~~~~~~~~~~~~~~~
The first thing you need to do to make a call using Odyssey is decide
which service you want to dial. You need to know what telephone number
to use, what baud rate and parity setting the system expects, and
whether it supports error correction. This information is often
published along with the telephone number in popular computing
magazines. If there is no mention of MNP or V42 in the published data
then the service may not support error correction.

Once you have the information you need, press ALT-N to display the
Odyssey dialing directory. Press ALT-I to create a blank line at the
first entry. Now press the "F2" key to edit the new entry.

Now, from top to bottom, fill in all the fields in the dialling
directory entry. The first entry is the key, which you may leave blank -
press <Enter> to step to the next field. The second field is the service
name, and can contain anything you like - type something and press
<Enter> to complete the change. The next field is the telephone number,
which you should enter in format similar to those you see in other
entries. The next field is the baud rate - you change this by pressing
the space bar, which causes a menu of available baud rates to appear -
simply highlight which baud rate you need and press <Enter>. Next is the
parity setting - cycle through the allowed settings with the space bar,
until you get to the setting you want. Next is the required terminal
emulation - hit <Enter> to skip this if TTY is acceptable, otherwise
press the space bar for a menu of available terminals. Press <Enter> to
skip the "Log File", "Script Name" and "Keyboard file" fields. Next is
the Error Correction field; if the system you will call supports error
correction then press the space bar to enable it. Don't bother with the
remaining fields; just press <Esc> now to tell the dialling directory
editor that you are finished. You will be asked "Save changes? (Y/N): ",
to which you should answer yes (press 'Y'). The box containing the entry
details will disappear, and you will see that the dialling directory has
been updated with the details of your new entry.

Don't worry if you make a typing error while you are changing a field.
You can always go back to a previous field using the arrow keys.

Now that you have created your new dialling directory entry, just press
the <Enter> key. Odyssey will dial the number you just entered, and
provided a modem answers, you will soon after be online for the first
time. Follow the instructions given by the system when you wish to
disconnect.

===========================================================================

NETWORK SUPPORT
~~~~~~~~~~~~~~~~

Odyssey version 2.00 adds a major feature, Network support.  This means
that one may add a modem to a node on a network and make it accessible
by any node using Odyssey.  (Note that this does not mean Odyssey V2.00
is a network version, it is still a single user program.  A site license
is required to have more that a single user use Odyssey on a Network!).

Four driver selections are now available under the "Connection Type", in
the Odyssey Setup menu:

- The Odyssey Native Driver
  The native Serial driver that has been part of all Odyssey versions

- The INT14 Driver
  Provides very basic Network Support.  It replaces the BIOS Int14.
  Note that BIOS INT14 provides only four basic functions, initialize
  port, get port status, read from the port and write to the port.
  Furthermore, BIOS Int14 services are polled, not interrupt driven.

- FOSSIL Driver
  This is sort of an extended Int14 driver, which was adopted by BBSes a
  few years ago (Fido Opus Seadog Standard Interface Layer).  Note that
  Odyssey provides support for the FOSSIL driver but you need to get the
  actual driver from a different source.

- NASI Driver (Network Asynchronous Services Interface)
  A Novell supported programming interface for accessing serial ports
  across a network.


===========================================================================

INTRODUCTION TO THE SCRIPT LANGUAGE
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you like messing about with script languages in comms packages then
you are in luck! Odyssey has one of the most powerful programming
languages you will see in any product not aimed exclusively at
programmers.


WHAT IS THE SCRIPT LANGUAGE FOR?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
As a PC user, you are probably familiar with the concept of "batch"
files. These are text files, all with a .BAT extension so that DOS will
recognise them, and all containing a simple sort of program which the
DOS command interpreter can understand. DOS batch files consist mainly
of ordinary DOS commands, although batch files can also use programming
features such as IF, GOTO and REM statements. The purpose of the batch
file is to make it easier for you to perform any repetitive task.
Instead of entering individual commands to change directories, load a
mouse driver, run a word processor, and change back to the root
directory when you exit, you can replace all of the above with a single
command which executes a batch file containing those instructions.

A comms package needs a script language for similar reasons. Many of the
things you do inside a comms package are repetitive tasks which you
perform (at least) daily. For example, you may log on to your friendly
local BBS to check if any electronic mail has arrived. If any has, then
you might want to open a log file, capture the new messages, log off,
and read the messages offline. If you use the same service often enough,
then it will almost certainly be worthwhile for you to prepare a script
to automate the procedure.

Using a script has at least these four advantages:-

    o Your hands are free for other work while the comms package
      gets on with its daily chore.
    o Once a script is prepared it can be used by anyone, including
      those who have no knowledge of how to perform the task manually.
    o Time wasting typing mistakes are eliminated.
    o The script responds to prompts and types messages much faster
      than a human possibly could. So online time is minimised, saving
      money.

However, there is one fly in the ointment, which is that a script can be
badly affected by line noise. For example, if a script is waiting for a
particular prompt, and that prompt is corrupted by spurious characters,
then depending on how carefully the script was written it could end up
waiting all day for a prompt that has already passed by.

This is where error correction comes into its own. Whether you use MNP
(or other error control standard) provided in your modem, or Odyssey's
software MNP, the important feature in common is that it is no longer
possible for a prompt to be corrupted by line noise, and so a breakdown
such as the one described above can never occur. Of course, this
requires that the host BBS supports MNP, but these days that is more and
more likely to be the case. MNP cannot prevent a carrier loss, another
potential cause of script failure, however that eventuality is usually
much easier to cope with than the problem of noise. Error correction has
turned a script language from an arguable white elephant into an
essential feature of modern communications packages.

So, you are now sold on the merits of a script language, however the
nature of the script language which should be provided in a comms
package is a matter for debate. Should we, the implementor of the
package, go for power or simplicity in the script language? On the one
hand a limited script language is usually easier for a beginner to
learn, on the other hand our beginner will not be that forever, and
sooner or later will smack into the brick wall, which is a limited
script language.

In Odyssey, we decided to go for power, but in such a way that beginners
can largely ignore the wide range of features until the day comes when
they are needed. A learn mode is provided which is capable of creating
scripts automatically, requiring negligible understanding of the
underlying language. From there you can progress to simple, manually
created scripts using a basic set of four script commands, and finally,
when you are feeling confident, you have the option to learn the
complete script language.

For programmers: Odyssey script closely resembles a conventional
programming language, especially structured languages like Pascal,
Modula-2 or C. If you have a familiarity with any of these, or with any
other common language then you should find that you are able to quickly
progress to the expert level.


A NOTE ABOUT SCRIPT EXECUTION
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In some packages, running a script takes over the comms package
completely, blocking out everything the user does at the keyboard,
except for the "cancel script" key, which is usually an <Esc>. In
Odyssey, the script executes in "parallel" with the user, and so you are
free to type Odyssey commands while a script is running, and to "help a
script along" if a mistake in the script or a burst of line noise causes
it to get stuck at a prompt. However, this is not true "background"
operation, since entering any major Odyssey subsystem (e.g. the menus,
or the editor), will cause the script to pause until you return to
terminal mode.


USING LEARN MODE TO CREATE SCRIPTS
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Learn mode provides the easiest way for a beginner to create an Odyssey
script. Typically this facility will be used to create logon scripts for
a variety of host BBS services. All you need to know when creating such
a script using learn mode is how to log on to that service manually. You
teach Odyssey how to do it once, and thereafter Odyssey will be able to
do the job for you.

The first step in using Learn mode to create a logon script is to create
a dialing directory entry for the new service - see the chapter on
"Using Odyssey" for a description of how to add entries to the dialing
directory.

When you create the dialing directory entry, you must put something in
the "key" column. This key can be anything you like, up to seven
characters long, but it should be unique to that entry (i.e. until you
are more experienced, you should make sure that the new key is not the
same as that of any other entry). The purpose of the key is twofold:
first it allows a script created by learn mode to identify the correct
directory entry to use, secondly it allows a script to be attached to
that entry so that the script is automatically started when you select
the entry for dialing. A script is "attached" to a dialing directory
entry when the script has the same name as the directory entry key.

For the sake of the following example, let us suppose that you want to
create a script for dialing a BBS host called "MICROP". First, you
create the dialing directory entry, making sure that you have the right
settings for baud rate, parity, MNP and so forth. In the key field of
the new line enter the word "MICROP" (without the quote marks). Having
completed the directory entry, including the key, you then press <Esc>
to return to the Odyssey terminal screen. Remember not to press <Esc>
before you have completed all the fields in an entry, otherwise the
<Esc> key will be interpreted as an instruction to abandon the changes
you have made. The entry has been completed when the coloured bar
returns to highlighting the entire line.

From the terminal mode, press ALT-G to display the General menu, then
type 'L' to select the "Learn a Script" option. Odyssey will ask you for
a name to give to the learned script, in this example you should give
the name "MICROP" (without the quotes). The name given must match the
directory entry key you entered earlier, so if you used a different key
name, you should also use that alternative at the script name prompt.
When you have typed in the script name you should press <Enter> to start
learn mode.

Learn mode is now active. From now on, everything you do will be noted
by Odyssey, and duplicated in the new script, so you should avoid doing
anything which is unrelated to the task of logging on to the service.

Press ALT-N to bring up the dialing directory again, moving the
highlight bar to the entry you created earlier (this should still be
highlighted if you exactly followed the instructions given above), then
press <Enter> to dial the number, and wait until you get a connection.

On most host systems, the next thing you will see is the BBS logo,
followed by a prompt for your user name (the name the BBS knows you by).
You should enter that now. The BBS will then prompt you for a password,
and again you should respond. You are now logged on to the BBS.

Odyssey now knows everything it needs to know in order to log on to that
service, so assuming that is as far as you want to take it, you should
now leave Learn mode by pressing <Esc>. Odyssey will convert what it has
learned into a script file and write it to disk. If you have been
following this example then the file created will be called "MICROP.SCR"
(all Odyssey scripts have the .SCR extension, in the same way that DOS
batch files always have a .BAT extension).

Learn mode is now terminated. Odyssey is no longer remembering what you
do. You can if you wish stay on the BBS to continue this session, or you
may log off in order to test the newly created script.

The next time you want to call that service simply run Odyssey, press
ALT-N to call up the dialing directory, select the correct entry using
the highlight bar, and press <Enter> to dial. Odyssey will automatically
run the learned script, which will not only dial the number for you, but
also enter your user name and password details, just as you did the
first time, leaving you logged on to the BBS and ready to read messages
or transfer files.

There are other ways of running scripts in Odyssey, a subject which is
discussed later in this chapter (see the section "How to Run a Script").

WARNING: If, during the learn procedure, something goes wrong with the
login process, for example if you get an engaged tone, then you should
abort learn mode by pressing the <Esc> key, then later you should start
again from scratch. Whatever you do, you should NOT attempt to redial
the number without first stopping and restarting learn mode - if you
ignore this warning you will have dialled the number twice, and so will
the Odyssey script when you run it!


LIMITATIONS OF LEARN MODE
~~~~~~~~~~~~~~~~~~~~~~~~~
For most systems, Odyssey learn mode will do a perfectly good job of
automatically creating a login script for you. However, some systems may
cause it problems if the timing of responses is very critical.

Strict timing problems occur when there is a minimum delay which must
occur between a prompt and a corresponding reply. Odyssey is not able to
differentiate between the delay of a slow typist, and a delay introduced
deliberately by the typist because he or she knows that the system will
not react correctly if the response comes too quickly. The British
Telecom PSS service is an example of a system in which you must wait a
second or two after a connection is established before you can start the
<CR>A2<CR> login process. If the delay inserted by Odyssey is too short
then you may have to increase it, by editing the script. For that you
can use the built in Odyssey editor, or else use any preferred external
editor, provided that it is capable of producing a clean ASCII text
file. Look for the "Delay(xx)" commands inserted by learn mode, and
increase the number shown between the brackets (which is a delay in
seconds). Remember to save your changes - if you use the Odyssey editor
then the save key is F2.


CREATING YOUR FIRST SCRIPT BY HAND
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
For the slightly more adventurous, this section describes how to create
scripts manually, using a minimal understanding of the script language,
but providing a little more flexibility than is possible with learn
mode. Reading this chapter will also allow you to better understand
scripts created by learn mode, should you need to modify one.

A script is created with a text editor; probably the most convenient
editor would be the one built into Odyssey (accessed with ALT-E),
however you are free to use any external text editor provided that it
produces clean ASCII text files. Use of the Odyssey editor is not
described here; if you are not familiar with it then you should perhaps
read the chapter on the editor first, before delving into the script
language. A script file must have an extension of .SCR before it will be
recognised by Odyssey, and furthermore it must have the same name as a
dialing directory entry key if the script is to be invoked automatically
when that directory entry is selected. You are not required to attach
scripts in this way, since scripts can also be invoked from the Call
menu, or from the DOS command line when running Odyssey. Remember to put
the script file in the "Odyssey Files" directory, so that Odyssey can
find it. This directory is named in the Setup/General menu, or if not
named then the current DOS working directory is assumed.

The Odyssey script language currently provides more than 100 built in
commands, yet it is quite possible to write useful Odyssey scripts using
only four of them. However, first you must learn rule number one, which
is that all Odyssey scripts start from the following minimum outline:-

      SCRIPT myscript;
      BEGIN

      END;

This "skeleton" is what Odyssey expects from any script, and its purpose
is to allow Odyssey to easily confirm that this file it is trying to use
is indeed a script, and helps it to more easily find where a sequence of
commands begin and end. The "myscript" name need not be literally as
shown, in fact it can be almost anything you like (its purpose is to
give the script a meaningful name which will be understood by a person
reading a printed listing). However, you should perhaps leave it as
shown until you become familiar with the rules surrounding the naming of
things in the Odyssey script language. Note the semicolons after the
"myscript" and after the "END" are required. The words "SCRIPT", "BEGIN"
and "END" are shown in upper case for clarity only. You can enter them
in lower case if you prefer.

Once you have created the basic script skeleton as shown above, you may
then enter commands between the BEGIN and END lines. The basic four
commands you may use are DIAL, WAITFOR, TRANSMIT and DELAY. These
commands are described below.

DIAL()

The Dial command is used to dial a number, taking the necessary details
from a dialing directory entry. In order to use the dial command you
must pass it the name of a directory entry key, and that key must match
an existing directory entry, otherwise the dial command will not be able
to proceed. Here is an example of the dial command:-

        Dial("MICROP");

Note that the key name is surrounded both by double quotes and round
brackets, and that the command is followed by a semicolon. This may seem
like excessive punctuation, but once you get around to learning the
complete language you will find out why they are required. For the
moment simply follow the rules.

In the above example, the script would look up a dialing directory entry
with a key of "MICROP", and would dial that number. The script will
resume from the statement following the Dial command once a connection
has been established.


WAITFOR()

WaitFor is a basic command which you will use a lot, however expert you
become. This command tells the script to wait until a particular
sequence of characters (called a "string") arrives from the host. Here
is an example of the waitfor command:-

        WaitFor("User name?");

Note again the use of double quotes, round brackets and the terminating
semicolon. In this example the script will wait until the string "User
name?" arrives from the host.

You can also, optionally, add a timeout to the WaitFor command. This
would mean that instead of the WaitFor command waiting forever for the
string to arrive, it can terminate either when the string arrives, or
when the timeout period has elapsed. This is an example of the WaitFor
command making use of a timeout:-

        WaitFor("User name?",10);

In the above example the WaitFor will terminate when the string "User
name?" arrives from the modem, or when a ten second period has passed.


TRANSMIT()

The Transmit() command tells the script to transmit a string via the
serial port. Here is an example of the transmit command:-

        Transmit("John Smith|");

In this example the script would transmit the characters inside the
double quotes to the modem, and hence to the host BBS. Note the '|'
character which forms part of this string. This is treated as a special
character by the transmit command, in that it is not transmitted
literally, but instead tells the transmit command to send the code for
newline (usually the carriage return character). This is required
because if you were typing this manually, in most cases the host would
require you to press <Enter> to complete the answer to the prompt.


DELAY()

This is the last of the four basic commands. The purpose of this command
is to insert a delay into the script, usually to avoid sending messages
to the host BBS before it is ready to receive them. This command is
given a number which is the delay you require, in seconds. Here is an
example of the delay command:-

        Delay(2);

In the above example, the script would pause for two seconds, and would
then continue with the next command.


PUTTING IT ALL TOGETHER
~~~~~~~~~~~~~~~~~~~~~~~
Now that you know what the basic commands are, we can proceed to put
them together in the form of a script to log on to an imaginary BBS.

In the following example the script will dial a BBS which has an entry
in your dialing directory with a key of "MICROP". The script will then
wait for the username prompt from the BBS and enter a name of John
Smith, then it will wait for the password prompt, and answer it with
"smithy". In both cases it will follow the characters in the reply with
a carriage return code.

        SCRIPT myscript;
        BEGIN
             Dial("MICROP");
             WaitFor("User name? ");
             Transmit("John Smith|");
             WaitFor("Password? ");
             Transmit("smithy|");
        END;

Note the indentation of the lines containing the commands. This is not a
requirement of the script language, but in many people's opinion it does
make the script look nicer, as well as making it a little easier to
follow. This is a good habit to get into early, since readability
becomes very important once you begin to write larger scripts using the
advanced script features.

These four basic commands should enable you to write a login script for
any service. However, such a script does not deal with errors which
might occur (such as an engaged tone). If that happens then you should
press the <Esc> key to abort the script. The next section contains
information on how to have the script recognise errors itself, however
you needn't read that now unless you are feeling confident!


DEALING WITH ERRORS
~~~~~~~~~~~~~~~~~~~
Although the example script shown above will work perfectly in most
cases, it does have a problem, in that it makes no attempt at all to
cater for those occasions when things do NOT work perfectly. For
example, suppose the number dialled is engaged - the script shown does
not check whether the dial attempt succeeded, so succeed or fail, the
script will go on to execute the next statement. The next statement is a
WaitFor, and that is never going to succeed if the dial attempt failed,
because Odyssey is at that time not even connected to the host. We
therefore need to put some error protection into the script, which we
can do using an IF statement.

An IF statement can be used to test whether a command succeeded. You
cannot test the success of all commands, because not all of them can
fail. However, among the commands you can test are DIAL and WAITFOR.

Here is the example script again, but this time we test the success of
the DIAL command using an IF statement. If the dial command is not
successful then the script stops:-

        SCRIPT myscript;
        BEGIN
             Write("Calling the MICROP BBS Service.|");
             IF Dial("MICROP") THEN
                 WaitFor("User name? ");
                 Transmit("John Smith|");
                 WaitFor("Password? ");
                 Transmit("smithy|");
             END;
        END;

Note the extra END which has appeared. The IF statement always has an
END associated with it in the same way that a BEGIN always has an END,
and it serves the same purpose, i.e. to "bracket" a sequence of
commands. In the above example the sequence of commands between the "IF"
line and the first "END" will only be executed if the dial attempt
succeeds. You could if you wished put other commands before the "IF"
line, or following the first "END" line, and these would not be
dependent on the "IF" test. In other words those commands would be
executed whether or not the dial attempt succeeds. This is how you
control the execution of commands in the Odyssey script language. The
"Write" command is an example of such a command which will always be
executed when you run this script (the Write command has not been
previously discussed, it simply displays a message on the screen, but
does not transmit that message to the modem).

Finally, we would like to cope with the situation that occurs when you
get a connection with a modem, but the remote computer does not respond.
To handle this, you can again use an IF statement, this time using it to
test the success of a WaitFor command. Since we now want the WaitFor to
give up after a certain period, we will specify a timeout this time -
ten seconds in the following example:-

        SCRIPT myscript;
        BEGIN
             Write("Calling the MICROP BBS Service.|");
             IF Dial("MICROP") THEN
                 IF WaitFor("User name? ",10) THEN
                     Transmit("John Smith|");
                     WaitFor("Password? ");
                     Transmit("smithy|");
                 END;
             END;
        END;



SEMICOLONS
~~~~~~~~~~
We should perhaps return to the question of the placement of semicolons.
In the first script example there was a semicolon following the first
use of WaitFor, yet there was no semicolon after the first WaitFor in
the most recent example shown. Also, there is no semicolon on either of
the two "IF" lines. If you study the above script you may be able to
spot the common factor for yourself, which is that a semicolon tells the
script processor where a complete statement ends. Let us take the last
script from top to bottom - "SCRIPT myscript" is a complete statement,
so it is followed by a semicolon. "BEGIN" is not a complete statement,
since it must have a matching end, so it is NOT followed by a semicolon.
The "Write" line is a complete statement, so there is a semicolon. The
first "IF" line is NOT a complete statement, since like the "BEGIN", it
must have a matching "END" -and so on down the list. In the case of the
first "WaitFor", it is not a complete statement, since it forms part of
an "IF condition THEN" sequence, whereas an unconditional "WaitFor" is a
complete statement, and so is followed by a semicolon.

The semicolon in the Odyssey script language serves more or less the
same purpose as the full stop which terminates a written sentence in the
English language. The only real difference is that the script language
grammar allows any "sentence" to be constructed from any number of
smaller sub-sentences, each of which is also terminated with a
semicolon.

Take all the time you need to understand this section of the manual. If
all was not clear the first time you read it then you are encouraged to
read it again. When you have read and understood the above discussion
you will know everything you need to know in order to manually create
your own login scripts for any BBS, and have them cope with almost any
eventuality.


HOW TO RUN A SCRIPT
~~~~~~~~~~~~~~~~~~~
From the Call menu
~~~~~~~~~~~~~~~~~~
You can run a script from the Call menu. Press ALT-C from Odyssey
terminal mode and the Call menu will be displayed. This menu contains
the names of each of the scripts which Odyssey finds in its "Odyssey
files" directory (named in Setup/General), or if not named, in the
current DOS working directory. If there are more scripts available than
can be displayed in a single menu (eight), then other script names can
be seen by paging up and down the list using the PgUp and PgDn keys. To
execute any script from the Call menu simply type the number shown
alongside the menu option.

From the Files menu
~~~~~~~~~~~~~~~~~~~
A script can also be executed from the Files menu. Press ALT-F from
Odyssey terminal mode to display the menu, then select the "Execute
Script" option. This menu option allows you to access scripts which are
not stored in the "Odyssey files" directory, you must therefore supply a
complete path, for example "c:\otherdir\myscript".

From the Dialling Directory
~~~~~~~~~~~~~~~~~~~~~~~~~~~
When you press <Enter> on a dialing directory entry in order to dial a
BBS, Odyssey will check for an "attached" script, and will load and run
one automatically, if it finds that an attached script exists. Odyssey
considers a script to be attached to a dialing directory entry when the
name of the script matches the key field of that dialing directory
entry. For example, if the key for the chosen entry is "MICROP", and a
script file exists called "MICROP.SCR", then Odyssey will load and run
"MICROP.SCR" instead of dialing the number. What happens from that
moment is entirely up to the script, but in most cases it will at some
point make a call to the script "DIAL" command, thus allowing the
dialing procedure to continue.

From another Script
~~~~~~~~~~~~~~~~~~~
A script has the facility to chain to any other script. It does this by
making use of the script "CHAIN" command. The script which used the
chain command is halted, and the chained script (if found) is executed.
Odyssey has no facility to "call" another script, i.e. with control
returning to the original script, however one possible approach if you
need to do that would be to explicitly chain back to the parent script
from the child.

From the DOS Command Line or Batch File
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can execute Odyssey scripts directly from the DOS command line, or
from a DOS batch file, by supplying the name of the script as a command
line argument to Odyssey. For example the DOS command:-

         C:\ODYSSEY> ody microp

would tell Odyssey to execute the script "MICROP.SCR" immediately after
loading. Odyssey does not display its normal welcome banner when a
script is named on the command line.


Stopping a Script
~~~~~~~~~~~~~~~~~
Pressing the <Esc> key while a script is running will cancel the script,
unless the script has used a special CanEscape(FALSE) command to disable
this feature. If you want to type and transmit an ESC character while a
script is running, without aborting the script, then a keyboard command
has been provided for that purpose - try ALT-F2.


SCRIPT COMMANDS
~~~~~~~~~~~~~~~
The above should be enough to get you started with simple scripts. The
manual for the full Odyssey package does of course cover the script
language syntax in much greater detail, as well as providing full
descriptions of each of the built in commands, with an example for each
one. This summarised guide however will simply list the commands which
are available:-

MODEM AND SERIAL I/O COMMANDS
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
PROC AutoAnswer(On:Flag);
PROC Break(tenths:Number);
PROC HangUp();
PROC ModemInit();
FUNC MNPAnswer():Flag;
FUNC MNPClass():Number;
FUNC MNPConnect():Flag;
FUNC OnLine():Flag;
PROC Paste(s:String);
PROC PortInit(Baud,Databits,Parity,Stopbits:Number);
PROC Receive(VAR s:String; timeout:Number [; NoEcho]);
PROC SetPort(PortNo:Number);
PROC Sleep();
PROC Transmit(s:String);

DISPLAY AND KEYBOARD COMMANDS
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
PROC Alarm(Seconds:Number);
PROC BackGnd(Colour:Number);
PROC ClrEol();
PROC ClrEos();
PROC ClrLine();
PROC ClrScr();
FUNC ColourDisplay():Flag;
PROC DelLine();
PROC DisableCursor();
PROC EnableCursor();
PROC ForeGnd(Colour:Number);
PROC GotoXY(x,y:Number);
PROC InsLine();
FUNC KeyPressed():Flag;
PROC KillWindow();
FUNC LoadKeyDef(kdf_name:String):Flag;
FUNC Menu(x,y,width:Number; Title:String;<N> {option:String;}
          Menu_Flags:Number):Number;
FUNC RdKey():Number;
PROC Read(VAR s:String [; NoEcho]);
PROC SetHelp(help_msg:String);
PROC UseWindow(win_handle:Number);
FUNC WhereX():Number;
FUNC WhereY():Number;
FUNC Window(x,y,width,height:Number; title:String;
            colour:Number):Number;
PROC Write(item {,item} : String_or_Number);


FILE AND DIRECTORY COMMANDS
~~~~~~~~~~~~~~~~~~~~~~~~~~~
PROC Chain(script_name:String);
FUNC ChDir(dir_name:String):Flag;
FUNC CopyFile(source_file,dest_file:String):Flag;
FUNC CurrentDir():String;
FUNC DiskSpace():Number;
FUNC Dos(cmd:String; WAIT or NOWAIT [+NOCLEAR] ):Number;
FUNC Download(protocol [,filename:String [,default-action] ] ):Flag;
PROC Edit(filename:String);
FUNC FAppend(VAR f:File; filename:String):Number;
FUNC FClose(VAR f:File):Number;
FUNC FCreate(VAR f:File; filename:String):Number;
FUNC FDelete(filename:String):Number;
FUNC FEOF(f:File):Flag;
FUNC FetchStr(Key:String; VAR s1,s2:String; [ filename:String ] ):Flag;
FUNC FFirst(wildcard:String; s_attr:Number;
            VAR Filename:String; VAR f_attr:Number):Flag;
FUNC FNext(VAR Filename:String;  VAR f_attr:Number):Flag;
FUNC FOpen(VAR f:File; filename:String):Number;
FUNC FQualify(filename:String):String;
FUNC FRead(f:File; VAR s:String):Number;
FUNC FRename(oldname,newname:String):Flag;
FUNC FWrite(f:File; s1 {,sn} :String_or_Number):Number;
FUNC IsFile(filespec:String):Flag;
FUNC LastTransferredFile():String;
FUNC MkDir(dir_name:string):Flag;
FUNC PickFile(wildcard:string; VAR filename:String):Flag;
PROC Shell();
FUNC Upload(protocol; filespec:String):Flag;

DIALLING COMMANDS
~~~~~~~~~~~~~~~~~
FUNC Dial(key:String):Flag;
FUNC DialQueued():Number;
FUNC DialTagged():Number;
FUNC TagDirEntries(Key:String; ClearOldTags:Flag):Number;

MODE CONTROL COMMANDS
~~~~~~~~~~~~~~~~~~~~~
PROC CanEscape(enable:Flag);
FUNC CRinTranslation(CR or CRLF):Number;
FUNC CrOutTranslation(CR or CRLF):Number;
FUNC Emulate(emulation:String):Flag;
FUNC EventLogging(enable:Flag):Flag;
FUNC LocalEcho(enable:Flag):Flag;
FUNC LogFile(Log_command; [ filename:string] ):Flag;
PROC PrinterOff();
PROC PrinterOn();
PROC RestoreDefaults();
PROC SetASCII(CharDelay,LineDelay:Number; BlankExpansion:Flag);
PROC SetAutoWrap(on:Flag);
PROC SetBackspace(Key:Number; Destructive:Flag);
PROC SetCISB(AutoInvoke,IntResponse,SAok,EscapeCtl:Flag);
PROC SetDialDelay(Secs:Number);
FUNC SetDiallingDir(Filename:String):Flag;
PROC SetDialPrefix(PrefixS:String);
PROC SetDialTimeout(Secs:Number);
PROC SetDownloadDir(dirname:String);
PROC SetRawLogging(on:Flag);
PROC SetMaxRedials(max:Number);
PROC SetScreenMode(MenuLine,StatusLine,BigScreen:Flag);
PROC SetSoundEffects(Windows,Bells,FTransfer:Flag);
PROC SetStripParity(on:Flag);
PROC SetZmodem(AutoDownload,FullStreaming,EscCtrls:Flag);

HOST MODE COMMANDS
~~~~~~~~~~~~~~~~~~
PROC HostShell();
PROC GetHostInfo(VAR NormPass,PrivPass,Welcome,HostDir:String;
                 VAR MNPwanted:Flag);
PROC FileSize(f:File; VAR Bytes,Xblocks:String);
FUNC WaitForCall():Number;

WATCH AND WAIT COMMANDS
~~~~~~~~~~~~~~~~~~~~~~~
PROC ClrAllWatches();
PROC ClrWatch(handle:Number);
FUNC GrabWhen(Target:String; VAR line:String):Number;
FUNC ReadScreen(x,y,len:Number):String;
FUNC Received(handle:Number):Flag;
FUNC WaitFor(target:String [; t_secs:Number ] ):Flag;
FUNC WaitForSilence(secs,max_wait_secs:Number):Flag;
PROC WatchAgain(handle:Number);
FUNC WatchEvent(handle1, {,handleN} : Number;
                [ timeout:Number ] ):Number;
FUNC WatchFor(target:String):Number;
FUNC When(s1:String; s2:String):Number;


DLL COMMANDS
~~~~~~~~~~~~
FUNC LoadDLL(DLLname:String):Number;
FUNC SendMessage(dll_handle:Number;
                 Command:String;
                 VAR str_arg:String;
                 num_arg:Number):Number;
FUNC UnloadDLL(dll_handle:Number):Number;

MISCELLANEOUS COMMANDS
~~~~~~~~~~~~~~~~~~~~~~
FUNC ASC(s:String; i:Number):Number;
FUNC CHR(n:Number):String;
FUNC Date():String;
PROC DEC(VAR n:Number [; amount:Number ] );
PROC Delay(secs:Number);
FUNC DTESpeed():Number;
PROC Exit();
FUNC GetCallInfo(VAR ServiceName:String;
                 VAR Connect_Speed:Number;
                 VAR Key:String):Flag;
PROC GetEnv(varname:String; VAR value:String):Flag;
PROC Halt();
PROC HaltE(return_code:Number);
PROC INC(VAR n:Number [; amount:Number ] );
PROC IntToStr(n:Number; VAR s:String);
FUNC IsDirKey(Key:String):Flag;
FUNC Length(s:String):Number;
PROC LogEvent(s:String);
FUNC OdyVersion():String;
FUNC Pos(substring,s:String):Number;
PROC Priority(enable:Flag);
PROC SetTimer(seconds:Number);
PROC SilentMode(enable:Flag);
FUNC StrEdit(VAR s:String [, NoEcho]):Flag;
PROC StrToInt(s:String; VAR n:Number);
FUNC SubStr(s:String; start,length:Number):String;
FUNC Time():String;
FUNC TimerExpired():Flag;
FUNC ToLower(s:String):String;
FUNC ToUpper(s:String):String;

-----------------------------------------------------------------------------

Registration Information
~~~~~~~~~~~~~~~~~~~~~~~~

Author/Publisher Information:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Odyssey is written and copyrighted (1991) by Don Milne, Micropack Ltd.

In the US and North America, it is exclusivelly distributed by:

               TRIUS, Inc.
               P.O. Box 249
               N. Andover, MA  01845-0249

               ORDERS ONLY:  1-800-GO-TRIUS
               Information:  508-794-9377
                       FAX:  [phone]
                       BBS:  508-794-0762
                       CIS:  71333,103


In the UK, it is Published and distributed by:

               Shareware Publishing
               3A Queen St,
               Seaton,
               Devon, EX12 2NY

               0297-24088 (voice)

Note that all Odyssey documentation uses British spelling throughout.


Usage Restrictions:
~~~~~~~~~~~~~~~~~~~
This evaluation copy of Odyssey has not yet been paid for. Users are
granted a licence to use it for evaluation purposes for a period of 30
days. If the software continues to be used it must be paid for.

Please be aware that old copies of Odyssey may be kept on bulletin board
services and disk vendor libraries for years. If the date of last update
at the top of this file is more than 12 months old please contact one of
the publishers (above) to ensure that you have the most current version.

Licensee shall not use, copy, rent, lease, sell, modify, decompile,
disassemble, otherwise reverse engineer, or transfer the licensed
program except as provided in this agreement. Any such unauthorized use
shall result in immediate and automatic termination of this license.

U.S. Government Information: Use, duplication, or disclosure by the U.S.
Government of the computer software and documentation in this package
shall be subject to the restricted rights applicable to commercial
computer software as set forth in subdivision (b)(3)(ii) of the Rights
in Technical Data and Computer Software clause at 252.227-7013 (DFARS
52.227-7013). The Contractor/manufacturer is:

    TRIUS, Inc., P.O. Box 249, N. Andover, MA  01845-0249.

Registrants are granted a licence to use Odyssey on a single computer as
they would a book - that is to say that only one person may use the
software at a time - LAN and Site licenses are available if more
extensive use that this is required. The creation of backup copies is
expressly permitted (and even encouraged).



Disclaimer of Warranty:
~~~~~~~~~~~~~~~~~~~~~~~
The Shareware evaluation (trial use) version is provided AS IS. The
publishers MAKE NO WARRANTY OF ANY KIND, EXPRESSED OR IMPLIED, INCLUDING
WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR
A PARTICULAR PURPOSE.

The publishers warrant the physical diskette(s) and physical
documentation provided with registered versions (only) to be free of
defects in materials and workmanship for a period of sixty days from the
date of registration. If the publishers receive notification within the
warranty period of defects in materials or workmanship, and such
notification is determined by the publishers to be correct, the
defective diskette(s) or documentation will be replaced.

The entire and exclusive liability and remedy for breach of this Limited
Warranty shall be limited to replacement of defective diskette(s) or
documentation and shall not include or extend to any claim for or right
to recover any other damages, including but not limited to, loss of
profit, data, or use of the software, or special, incidental, or
consequential damages or other similar claims, even if the publishers
have been specifically advised of the possibility of such damages. In no
event will the publishers' liability for any damages to you or any other
person ever exceed the lower of suggested list price or actual price
paid for the license to use the software, regardless of any form of the
claim.

THE PUBLISHERS SPECIFICALLY DISCLAIMS ALL OTHER WARRANTIES, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO, ANY IMPLIED WARRANTY OF
MERCHANTABILITY AND/OR FITNESS FOR A PARTICULAR PURPOSE.



Registration Information
~~~~~~~~~~~~~~~~~~~~~~~~
Registration of your Odyssey Package gets you (apart from salving your
guilty concience):

- The LATEST version of the software, plus notice of updates.

- A comprehensive, professionally bound and typeset 300+ page manual.

- Notices of updates and reduced-price upgrades.

- Free voice-line technical support for 90 days. (extendable)

- Online support via CIX (UK), Compuserve (UKSHARE and PCVENF), and the
  TRIUS BBS (USA)

- The Odyssey Extension Package containing a script compiler, an editor
  configuration utility, and a dialing directory conversion program to
  make switching from Procomm, QModem, or Telix easier.

- The Ody FAX module (supports EIA Class I/II modems), that enables you to
  send and receive faxes directly from your computer (provided you have a
  Fax/Modem.

- The Ody REMOTE CONTROL module that allows you to operated a remote PC with
  the same ease as if you were there.  Ideal for client support, file
  transfers, (up to 5400cps), etc.


For a limited time ONLY, in North America you can register Odyssey by
sending $89.00 + $6 postage to TRIUS, Inc. using the invoice below.
TRIUS, Inc. also accepts credit card payments (1-800-GO-TRIUS). There is
also a script (Alt-C Register) that will automate registration by BBS.

You might also be able to find Odyssey at your local software dealer. If
they do not have it have them call either of the publishers for
information. Thank you.

Site licences are available for the Odyssey. A site licence entitles you
to use this software on all of the computers in a building, campus, or
plant.  Contact TRIUS, Inc. for details.

Additionally, VAR licences are available for computer retailers and
consultants. This entitles the seller to bundle Odyssey with computers,
modems, or other hardware or software sold at retail. The buyer of the
computers will become registered users of Odyssey at no additional fee
upon returning a postcard-style registration card.



                  Single User Invoice - North America
                  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
                   Introductory Limiter Time Pricing
                   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


Remit to:                        From:

TRIUS, Inc.                         ____________________________________
P.O. Box 249
N. Andover, MA  01845-0249          ____________________________________

or VISA/MC call:                    ____________________________________
   1-800-GO-TRIUS
  * Orders  ONLY *                  ____________________________________


Send me ___  registered copies of Odyssey at $89 + $6 shipping each.
             (Includes diskette, manual, etc.)

Send me ___ copies of the current Odyssey shareware diskette at $5 each.


                                                       Total: __________

I require ____ 5 1/4"   ____ 3 1/2" disks
-------------------------------------------------------------------------
Checks, Money Orders, VISA, MasterCard are accepted.  Written Purchase
Orders are accepted for quantity purchases and site licenses from most
companies, schools, and governmental units.  Terms NET 10.


VISA/MC #  _________  _________  _________  _________  Exp Date:___ /____


Signature ________________________________   Phone ______________________

To Purchasing, Accounts Payable:

Note that Odyssey has been delivered and accepted by the customer. Upon
receipt of this paid invoice, printed manual(s) and current disk(s) will
be sent.
-------------------------------------------------------------------------
   Contact TRIUS, Inc. at  508-794-9377  for site licensing prices!
-------------------------------------------------------------------------