BMODEM for the Atari ST Computers Version 2.3a A Public Domain Communications Program by David Betz Permission is granted for the non-commercial use and distribution of this software and documentation, provided only that credit be duly given. Suggestions for improvement, or reports of problems regarding this software should be made to the author: David Betz 114 Davenport Ave. Manchester, NH 03103 (603) 625-4691 (home) Manual Revision 1.1 - December 2, 1986 Questions or suggestions regarding this manual should be addressed to: Ron Sprunger 74-285 Primrose Palm Desert, CA 92260 Tel (619) 341-0109 -TABLE OF CONTENTS- Manual Conventions.............. 1 Purpose of BMODEM............... 1 Program Setup................... 1 Usage........................... 2 Terminal Mode................... 2 Command Mode.................... 2 Commands........................ 3 TYPE........................ 3 EXPECT...................... 3 SEND........................ 4 RECEIVE..................... 4 CAPTURE..................... 4 CLOSE....................... 4 ASEND....................... 4 XMODEM/YMODEM............... 5 CHECKSUM/CRC................ 5 VERIFY/NOVERIFY............. 5 WATCH/NOWATCH............... 5 FULL-DUPLEX/HALF-DUPLEX..... 5 BAUD-RATE................... 6 DTR/NODTR................... 6 ESCAPE...................... 6 CALL........................ 6 EXIT........................ 7 ABORT....................... 7 HELP........................ 7 PROMPT...................... 7 DELAY....................... 7 MKEY........................ 8 STATUS...................... 8 SYSTEM...................... 9 SET......................... 9 Script Files.................... 10 BMODEM.INI...................... 11 Command Summary................. 12 Macro Binding Summary........... 12 Version History................. 13 Known Bugs/Problems............. 13 Under Consideration............. 13 BMODEM for the Atari ST Page 1 Reference Guide -MANUAL CONVENTIONS- In this manual, the characters "<" and ">" are used to denote specific keys to be pressed. For instance refers to the key marked "Return" on the keyboard. The caret ("^") is used to signify a "control key". This means that a particular key is to be struck while is depressed. In the case of scripts, the caret is also used to signify the character which would be produced by pressing a particular control key. "^M", for instance, is the ASCII carriage return character, which may be produced from the keyboard by striking , or by pressing while holding down . Parentheses ("()") are used to indicate required parameters. Square brackets ("[]") are used to indicate optional parameters. "/" is used to indicate that either of two choices is possible. For instance CRC/CHECKSUM means that either "CRC" or "CHECKSUM" may be given as the command, depending on which is desired. -PURPOSE- BMODEM is a terminal emulator/file-transfer program. It facilitates communications with remote computers by allowing the use of the Atari ST as a terminal via modem or direct hookup, and allows inter-computer transfer of files, using file-transfer protocols commonly available on remote bulletin board services. It was specifically designed to make life easier when using the Byte Information Exchange, or BIX. A "protocol" is simply a way for two computers to transfer files between themselves with verified accuracy of the transfer by some means. BMODEM allows capturing or sending ASCII text files using no protocol, as well as receiving and sending binary files with the popular xmodem and ymodem protocols. An ASCII file is one containing text; that is, readable characters. A binary file is one which might have meaning to a computer, such as a program, but which might contain some characters which people, printers, and terminals can't handle. In addition, BMODEM has the ability to perform sequences of commands automatically, according to information in "script" files, as well as to expand specific function keys to user-selected commands (macros). -SETUP- BMODEM may be installed on any Atari ST computer. If the program is to be invoked from the desktop with specific script files specified, it should be renamed to BMODEM.ttp, or installed on the desktop as a "TOS Takes Parameters" program. Otherwise, it may simply be installed as BMODEM.tos. BMODEM for the Atari ST Page 2 Reference Guide -USAGE- BMODEM is invoked from the desktop by double-clicking on its icon or filename, or from a shell by invoking according to shell conventions. If BMODEM is installed as a Tos-Takes-Parameters program, the user will be prompted for parameters to pass on to the program. The only valid parameter is a filename, which BMODEM will interpret as a script file (q.v.). When first started, BMODEM looks for a file called BMODEM.ini, and uses that as the default script. If BMODEM.ini exists, all commands in that file will be interpreted and executed first, then if a script file was specified in the program invocation, that script will be read and acted on. In the absence of other specifications, BMODEM will default to 1200 baud, half-duplex operation, with default file-transfer protocol of xmodem/crc. When BMODEM starts, a one-line version identification message will be displayed, after which BMODEM will first interpret and implement BMODEM.ini, then whatever script file is pending, then immediately go into terminal mode. BMODEM operates in either terminal or command mode, both of which are explained below. -TERMINAL MODE- When BMODEM is in terminal mode, whatever is typed at the keyboard will be delivered to the serial communications port. Commands may be given to the modem attached to the serial port to initiate a call, or if a connection already exists, what is typed will be sent on to the remote computer. BMODEM commands may not be given in terminal mode, since what is typed at the keyboard is not interpreted by BMODEM. While in terminal mode, you may use BMODEM's "macro" capability to issue commands by pressing certain "function keys". See "MACROS". Pressing <^\> (hold down while pressing <\>) will switch to command mode, signified by the "CMD>" prompt appearing. <^\> is the "escape" key, and may be changed with the "ESCAPE" command. See "COMMANDS". -COMMAND MODE- Except for macros, BMODEM commands must be given from command mode. You are in command mode when you see the "CMD>" prompt. In command mode, you are talking to BMODEM, and may change any of the user-controllable parameters of the program, such as baud rate, communications protocol, or the escape key. You may also begin file transfers, issue system commands, and close files. To exit command mode, just press . BMODEM for the Atari ST Page 3 Reference Guide -COMMANDS- BMODEM commands may be given in upper or lower-case, or any combination of the two. Some commands are self-sufficient; that is, merely typing in the command, followed by , is sufficient to bring about the desired effect. Other commands require additional information, such as a file name to act upon, or a character or string of characters to associate with a key or action. If the command requires additional information, or "parameters", type in the command, followed by a space, followed by the parameter. More than one command may be given on a line, provided that the commands are separated by a space. All BMODEM commands are explained below. The commands are given in upper case, though they may be entered lower case as well. A brief description of each command is given, along with an example of its use. The examples are preceded by "CMD>", indicating that they are to be typed in from command mode. All commands may be used in script files as well. Valid commands for BMODEM, along with their usage, are: TYPE (character-string) Send a character, or string of characters, to the communications port. If the string contains spaces or certain other characters, it MUST be enclosed in quotes, so quoting a string is a good idea. If the string contains control-characters (ASCII values 0 through 31 decimal), they may be signified with the caret ("^") followed by the character having an ASCII value 64 higher than the ASCII value desired. For example, to send "myname" to the port, followed by a carriage return, you would give the command: CMD> type "myname^M" EXPECT (character-string) The program awaits character-string before proceeding with the script. While it waits, BMODEM returns to terminal mode, so that normal communications occur until the expected string is sent by the remote system, at which time the script will be resumed. CMD> expect "login:" BMODEM for the Atari ST Page 4 Reference Guide -COMMANDS (Continued)- SEND (filename) Begin sending the specified file using the current file-transfer protocol. The remote system must be set up to receive a file using the same protocol prior to invoking the "SEND" command. The filename does not need to be quoted. CMD> send test.prg RECEIVE (filename) Begin receiving the specified file using the currently-defined file-transfer protocol. The remote system must be commanded to send a file using the same protocol prior to invoking the "RECEIVE" command. The file is automatically closed when the transfer is complete. CMD> receive test.prg CAPTURE (filename) Begin capturing ASCII text, to be put into the specified file. CMD> capture test.txt CLOSE "Close" requires no parameters, and closes the currently-open ASCII capture file. No on-screen indication is given of its action, and the only indication the user might have of its efficacy is some activity on the disk drive. BMODEM closes an open capture file automatically on EXIT. CMD> close ASEND (filename) Send the specified ASCII text file over the port. The user must prepare the remote system in advance for receiving the text. Usually, this means invoking an editor on the remote system, then giving the asend command. When ASEND opens the file to be transferred, it reports the file name and number of bytes to be sent. As the transfer takes place, a status line continually reports the line being sent and the cumulative bytes transferred. At the end of the transfer, the message [ ASCII send complete ] is displayed. While the transfer is in progress, it may be terminated at any time by pressing the key. CMD> asend test.txt BMODEM for the Atari ST Page 5 Reference Guide -COMMANDS (Continued)- XMODEM/YMODEM These are the two protocols currently supported by BMODEM for the transfer of binary files. Xmodem is the popular Modem7 protocol of Ward Christensen, supported by almost all bulletin boards. It involves the transfer of files in 128-byte chunks, or packets. Ymodem is a similar protocol, but uses 1024-byte packets, and thus works more rapidly, if the remote system supports the protocol. In either case, each packet is checked at both ends, and the verifying information compared. The checking can be done by either CRC or CHECKSUM, which will not be further explained, other than to say that they are two different methods of verifying the content of a packet. CMD> xmodem CHECKSUM/CRC The user may specify one of these two verification methods for use in file transfers. CMD> checksum VERIFY/NOVERIFY Signals whether script commands are to be echoed on the host screen or not. CMD> verify WATCH/NOWATCH Indicates whether BMODEM should show the results of script dialog on the screen or not. CMD> watch FULL-DUPLEX/HALF-DUPLEX In full-duplex, BMODEM expects the remote system to echo back everything the host sends it. In half-duplex, BMODEM does the echoing, saving transmission time. If the remote system assumes full-duplex, and the user selects half-duplex, every character typed at the keyboard will appear twice on the screen; once from BMODEM, and once from the remote system. CMD> full-duplex BMODEM for the Atari ST Page 6 Reference Guide -COMMANDS (Continued)- BAUD-RATE (rate) Most modem communication is done at either 300 or 1200 baud. Baud refers to the speed with which data is transferred. Direct connection of two computers usually allows faster rates, such as 2400, 4800, or even 9600 to be used. The "baud-rate" command sets the Atari's serial port to the specified speed. The remote computer must be communicating at the same speed, and the modem (if any) must also support the speed. CMD> baud-rate 1200 DTR/NODTR When two computers are communicating, it is necessary to have some form of flow control, so that information is not sent over the line faster than the recipient can accept it. This is typically done with a protocol called XON/XOFF, meaning that when the recipient needs to stop the flow, it sends the XOFF character (usually ^S), and when it again is ready to receive, it sends the XON character (usually ^Q). Another method is DTR, meaning Data Terminal Ready. This requires at least one more line in the communications line, usually connected to pin 20 on the serial port. Whether DTR is being used is controlled by this command. CMD> nodtr ESCAPE [modifier-](named key) BMODEM by default recognizes <^\> as the command to transfer from terminal to command mode. The user may change this to any named key with the "ESCAPE" command. After entering "escape ", the user may enter any or all of the modifiers 's', 'c', 'a', specifying that the named key must be entered with , , or depressed, or any combination thereof. For more information on named keys and modifiers, see MKEY and "Command Summary". CMD> escape s-undo CALL (filename) In addition to allowing a script file name as a parameter on invocation, BMODEM will open and use a named script at any time by use of the "call" command. The filename does not need to be quoted. CMD> call myini.fil BMODEM for the Atari ST Page 7 Reference Guide -COMMANDS (Continued)- EXIT Leaves BMODEM and returns to the calling program (usually the desktop or a shell). CMD> exit ABORT Ceases execution of the current script file. This might be necessary if the script gets out of synch, or if there is no answer on the number being called from within a script. CMD> abort HELP [more] The "Help" command produces a screen listing of the valid BMODEM commands. The same listing may be seen by pressing the key from terminal mode. If "help more" is entered, a list of the default function key macros is shown, along with the rules for defining macros. CMD> help more PROMPT [prompt string] (command) Used in scripts to display a message on the screen. The PROMPT command might be used to explain usage prior to issuing a command. The prompt string will be shown on the screen, but NOT sent to the serial port. CMD> prompt "Enter the name of the program to run:^M^J" system DELAY (nn) If a pause in a script is needed, for instance to allow the modem time to dial, or because a telephone dialing sequence requires it, this is the way to introduce the pause. The delay is in tenths of a second. CMD> delay 5 BMODEM for the Atari ST Page 8 Reference Guide -COMMANDS (Continued)- MKEY [modifier-](named key) (macro character string) Associates a character string (which would be a command, or series of commands) with a particular named key. The assignment remains in effect for the duration of the work session, or until changed with another mkey command. The modifiers are 's', 'c', and 'a', for , , and , respectively. If a modifier is specified, it means that the named modifier key must be held down while the named key is pressed. More than one modifier may be specified, separated from one another and from the key name by '-' (dash). A complete list of the function keys available for macro assignment with the mkey command, as well as all the default macro bindings can be obtained by typing "help more" from the CMD> prompt. In addition, the Command Summary page in this manual lists all the named keys. Keys without a specified name may be used as named keys by using their "scan codes", preceded by "$". A key's scan code may be obtained by running the public domain program SHOWCHAR.TOS, which is distributed with BMODEM. CMD> mkey F9 "prompt \"Aborting Script\" abort" CMD> mkey INSERT "help more" CMD> mkey s-c-INSERT "prompt \"Shift-Control-Insert^M^J\"" CMD> mkey c-$1E "prompt \"This is Control-A^M^J\"" Note in three of the examples that the backslash ("\") is used to allow quotes for the prompt command within the quotes for the mkey character string. Each of the internal quotes must be backslashed in order for this to work. Also note that two BMODEM commands are included in the character string now associated with . The second example binds the default macro definition screen to the key. STATUS This command produces a screen display of the current BMODEM settings. It includes protocols, display parameters, and environment variables. CMD> status BMODEM for the Atari ST Page 9 Reference Guide -COMMANDS (Continued)- SYSTEM [progname] [program parameters] External programs can be run on the computer without leaving BMODEM. The SYSTEM command can be invoked without a program name, in which case the prompt "System?" will be displayed, and the user can type in the name of the program to be run, along with any parameters which that program might need. The program name can lack the file suffix (.tos, .ttp, .prg), and BMODEM will look under all three common program suffixes. If only a particular suffix is to be looked for, or a particular search order is desired, the user can specify the suffix in the SUFF variable, explained below under "SET". The directory in which the program resides must be specified, unless it is the current directory, or is specified in the PATH variable. CMD> system a:\bin\me.ttp test.fil CMD> system me test.fil SET [variable name] [character string] BMODEM has three "environment variables" which may be controlled with the SET command. They are: PATH The path to search for external programs (SYSTEM) SUFF The program suffix search order BMODEM The path to search for BMODEM scripts Each variable accepts more than one parameter. If program code is commonly kept in directories other than the work directory, those paths may be set into the PATH variable, obviating the need to specify the path to search when running a program with the SYSTEM command. The SUFF variable must be given complete suffixes, including ".". Use of the BMODEM variable facilitates keeping all script files in one place on the system, even though BMODEM itself might be run from another directory. Note that the BMODEM.INI file must be in the directory from which BMODEM is invoked. Backslash characters within paths must be escaped with a second backslash. CMD> set path "a:\\bin,b:\\" CMD> set suff ".ttp,.tos,.prg" CMD> set bmodem ".,b:\\scripts" BMODEM for the Atari ST Page 10 Reference Guide -SCRIPT FILES- Often, upon entering BMODEM, or during a communications session, it is desirable to execute a sequence of BMODEM commands. The user might want to log onto a bulletin board automatically, or use a special script to handle a file transfer. All this can be done with script files. When executed, BMODEM looks for the script file "BMODEM.INI". By creating a script file with this name, the user can assure that BMODEM will be configured according to his needs. Since BMODEM defaults to 1200 baud, half-duplex, xmodem-crc operation, a user with other requirements might use the BMODEM.ini file to start out at 2400 baud, full-duplex, ymodem protocol, and to define for aborting script files: VERIFY NOWATCH BAUD-RATE 2400 FULL-DUPLEX YMODEM CRC MKEY F9 "ABORT" In order to log onto a bulletin board, a user might need to have a more complex script file, using many of the BMODEM commands. The script file needs to send commands over the modem, as well as respond to the prompts issued by the bulletin board. Here's a sample file, using the Hayes modem commands to log onto a bulletin board, allow the user to work on the board, and hang up the phone and exit BMODEM when the session is done. At one point this script issues the full-duplex command in order to avoid echoing of the password on the screen - in cases where people other than the user have access to the machine, it might not be desirable to put passwords in script files at all. TYPE "ATD 555-9999^M" EXPECT "Login:" TYPE "MyLoginName^M" EXPECT "Password:" FULL-DUPLEX TYPE "MyPassWord^M" HALF-DUPLEX EXPECT "Topic?" TYPE "MyTopic^M" EXPECT "Goodbye" TYPE "ATH^M" EXIT BMODEM for the Atari ST Page 11 Reference Guide -SCRIPT FILES (Continued)- This script is purely hypothetical. By logging onto a bulletin board for which you want to create a script, carefully noting each step in the procedure, including prompts issued by the board and your responses, you can build a list of the actual prompts received and commands issued to get you onto the board. Special commands might be needed at some point to set up the proper communications with the board; for instance, to tell the board that you're using half-duplex, or what baud-rate you're using (some boards determine baud-rate by receiving one or more ^M characters). When communicating with BIX via TYMNET, some commands can be given at the TYMNET login to control full/half-duplex and flow control. In order to set these up properly, a line like this might be needed: EXPECT "Login:" TYPE "^H^X^RMyLogin^M" ^H tells TYMNET to use half-duplex, ^X and ^R tell it you want to be able to control information flow with ^S and ^Q, and, as with other examples, ^M sends the carriage return needed to signal the end of your input. -BMODEM.INI- This special script file must, if present, reside in the directory from which BMODEM is invoked in order to be found. If found, it is read in and acted on first thing when BMODEM is run. This file may be used to define macros, set environment variables and protocols, and in general to configure BMODEM always to start up in the way most convenient for the user. A sample follows: verify baud-rate 1200 half-duplex noverify watch set path "a:\\bin,a:\\" set bmodem ".,b:\\scripts" set suff ".prg,.ttp,.tos" mkey F9 abort mkey INSERT "help more" BMODEM for the Atari ST Page 12 Reference Guide -BMODEM COMMAND SUMMARY- TYPE (character string) -- To Port EXPECT (character string) -- From Port SEND (character string) -- Use current protocol RECEIVE (filename) -- Use current Protocol CAPTURE (ASCII file name) -- Open for Capture CLOSE -- Capture File ASEND (filename) -- Send ASCII XMODEM/YMODEM -- Transfer Protocol CHECKSUM/CRC -- Error Checking VERIFY/NOVERIFY -- Echo Script Cmds WATCH/NOWATCH -- Modem Script Data FULL-DUPLEX/HALF-DUPLEX -- Remote/Local Echo BAUD-RATE (rate) -- Port Speed DTR/NODTR -- Hardware Handshake ESCAPE [a/s/c-](named key) -- Terminal to Command Mode CALL (script filename) -- Start Script EXIT -- Leave BMODEM ABORT -- Terminate Script HELP [more] -- Show Commands [Macros] PROMPT (character string) -- Display on screen MKEY [a/s/c-](key) (macro) -- Bind Macro to Key SYSTEM (program) [params] -- Run External Program (! also) SET (VAR name) (value) -- Set Environmt Variable STATUS -- Show Current Settings DELAY (nn) -- Pause nn tenths of second -MACRO KEY BINDINGS SUMMARY- These are the default macro key bindings for BMODEM: F1 HALF-DUPLEX F2 FULL-DUPLEX F3 SEND F4 RECEIVE F5 ASEND F6 CAPTURE F7 CLOSE F8 SYSTEM F10 EXIT HELP HELP Named keys are: F1 F2 F3 F4 F5 F6 F7 F8 F9 F10 HELP UNDO INSERT CLR-HOME UP DOWN LEFT RIGHT Any Key may be used if the key's scan code is known. Scan codes are specified with $hh, where 'hh' is the hexadecimal code for the key. For example, the numeric keys on the top row of the main keyboard have scan codes of 120-129, when used with , which translates to hexadecimal values $78-$81. A key's scan code may be determined by using SHOWCHAR.TOS, a public domain program distributed with BMODEM. Shift-Alt-0 is named s-a-$81. Note that the top row keys from <1> to <=> are unique in having different scan codes when used with . 'a-' must be used to name these keys with . BMODEM for the Atari ST Page 13 Reference Guide -VERSION HISTORY- VERSION 1.0 Original port of BMODEM from UNIX XMODEM/YMODEM protocols for Atari ST VERSION 2.0 ASEND command added MKEY command and Macro key bindings added HELP MORE for macro key bindings ESCAPE command added PROMPT command added BMODEM.INI initialization SYSTEM command added VERSION 2.1 : 11/16/86 SET command added STATUS command added Environment Variables PATH, SUFF, BMODEM added Report on Progress added to ASEND command VERSION 2.3 : 11/22/86 Pass existing environment to SYSTEM-called programs Ability to bind ESCAPE command to function key Ability to specify Shift/Control/Alt combinations VERSION 2.3a : 12/02/86 8K capture buffer Key binding to scan code fixed DELAY nn (sec/10) implemented -KNOWN BUGS/PROBLEMS- ABORT command does not work SUFF variable requires ".sfx" - will not supply "." -UNDER CONSIDERATION- User-selectable buffer size for capture Command language implementation y this command.