Boston 2/boston-2.iso/DOS/HILFEN/MODEM/ODYSSEY/ODY150SH.LZH/ODY150SH.DOC

Text File | 1992-08-05 | 88KB | 1,872 lines

                      ODYSSEY SHAREWARE USA VERSION
                      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
                               Release 1.50
                               ~~~~~~~~~~~~
                             December 1, 1991
                             ~~~~~~~~~~~~~~~~







                       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 package 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 the publishers nor
the authors make any warranty that ODYSSEY SHAREWARE VERSION is suitable
for any purpose. Under no circumstances will either publisher 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.  You
will of course receive a full, professionally  typeset  and  bound,  300
page manual when you purchase the full Odyssey package.


Introduction to Odyssey Shareware Version
-----------------------------------------

Odyssey is supplied as 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.


INSTALL is the program you will use to  unpack  all  the  Odyssey  files
into an Odyssey directory on your hard disk or second  floppy.  However,
whichever target you unpack Odyssey files onto, it must  have  at  least
500K 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 one of the publishers for support.

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
       i.e., where it should install the Odyssey files. If  yours  is  a
       typical system then the default offered "C:\ODYSSEY" 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 will create  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 determine 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.

    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 numbers will  be  accepted.  In
the example prompt shown above, two comm  ports  have  been  recognised,
and a 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.


         Use what modem speed? [2400] :

The answer to this question  determines  Odyssey's  default  serial  I/O
speed, i.e. the speed Odyssey programs the comm port for  each  time  it
is run. The answer is not important if you intend  to  use  the  Odyssey
dialling facilities to make connections, since  the  dialling  directory
allows you to store an independent speed  for  each  dialling  directory
entry. The default for this question is always 2400 bps, and you  should
either press <enter> to accept this default,  or  type  in  a  different
figure, normally the maximum speed which your modem will accept.

If you do not know what speed to use with your modem then the following
table may help.

            Modem Type         Speed

            CCITT V21           300
            CCITT V22          1200
            CCITT V23          1200          * see note
            CCITT V22bis       2400
            CCITT V32          9600
            Bell 103A           300
            Bell 212A          1200


You can find out which of the above standards your modem conforms to  by
checking your modem's manual.  If  yours  is  one  of  the  increasingly
prevalent multi-standard modems, then choose the  speed  which  conforms
to the fastest standard. If your modem  uses  a  proprietary  signalling
technique (for example,  US  Robotics  Courier  HST  modems),  then  you
should again consult the modem manual for guidance.

**NOTE**: Odyssey only supports V23 modems which are  capable  of  speed
buffering, since the PC does not allow software to set different  speeds
for receive and transmit in any  reliable  way.  Speed  buffering  means
that the modem will receive characters from the  PC  at  1200  bps,  but
will transmit them  at  75  bps,  buffering  any  characters  it  cannot
immediately transmit. Therefore, if  you  have  a  V23  modem  which  is
capable of speed buffering then the correct speed to set is 1200 bps.

If your modem supports hardware data compression, i.e.  either  MNP5  or
V42bis, then you should at least double  the  speed  selected  from  the
above table. For example, if you have a V22bis modem with MNP5 then  you
should select a speed of 4800 bps, otherwise you  will  see  no  benefit
from the data compression. This rule ONLY applies to hardware MNP -  you
do not double the port speed when you intend you use Odyssey's  software
MNP.


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

Enter T or P in answer to  this  question,  depending  on  whether  your
exchange allows tone dialling or not. If you do not  know  then  P  (for
Pulse dialling) 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 dialling. 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 dialling. In  the  latter  case,  you
should perhaps consider asking  your  local  telephone  company  whether
tone dialling is available, since  the  much  faster  dial  and  connect
sequence is much more pleasant for modem communications.

          Should Odyssey use colour? [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 colour, however it cannot tell if you  actually  have  a  colour
monitor. Your answer to this question will settle the issue. Enter Y  if
you can use colour, 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 dialling 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  dialling
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  dialling.  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 dialling. 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  dialling
       (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
       dialling, 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

Of interest in this menu is the "Strip Parity Bit" option. If  you  want
to call a host using a packet switching network service,  you  may  find
that you need to set seven bits and even parity to use the network,  but
that the host itself works best with eight bits no parity. You  can  get
around the need to switch parity settings in  mid-call  by  setting  the
"Strip Parity Bit" option to "YES" (which it is by default).  This  will
ensure that you never see the IBM "semi-graphic"  characters  which  are
caused by an incorrect parity setting, and allows you to  leave  Odyssey
configured for 8 data bits and no parity.

**NOTE**: Loading ANSI terminal emulation resets the "Strip Parity  Bit"
option to "NO".  This  is  because  ANSI  requires  all  eight  bits  to
deliberately display  the  aforementioned  semi-graphic  characters.  If
this happens to you then  you  should  probably  be  using  a  different
emulation, perhaps VT100, or perhaps just stick with "TTY", the  default
emulation.

You may also 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 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  dialling  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 system 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 MNP error  correction.  This  information  is  often
published  along  with  the  telephone  number  in   popular   computing
magazines. If there is no mention of MNP in the published data then  the
system may not support error correction.

Once you have the information you  need,  press  ALT-N  to  display  the
Odyssey dialling directory. Press the "Ins"  or  "Insert"  key  on  your
keyboard to create a blank line at the first entry. Now press  the  "F2"
key to edit that line.

Now from left  to  right,  fill  in  all  the  fields  in  the  dialling
directory entry, pressing <Enter> after changing each field.  The  first
field is the service name,  and  can  contain  anything  you  like.  The
second field is the telephone  number,  which  you  should  enter  in  a
similar format to the other entries. The next field is  the  baud  rate,
followed by the parity setting (this is normally 'N' for no  parity,  or
'E' for even parity). If the system you  will  call  supports  MNP,  but
your modem does not, then put 'Y' in the MNP column, otherwise put  'N'.
Put 'N' in the "log" column. If the service you want  to  call  needs  a
particular terminal type, then put the name  of  the  necessary  Odyssey
terminal emulation in the "Emul" column. Press <Enter> on  each  of  the
remaining fields on the line. When you press <Enter> on the last  field,
Odyssey should return to highlighting the entire  directory  entry,  and
is then ready to dial.

Don't worry if you make a  typing  error  while  you  are  changing  the
fields. You can always go back to a previous field by typing  SHIFT-Tab,
or you could simply re-edit the line when you have  finished  the  other
changes.

Once you have entered all the fields correctly, just press  the  <Enter>
key once more. 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.

The above should be more than enough information  to  get  you  started,
but remember that you can always consult F1  help.  Remember  also  that
when you purchase the full Odyssey you will receive  a  full,  300  page
manual, which includes more detailed information on  every  menu  option
and keyboard command in Odyssey.

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


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 for any electronic mail which  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 this 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 dialling directory entry for the new service - see the  chapter
on "Using Odyssey" for a description  of  how  to  add  entries  to  the
dialling directory.

When you create the dialling 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 dialling. A script is "attached" to a  dialling  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 dialling a BBS  host  called  "MICROP".  First,  you
create the dialling 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  dialling  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 dialling 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  dialling  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 dialling 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  dialling  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 dialling 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 dialling 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  dialling  directory  entry  when
the name of the script matches the key field of that dialling  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 dialling 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
dialling 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);
FUNC Dial(key:String):Flag;
FUNC DTESpeed():Number;
PROC HangUp();
FUNC LocalEcho(enable:Flag):Flag;
FUNC MNPAnswer():Flag;
FUNC MNPConnect():Flag;
FUNC MNPClass():Number;
FUNC OnLine():Flag;
PROC Paste(s:String);
PROC PortInit(Baud,Databits,Parity,Stopbits:Number);
PROC Receive(VAR s:String; timeout:Number [; NoEcho]);
PROC RestoreDefaults();
PROC SetPort(PortNo:Number);
PROC Sleep();
PROC Transmit(s:String);
FUNC WaitForCall():Number;


Odyssey Setup/Mode Commands

PROC SetASCII(CharDelay,LineDelay:Number; BlankExpansion:Flag);
PROC SetCISB(AutoInvoke,IntResponse,SAok,EscapeCtl:Flag);
PROC SetDialPrefix(PrefixS:String);
PROC SetDialTimeout(Secs:Number);
FUNC SetDiallingDir(Filename:String):Flag;
PROC SetScreenMode(MenuLine,StatusLine,BigScreen:Flag);
PROC SetStripParity(on:Flag);
PROC SetBackspace(Key:Number; Destructive:Flag);
PROC SetAutoWrap(on:Flag);
PROC SetRawLogging(on:Flag);
FUNC CRinTranslation(CR or CRLF):Number;
FUNC CRoutTranslation(CR or CRLF):Number;
PROC SetSoundEffects(Windows,Bells,FTransfer:Flag);
PROC SetZmodem(AutoDownload,FullStreaming,EscCtrls:Flag);




Display and Keyboard Commands

PROC Alarm(Seconds:Number);
PROC BackGnd(Colour:Number);
PROC ForeGnd(Colour:Number);
PROC CanEscape(enable:Flag);
PROC ClrEol();
PROC ClrEos();
PROC ClrLine();
PROC ClrScr();
FUNC ColourDisplay():Flag;
PROC DelLine();
PROC InsLine();
PROC DisableCursor();
PROC EnableCursor();
FUNC Emulate(emulation:String):Flag;
PROC GotoXY(x,y:Number);
FUNC KeyPressed():Flag;
FUNC RdKey():Number;
PROC KillWindow();
PROC UseWindow(win_handle:Number);
FUNC Window(x,y,width,height:Number; title:String; colour:Number):Number;
FUNC LoadKeyDef(kdf_name:String):Flag;
FUNC Menu(x,y,width:Number;
          Title:String;
          option1 {,optionN}:String;
          Menu_Flags:Number):Number;
PROC Read(VAR s:String [; NoEcho]);
PROC SetHelp(help_msg:String);
FUNC WhereX():Number;
FUNC WhereY():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(s:String; WAIT or NOWAIT [+NOCLEAR] ):Number;
FUNC Download(protocol [; filename:String] [;default_action] ):Flag;
FUNC Upload(protocol; filespec:String):Flag;
PROC Edit(filename:String);
FUNC FAppend(VAR f:File; filename:String):Number;
FUNC FCreate(VAR f:File; filename:String):Number;
FUNC FOpen(VAR f:File; filename:String):Number;
FUNC FClose(VAR f:File):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 FQualify(filename:String):String;
FUNC FRead(f:File; VAR s:String):Number;
FUNC FWrite(f:File; s1 {,sn} :String_or_Number):Number;
FUNC FRename(oldname,newname:String):Flag;
PROC GetFileSize(f:File; VAR Bytes,Xblocks:String);
FUNC IsFile(filespec:String):Flag;
FUNC LastTransferredFile():String;
FUNC LogFile(OPEN or SUSPEND or RESUME or CLOSE [;file_to_open:string]):Flag;
FUNC MkDir(dir_name:string):Flag;
FUNC PickFile(wildcard:string; VAR filename:String):Flag;
PROC PrinterOff();
PROC PrinterOn();
PROC SetDownloadDir(dirname:String);
PROC Shell();
PROC HostShell();


Watching and Waiting Commands

FUNC WaitFor(target:String [; timeout_secs:Number ] ):Flag;
FUNC WatchFor(target:String):Number;
FUNC Received(handle:Number):Flag;
PROC WatchAgain(handle:Number);
PROC ClrWatch(handle:Number);
PROC ClrAllWatches();
FUNC When(s1:String; s2:String):Number;
FUNC WatchEvent(handle1, {,handleN} : Number; [ timeout:Number ] ):Number;
FUNC GrabWhen(Target:String; VAR line:String):Number;



Miscellaneous Commands

FUNC ASC(s:String; i:Number):Number;
FUNC CHR(n:Number):String;
FUNC ToLower(s:String):String;
FUNC ToUpper(s:String):String;
FUNC Date():String;
FUNC Time():String;
PROC DEC(VAR n:Number [; amount:Number ] );
PROC INC(VAR n:Number [; amount:Number ] );
PROC Delay(secs:Number);
PROC Exit();
PROC GetEnv(varname:String; VAR value:String):Flag;
PROC GetHostInfo(VAR NormPass,PrivPass,Welcome,HostDir:String;
                 VAR MNPwanted:Flag);
PROC Halt();
PROC HaltE(return_code:Number);
PROC IntToStr(n:Number; VAR s:String);
PROC StrToInt(s:String; VAR n:Number);
FUNC IsDirKey(Key:String):Flag;
FUNC Length(s:String):Number;
FUNC OdyVersion():String;
FUNC Pos(substring,s:String):Number;
PROC Priority(enable:Flag);
FUNC StrEdit(VAR s:String [, NoEcho]):Flag;
PROC SetTimer(seconds:Number);
FUNC TimerExpired():Flag;
PROC SilentMode(enable:Flag);
FUNC SubStr(s:String; start,length:Number):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:  72727,616


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, and 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.



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.

In the UK, you can register Odyssey by sending £89.00 + £4 carriage + VAT
(total £109.28) to Shareware Publishing. Shareware Publishing also accept
credit card payments on (0297) 24088.

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 /12" 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!
-------------------------------------------------------------------------