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 key. For example, if you put the Odyssey disk in drive A, then you should type:- A: 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 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 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 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 key. Generally speaking, the 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 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 key is pressed, then Odyssey treats this as an instruction to cancel the edit, and restores the original contents of the string. The 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 , 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 . 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 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 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 . 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 to select a file, or press 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 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 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" . 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" . 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 (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 to step to the next field. The second field is the service name, and can contain anything you like - type something and press 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 . 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 to skip this if TTY is acceptable, otherwise press the space bar for a menu of available terminals. Press 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 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 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 . 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 to return to the Odyssey terminal screen. Remember not to press before you have completed all the fields in an entry, otherwise the 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 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 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 . 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 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 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 A2 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 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 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 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 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; {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: 508-688-6312 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! -------------------------------------------------------------------------