IMPORTANT NOTE: The FidoTerm manual is beautifully typeset using the TeX mathematical typsetting system, and available as a very nice printed 40 page booklet. This file is that manual mechanically stripped of it's format codes, and therefore contains only the text. It is not very nice to look at or print out. It does however contain all of the technical information. If you would like a copy of the printed manual, and the latest copy of the software, mail $12US ($16 outside North America, US FUNDS ONLY!!) to: FidoTerm c/o World Power Systems Box 77731 San Francisco CA 94107 USA Fido and FidoNet are registered trademarks of Tom Jennings World Power Systems San Francisco, California FidoTerm is an easy to use, but powerful and customizable telecommunications program, oriented towards the performance technical user. It contains easy to use commands, a fast and flexible modem programming language, an advanced Zmodem, universal Xmodem, and an intelligent and adaptive text uploader. FidoTerm requires: a computer running PCDOS/MSDOS version 2 or higher; 196K free memory; an ASYNC adapter or internal modem. Second revision: August 1992 First revision: February 1992 Original printing: September 1989 Copyright 1992 by Tom Jennings. All rights reserved. No part of this book may be reproduced in any form without permission, except for ``reasonable use'' and quotations of brief passages by reviewers. World Power Systems P.O. Box 77731 San Francisco CA 94107 USA FidoNet 1:125/111 internet tom.jennings@fidosw.fidonet.org modem (415)-863-2739 9600HST Fido and FidoNet are U.S. registered trademarks of Tom Jennings. -10000 FidoTerm Communications program, February 1992 Contents Running FidoTerm 1 Async Adapters and FOSSIL drivers 2 FidoTerm Commands and Features 2 The status line 3 Function keys 3 How the screen works 4 8pt Command descriptions File -- ESCape FILE 4 File -- ESCape FILE TRANSMIT 5 File -- ESCape FILE RECEIVE 5 Baud -- ESCape BAUD 5 Bit tests -- ESCape TEST DOS -- ESCape DOS 6 Script -- ESCape SCRIPT 6 Controls -- ESCape CONTROLS 7 Parity -- ESCape CONTROLS PARITY 7 Screen -- ESCape CONTROLS SCREEN 8 Echo -- ESCape CONTROLS ECHO 8 8pt The script language Fidoterm's script language 9 Script language machine model 9 Instruction processing 11 Pattern matching 14 Complex pattern matching 16 Further notes on pattern matching 19 8pt Instruction descriptions Register and arithmetic 20 Flow control 21 String comparison 22 User input 23 Character input/output 23 File I/O 24 Special instructions 25 File-transfer control 26 Line control and hardware 27 Script execution control 28 Running FidoTerm From DOS, simply execute FT.EXE: FT When Fido/FidoNet displays its ready-prompt ( Fido active: Waiting for a call or event (?=help) ) simply enter: F In either case, FidoTerm executes the startup script FIDOTERM.SCR (details follow shortly) and leaves you ready to type commands to FidoTerm, or characters to/from the serial port or modem. If run from Fido/FidoNet, the command ESCape Q (quit FidoTerm) command returns you directly to Fido instead of DOS. FidoTerm starts up with simple default values for things, such as 2400 baud, no parity, etc. Some features are not ``turned on'' until you enable them via a script command. You will probably want to create or modify the sample FIDOTERM.SCR startup script file. FIDOTERM.SCR Start up Script File When FidoTerm is first run, it tries to run a script named FIDOTERM.SCR . It first looks in the current, default directory; if not found there, it looks through each directory in your DOS PATH , and executes the first one found. Nothing happens if one is not found. An example FIDOTERM.SCR script is given below, and makes a decent base from which to customize. The script commands are described in a later section (see inside front cover) but if you're in a hurry you can probably guess their meanings: io-port 1 ;use COM1 &b= 9600 ;initially 9600 baud protocol zmodem ;def. file transfer protocol color 7 ;status line color/attribute cursor-height 6 ;big cursor (LCD readability) file-log "filexfer.log" ;FidoTerm logs up/dn loads zmodem-path c:/temp ;ZMODEM recv path (There should be a similar FIDOTERM.SCR file packaged with FidoTerm.) ( HINT : Use a forward slash / instead of a backslash in FidoTerm pathnames; backslash has special meaning within FidoTerm, which is covered within this manual.) (HINT: You can have one, main FIDOTERM.SCR script in a directory defined if your DOS PATH command, setting such basic things as serial port number, etc, and have customized FIDOTERM.SCR files in certain subdirectories to modify FidoTerm's behavior when run from those directories.) Async Adapters and FOSSIL drivers FidoTerm contains it's own driver for use with a standard PC clone Async Adapter. It supports either COM1 or COM2, and any of the baud rates 300 to 38,400. If a FOSSIL driver is installed, FidoTerm will detect it and automatically use the FOSSIL driver instead of the integral drivers. A FOSSIL driver is required to use other than COM1 and COM2. FOSSIL drivers are available for most DOS machines. They are not supplied by me. FidoTerm Commands and Features FidoTerm is always in ``terminal mode''. Characters typed on the typewriter portion of the keyboard are sent directly to the serial port or modem; characters received from the serial port or modem are displayed on the screen immediately. For example, if you have an ``AT command'' type modem, typing ATE1V1 should cause the modem to respond with OK in the usual manner. The ESCape key The ESCape key is FidoTerm's command key . Entering ESCape replaces the status line contents with a prompt for a command. All commands are single letters, as shown in the prompt. Some commands have sub-commands. Details on specific commands is given in the second section following. To send an ESCape character: Entering an ESCape at the command prompt sends an ESCape to the serial port. In other words, from terminal mode, hitting the ESCape key twice sends one escape character to the serial port. Other special keyboard characters are: function keys ( F1 through F12 , PgUp , PgDn , the arrow keys, Home and End ) perform FidoTerm functions. See the Function keys section for details. FidoTerm does not have a large array of commands. What it does have is a flexible and fast script language. The sample autodialer script is written in the script language. This makes FidoTerm extensible and customizable. The status line The very bottom line of the screen is ``owned'' by FidoTerm. It will show one of three things; first, most often, line status as described below; second, command prompts after you enter ESCape; and last, messages and prompts generated by the script language. Use ESC 9600 . Zmodem . N . 23:59:59. 9600 is the currently set baud rate. Set by ESCape BAUD command or script register &B . Zmodem is the default file transfer protocol setting, set by the ESCape FILE PROTOCOL command. Zmodem has the additional desirable side effect of allowing ``auto-receive''; that is, when enabled, when you manually start a file download on the remote BBS, FidoTerm detects the remote computer's file transmission and invokes the correct FidoTerm commands to receive the file for you automatically. You must enable this feature with the zmodem-path script command. The single letter ( N, O, E, Z ) shown is the parity setting; see the ESCape CONTROL PARITY command. The current time of day is displayed in 24 hour format. If you have file capture on (command ESCape FILE CAPTURE ) the name of the capture file will be shown in the blank portion of the status line. There is one additional snippet of information stuck in the very last position: if the serial port's Carrier Detect signal is TRUE, a small centered dot is displayed after the last time of day digit. Function Keys FidoTerm uses extended function keys for two purposes: user scripts and screen viewing. The function keys F1 through F12 execute scripts. Pressing key F1 causes FidoTerm to try to run F1.SCR , following the directory-search process outlined in the Running FidoTerm section. F2 executes F2.SCR , and so on. It is recommended that you put commonly used scripts in one of the subdirectories that appears in your PATH. How the Screen Works The screen in front of you hopefully has 25 lines. FidoTerm takes over the bottom line for commands and status, leaving the other 24 for use as the screen as you'd normally think of it. These lines are what you look at, and are what the ANSI command sequences operate on. New text (generally) is displayed at the bottom, and old text scrolls off the top. FidoTerm keeps an image of the screen, plus the last 350 or so previous lines that have ``scrolled off the top''. You can view these previous lines with the following keys: KEY KEYACTION PgUp go one screenful backwards up arrow go one line backwards PgDn go one screenful forwards down arrow go one line forwards Home go to the oldest line End return to normal (Don't forget to turn the stupid NUMLOCK key off, if necessary.) When viewing previous lines, FidoTerm numbers the lines on the left to indicate their relative position. Characters being received while you are viewing previous lines are not lost; they are being stored for viewing later. Note that incoming data may cause scrolling previous lines to jump erratically, due to FidoTerm constantly adding the incoming text to the bottom of the viewable text. File commands -- ESCape FILE There are six sub-commands in the ESCape FILE prompt: DIR displays files on your disk(s). You must enter a file specification (DOS wildcard characters * and ? encouraged). Matching files will be listed, along with their sizes and creation dates. PROTOCOL lets you choose the file transfer protocol you want to use. (See the short, opinionated advice following this section on choosing a protocol.) If you have a choice, here's the short-form advice: ZMODEM most preferable, XMODEM clunky to use but ubiquitous. CAPTURE causes all text you see displayed on the screen to be saved in the disk file you specify. When there is a capture file active, the name of the file is shown in the status line (truncated to 16 characters). To stop capturing text, execute the command a second time. Entering the name of a file that already exists causes FidoTerm to append new text to the end of that file. RECEIVE transfers files from the remote computer (or BBS) to yours, using the protocol previously specified with ESCape FILE PROTOCOL . When using XMODEM, you must enter a filename; for ZMODEM and TELINK you can enter a pathname to receive the file(s), because the file-transmitting computer will send the filenames as well (XMODEM doesn't have this feature.) TRANSMIT transfers files from your computer to the remote computer, using the previously-selected protocol. For XMODEM you can enter only one name; for ZMODEM or TELINK, you can enter a list of names separated with spaces, and DOS wildcards * and ?. STATUS simply displays the result of the last file transfer, if there was one. After a file transfer, FidoTerm displays the status window for 20 seconds before returning to terminal mode. This command restores the file transfer status. Manually stopping a file transmit or receive Once a file transfer is underway, typing ESCape will ask if you want to terminate the transfer. (You may have to wait for FidoTerm to get back to you.) Answer appropriately. Answering ``N'' will continue the file transfer as if you had never interfered, though you may cause a data error in ZMODEM file receives, which FidoTerm will normally recover from. Baud rate command -- ESCape BAUD FidoTerm supports only the following rates: 300, 1200, 2400, 4800, 9600 and 19,200 and 38,400. Of course, setting FidoTerm's baud rate higher than what your modem or attached device is capable of won't work. Not all Async Adapters are capable of greater than 9600 baud, the design limit of the Async Adapter. You might find it works at 19,200 or above, but has an unacceptably high error rate. FidoTerm is not the problem. Upgrading the serial chip on your Adapter to a 16550 UART integrated circuit will greatly improve performance and error rate. Bit Tests These tests are non-protocol bit error rate and performance tests. Bit error rate testing (BERT) is a widely recognized method of testing asynchronous equipment, and a general discussion is outside the scope of this manual (how's that for a cop-out) though the overall behavior is covered following the test command descriptions below. You can interrupt a test at any time using the ESCape key. Also, receipt of eight consecutive Control-X (CAN) characters within a two second period will abort any test. (Obviously you should avoid this sequence in custom test patterns.) There are five sub-commands; each will prompt you for the test duration (specified in minutes, or MM:SS format, up to 4 billion minutes), optionally followed by a log interval, in the same format (not specifically prompted for). See below for bit error rate logging information. TRANSMIT-ONLY Performs send-only pattern testing and statistics. Single bit errors may be manually injected with the I key; the next time the pattern starts over the first byte will have bit 0 toggled. RECV-ONLY Performs receive-only pattern testing and statistics. BIDIR performs a bidirectional transmit/receive pattern test. The remote end should be physically jumpered or in loopback mode. Full transmit and receive statistics are displayed. LOOPBACK simply returns every character sent, without any testing or statistics. STATUS simply displays the result of the last test, if any. All of the tests except LOOPBACK require that the carrier detect (CD) signal from the async interface remain TRUE throughout the test; if at any time CD is lost, the test is terminated, and logged in the log file. And finally, FidoTerm issues a BER test identification string at the start of a test to inform the remote end of what is about to occur. (The identification string does not contain the test pattern start character (STX) and does not affect testing.) Bit error rate testing Bit error rate testing generates statistical information on a particular asynchronous communications link, using one or two computers depending on what is being tested. In general, testing consists of sending large numbers of bits in a predictable pattern and looking for discrepencies in the pattern received at the other end of the link. The pattern used is generally a ``quick brown fox'' type ASCII test pattern. The default test pattern contained within FidoTerm is: stx bel cr lf nul THE sp QUICK sp BROWN sp FOX sp JUMPS sp OVER sp THE sp LAZY sp DOG sp *****U1234567890 sp nul nul nul nul etx bel nul Where stx, bel, cr, lf, nul, etx are standard ASCII control character names, and sp is the space character. You can create a custom test pattern; see below for details. BERT accuracy Since BER testing is statistical, large numbers of bits (hundreds of millions or greater) are required for the tests to have any validity. FidoTerm's bit counting and error-rate arithmetic is highly accurate, and properly handles out-of-range values. Integer arithmetic is used throughout. The limit for bit counts (total sent and received, error bits, etc) is 4,294,967,999,999 bits. If that count is exceeded (good luck), `` >4,294,967,999,999 '' is display for the count in question, and any associated ratio that relies on that count (error rate, bytes/sec, etc) is displayed as a field of all asterisks. Ratios are calculated to one decimal point greater than the displayed value. BER testing consists of the transmitter outputting a fixed test pattern repeatedly, and the receiver comparing the stream of received bytes as a pattern of bits. Both the transmitter and the receiver must use the exact same pattern for this to work. The receiver synchronizes with the transmitter by waiting for the first character in the test pattern (ASCII STX in the default pattern), then comparing each subsequent character received against it's own copy of the test pattern, and checking for incorrect bits via an exclusive-OR. Each loop through the test pattern is called a block . Bit error rate is expressed as a ratio of good bits divided by bad bits, displayed traditionally in exponent form; one error bit per million bits is expressed as 1.000*10E-6 . It is possible for the receiver to get out of sync with the transmitter due to bit errors (dropped bytes, burst errors, etc). When this happens it is necessary to ``re-sync''. FidoTerm resyncs when it gets bad bits in any two consecutive bytes. (It is assumed that the overall error rate is low, and that bad bits are spread apart in time.) Errored time is the number of discrete one-second periods during which errors occurred, and is very useful for determining how bad bits are distributed over time. That is, at least one second without an error must go by for FidoTerm to consider a bit error to be within another errored second. Assume as an example you tested for 10 hours, and hundreds of millions of bits, and had 100 bit errors. If the errored time was one second, then all of those 100 errors occurred within that one second period; in other words, a burst of errors. If however the 100 bit errors was spread over 20 minutes of errored time, the system under test is dropping bits sporadically. ERR BL is shorthand for ``errored blocks'', the number of blocks (test pattern loops) that contained at least one bad bit. Resyncs is the number of times that FidoTerm had to resynchronize due to consecutive byte errors. These two are of dubious value to most users. BERT log data Because valid bit error rate testing requires huge numbers of bits and long periods of time, FidoTerm generates a detailed log of testing, but only if you use the TEST-LOG script command to specify a log file. (The best place for this command is in the startup script FIDOTERM.SCR mentioned previously.) When a BER test is started, if the specified file does not exist, it is created; if it already exists, FidoTerm appends new data to it's end. Log files are plain ASCII text files. Into the log FidoTerm places complete start-of-test information; during the test a record of activity is generated periodically; at the end of test overall statistics and test-termination information is logged. The default log interval is one-tenth the test duration. You can specify a log interval when the test is started, by following the test duration with a space and the desired logging interval. Custom BERT patterns FidoTerm can optionally use a test pattern you create and put into a file called FIDOTERM.BPT (not provided). You must use a text editor that gives you explicit control over characters entered; most word processors will not do this. BRIEF, MATE, and other ``programmer's'' text editors will. In the file you must put two things: the name of the pattern, terminated by a CR or CR/LF, followed by up to 256 test data characters. Characters within the file are used exactly, with one exception: 377 (255 decimal) represents a NUL character, because NUL characters are nearly impossible to enter with many text editors. Do not enter a NUL into the test patter file! (Therefore you cannot use 377 (255 decimal) in the test pattern, sorry.) Control-Z, SUB, 26 decimal, is a valid data character. Remember that both the transmit and receive FidoTerm programs must use the exact same pattern! The ``DOS'' command -- ESCape DOS This command temporarily returns you to DOS; FidoTerm is still occupying memory (approximately 256K), but is dormant. FidoTerm's settings and the screen are preserved while you are back in DOS. Please note that any incoming data from the modem is lost while you are in DOS; FidoTerm is dormant until you return to it. To return to FidoTerm, enter: EXIT Script command -- ESCape SCRIPT Scripts are disk files that contain instructions that FidoTerm executes as if it were a single command. Scripts allow you to create high level functions not directly built into FidoTerm. Because they are text files, you can write your own or modify existing ones. The autodialer function performed by function key F4 is a script file. Details on the script language are covered in a later section. FidoTerm prefers that script filenames have extension .SCR ; entering LOGIN at the ESCape SCRIPT prompt will result in FidoTerm executing script file LOGIN.SCR . Scripts are executed via the ESCape SCRIPT command, or via a function key. If a script requires arguments, simply enter them after the script filename: LOGIN "tom jennings" password Special startup script FIDOTERM.SCR When FidoTerm is first run, it tries to run a script named FIDOTERM.SCR . Please refer to the Running FidoTerm section at the beginning of this book for details. Controls command -- ESCape CONTROLS The CONTROLS command has three sub-commands; PARITY , SCREEN and ECHO . 2pt Parity -- ESCape CONTROLS PARITY Parity is rarely used on modern bulletin boards; it was once used as a magical talisman to ward off bad characters caused by mysterious ``line noise'' (clicks, hiss, disembodied voices, thunder and so on you hear on some phone lines). The idea was to steal one of the valuable 8 data bits in a byte for use as a ``parity'' bit, so that if the telephone company managed to corrupt your name into `` ( iDm Johnson'' your program could say ``aha! the parity is wrong!'' Big deal. You knew that the instant you saw it. Besides, there's a good chance the parity bit itself got trashed. For plain old typing, well, you can tell text from trash all by yourself. For file transfers, we have things like XMODEM and ZMODEM, which correct any errors during a file transmission. OK, I'll shut up now. The choices in FidoTerm are: NO parity means the 8th bit is left untouched; EVEN and ODD parity are the two parity choices; ZERO unconditionally clears the 8th bit, the parity bit. First, leave as No Parity; if you are calling something like Telnet, and it is not responding, try typing the alphabet: ABCDEFGHI If every other character is bad or missing, change to odd or even parity, try again. If you try to log into bulletin board systems such as Fido/FidoNet or Opus, entering certain characters while parity is selected will cause totally bizarre behavior -- the BBS will think you are trying to initiate a network mail transfer and cease listening to your otherwise potentially reasonable commands. If you want to use the extended IBM character set, you must use No Parity. 6pt Screen -- ESCape CONTROLS SCREEN These determine how FidoTerm treats incoming data for display on the screen. ANSI is the most common choice, and supports both IBM ANSI and a limited DEC VT100 subset of ANSI command sequences. Though a description of ANSI is outside the scope of this manual, briefly, ANSI is a predefined ``command language'' to instruct terminal programs how to construct simply graphical screen images, such as color, cursor position, screen editing, etc. (Make sure you have ESCape CONTROLS PARITY NO selected, otherwise extended IBM graphical characters will be corrupted.) Plain tells FidoTerm to ignore ANSI command sequences, and act like a ``plain'' terminal, such as a Teletype Corp. ASR-33 from the 1960's. Hex causes all incoming characters to be displayed as their two-digit hexadecimal equivalent. Echo -- ESCape CONTROLS ECHO Echo may be YES or NO -- yes meaning each keystroke you enter is displayed on your screen as well as being output to the serial port or modem. FidoTerm's Script Language Script files are text files containing FidoTerm instructions. All must have the extension .SCR . FidoTerm first looks for the script file in the current, default directory. If not found, it searches through each path in the PATH environment string. When executed via a command or script CALL instruction, FidoTerm loads the script into memory, stripping comments and tokenizing instructions. Hence, comments, instruction name length, and embedded spaces have no effect on performance. The script language supports recursion, local variables and pass-by-value parameter passing. There are no pointers (alas). It has a fairly thorough macro capability. There are rudimentary debugging tools built-in. Script files can call other script files. You can (and should) put subroutines into separate scripts and execute them with CALL and RETURN instructions, and pass parameters in and out of them, to do such things as dial phone numbers, search for text, etc. Each subroutine has it's own private workspace so that each can be written as a separate script. Of course scripts can execute any FidoTerm command. Script Language Machine Model FidoTerm's script language is a machine language, and like all machine languages, there is an underlying ``model'' machine that the script instructions manipulate. The script machine model has the following components at your disposal: NAME NAMEDESCRIPTION &AThe numeric accumulator, values 0--65535 &BThe baud rate register &CThe clock, counts up, in seconds &EThe error register &RThe general purpose Recognizer &SThe special shift register, 20 characters, &TThe trap register, 0 or 1--65535 seconds &0--&9Local, general-purpose registers stack10 levels of data stack Register characteristics All registers can contain numbers in the range of 0 to 65,535, and registers &R , &S and &0 to &9 may contain either numbers or text. If a register containing text is used with an arithmetic instruction, it is considered to be zero. All letter registers ( &A -- &T ) are global ; changes made to them by any routine or subroutine will be available to all. The numeric registers ( &0 -- &9 ) are local ; each subroutine has it's own set of numeric registers. For example, if script MAIN.SCR calls subroutine DIAL.SCR , changes made to the numeric registers by DIAL.SCR do not affect MAIN.SCR 's numeric register values. &A The accumulator (such a quaint word) is a simple register for storing or manipulating numbers. It can be set to any value from 0 to 65535. It can be stored into any other register. There are instructions to test when the accumulator is zero. &B The baud rate register contains the current serial port baud rate. It can be set to one of the following values: 300, 1200, 2400, 4800, 9600, 19200 or 38400. Attempts to set it to other values will be ignored. &E The error register has the same characteristics as the accumulator, &A. There are special instructions to set and test the error register. By convention, non-zero is considered ``error''. &R The Recognizer is a general purpose register, and can contain text or numeric values. The shift register is a special register that contains the last 20 characters received from the modem, and is what patterns are matched against. Characters are shifted in from the right, and the left most character ``falls off'' the end. You can also store text in &S and use the IF instruction to do string comparisons. Note that assignments from &S to other registers will probably not have the desired effect due to its peculiar right-to-left nature. &T The trap register is part of a mechanism to break endless loops; the TRAP instruction is used to set a failsafe if a script or part of a script takes too long to execute. Please refer to the TRAP instruction description for details. &0--&9 The numeric registers are local general purpose registers that may contain text or numbers. These registers have an initial value set by the calling subroutine. A CALL instruction puts parameters into these registers, from left to right, stripping off one level of quotes. The stack is a general purpose ``push down'' stack; you PUSH items onto the stack, and POP them off. Items can only be accessed from the top of the stack. There is room for up to ten items on the stack. If there are (for instance) five items on the stack, to get at the first one pushed (the ``bottom'' of the stack) you must first pop off the four on ``top'' of it. Instruction Processing The script processor is an interpreter, scanning lines of instructions from top to bottom, left to right. Program control can be altered with jump, call, return or trap instructions. The macro processor is at the very heart of the script language, and is a great source of it's power. The macro format is the same as standard ``C'' language, slightly extended. Notes on quotes The proper use of quotes can be somewhat confusing if you are not in tune with how traditional macro processing works. To make things worse, many times you can use them improperly and it doesn't seem to matter. The problem is due to ``quote stripping''. Quotes are a container around a string of characters, and occur in pairs. Each time FidoTerm uses a string, it strips off one layer of quotes. For example: message "This is a string" ;an example displays the text between the quotes on the screen; the quotes have been stripped off. They are there to tell the instruction processor where text begins and ends; we don't want it to display the comment in the example above. &R= "415-863-2739 Tom Jennings" This example puts the text given into the &R register. The quotes are stripped as the string is read; therefore &R contains 4, 1, 5, -, i, n, g, and s, without the quotes. The instruction message &R would display: 415-863-2739 Tom Jennings The contents of a register is treated as a single indivisible unit. Argument passing What if you wanted to separate a string into its component strings, as in the example above, separating the phone number and name? When a subroutine is called, FidoTerm passes arguments to the subroutine in the numeric registers. Examples: call LOGIN ;no arguments passed call LOGIN "first", "second" ;two arguments In the first example, when LOGIN executes, &1 -- &9 are all empty; in the second, &1 contains first and &2 contains second . Consider the following two examples: call ENTER "&R" call ENTER &R When executed, ENTER.SCR &1 contains 415- 0pt 863- 0pt 2739 Tom Jennings , because the string (ie. &R contents) is contained within quotes. In the second example, it receives &1 containing 415-863-2739 , &2 containing Tom and &3 containing Jennings , and so on. Zero or one? The first passed parameter is put into &1 , not &0 . String concatenation Combining multiple strings is easy. To concatenate all of the strings in the above example into one string: &R= "&3, &2 tel. &1" would result in: Jennings, Tom tel. 415-863-2739 Control characters Note the`` '' before the quote character merely quotes what follows. There are some convenient short-hand exceptions: 255 rcarriage return, 13 decimal nline feed, 10 decimal eescape, 27 decimal bbackspace, 8 decimal cETX (Control-C), 3 decimal 1SOH character, decimal 1 127DEL character, decimal 127 You can also enter control characters like so: A1 decimal, ASCII SOH Mcarriage return, 13 decimal Jlinefeed, 10 decimal Instruction argument handling -- more examples The ADD instruction adds a value to the accumulator. For example: ADD 27 Would add 27 to the accumulator; if it had contained 3, it would now contain 30. If the &2 register contained ``34'', the following: ADD &2 Would add the numeric value 34 to &A . Here are some further examples. Assume first: &A contains 20 &R contains ``Text'' &1 contains ``863-2739'' &2 contains 300 DIALING XXX AT XXX BAUD XXX INSTRUCTIONOPERAND EXPANDED message "sample text" sample text message &R 20 message "pattern is &r, OK?" pattern is 20, OK? message "&A&R&A" 20Text20 message "Dialing &1 at &2 baud" Dialing 863-2739 at 300 baud You can take this to absurd extremes. The instruction JMP label passes execution to the line following the line containing label :. You can take advantage of this by using a ``computed goto''. The command: jmp "&R" Would attempt to label TEXT: in the current script. You would of course get an error if it didn't exist. Pattern Matching The main purpose of FidoTerm's script language is pattern matching; looking for particular strings of characters received from the modem. The single most important component of the script machine is the Shift Register, &S. The shift register contains the last 20 characters received from the modem. As characters are received from the modem or serial port, the characters (if any) in the shift register are shifted left, creating a ``hole'' on the right-hand end, and dropping off the left-most character, and the newly received character added into the hole on the right-hand end. The shift register is an extremely powerful way to test for patterns. There is also a more usual, simple wait-for-a-specified-string type instruction ( MATCH in FidoTerm's instruction set). Both are very useful. For example, you've called a bulletin board, and this is the sign on message you see: WELCOME TO THE ACME HOG THROWERS BBS ENTER YOUR HOGS NAME AND PASSWORD: (Let's assume it is asking your for input; you could enter it manually and proceed. The general idea here though is to automate the process by detecting when the remote BBS is asking a question, and automatically providing the correct response to the question. You of course have to know which text is the question (us humans know immediately); providing the answer is easy. We are trying here to define the general problem of detecting the question.) Lots of times a simple instruction will do exactly what you want ( MATCH "PASSWORD:" ). This sort of thing is easy to write scripts for, and even in complex scripts is a very useful function. In FidoTerm the technique used involves a 20 character array called the shift register , referred to as &S in the script language. The shift register changes after a character is received from the modem; in the example above, W, E, L, C, O, M, E, etc. Part way through the above message being displayed, the shift register would look like: to 2.5in WEL to 2.5in WELC to 2.5in WELCO to 2.5in WELCOM to 2.5in to 2.5in LCOME TO THE HOG THRO to 2.5in FidoTerm compares patterns you specify against the right hand end of the shift register; this means that for each character received (therefore a new string each time) you can look for any reasonable number of possible patterns. In this example, to do an automatic login, once we see the word PASSWORD: , we can output the name and password. This is a common and simple case. The MATCH instruction will do the job. MATCH compares text you specify against the contents of the shift register. For this example we'd use WORD: . A string match is used, so you only need to use enough characters to make it unique; the string WORD: does not appear anywhere else in the initial sign on message. (Actually, : (a single colon) will work fine here, but it's a good idea to use at least a couple of characters; if for no other reason than you, the programmer, can tell later what you were trying to do.) MATCH "WORD:" To continue the example above, as characters come in from the modem they shift through the shift register. FidoTerm is executing the MATCH instruction above, and the shift register looks like: to 3in 4pt to 3in match WORD: to 3in against OGS NAME AND PASSWOR 4pt to 3in match WORD: to 3in against GS NAME AND PASSWORD 4pt to 3in match WORD: to 3in against S NAME AND PASSWORD: For each character received, the MATCH instruction is comparing it's pattern ( WORD: ) against the contents of the shift register. When the patterns match, the next line of the script file is executed, which in this case could be an instruction to output your name and password. Complex Pattern Matching You don't need to understand the how and whys of the shift register to use the MATCH instruction, and for most casual script writers that will be all you need. A good example of the limitations of such a simple system is a script that dials phone numbers with a modem using ``AT'' commands, and responding to the many possible ``result codes''. (This example assumes a basic understanding of modem commands.) The dialing part is easy; you just issue the ATDT command and the phone number. The problem arises when you try to interpret the results of that command, such as busy, no answer, connecting at various baud rates, errors, etc. A simple MATCH instruction just won't work. For example the US Robotics Courier HST has over a dozen possible responses to a simple dial command; any script you write must be able to handle them all. That's what we'll do here. Dialing a US Robotics Courier HST (Or other ``AT command'' modem.) The command we'll use, for simplicity, is: AT DT 764 1629 r" (`` r'' means carriage return, CR, decimal 13) The modem can respond with any of the following result words: # # CONNECT (300 baud) RING (incoming call) NO CARRIER (failed to connect) ERROR (bad command given) CONNECT 1200 (connect at 1200 baud) NO DIAL TONE BUSY NO ANSWER CONNECT 2400 RINGING VOICE CONNECT 9600 This is where you take advantage of the shift register. The script fragment below handles the problem at hand and is explained below. You will be using this SAMPLE/ IF/ JMP loop to do most complex string compares. (Note that this example is simpler than the DIAL.SCR provided with the FidoTerm program.) &t= 60 ; very short timeout... &c= 0 trap failed output "ATDT 863-2739 r"; dial command and number get-result: sample if "9600" 9600b if "4800" 2400b if "2400" 2400b if "1200" 1200b if "300" 300b if "VOICE" voice if "ECT r" 300b if "BUSY" busy if "RING" ring if "NO" noans jmp get-result busy: message "Busy, redialing ..." &t= 60 ;re-set trap to 60 sec delay 1000 ;let it go onhook! output "A/ r" jmp get-result ring: message "Ring!" jmp get-result timeout: message "The modem is dead as a doorknob" return 1 noans: message "No connection!" return 1 voice: message "Voice!" return 1 ;---------------- 300b: &a= 300 jmp connect 1200b: &a= 1200 jmp connect 2400b: &a= 2400 jmp connect 4800b: &a= 4800 jmp connect 9600b: &a= 9600 jmp connect 19200b: &a= 19200 connect: &b= &a ;connect baud rate, message "Connected at &a baud" return 0 SAMPLE is a special instruction for use in SAMPLE/ IF/ JMP loops, and causes one character to shift into the shift register. (The MATCH instruction and most others do this automatically, but IF doesn't.) You should have one, and only one, SAMPLE instruction before each set of IF instructions; if you have none, the shift register will not ever change, and if you have more than one you will miss patterns. IF compares the given pattern against the current contents of the shift register, and branches to the specified label if a match is made. The patterns searched for by the IF instructions must be unique. You could search for the entire modem response ( CONNECT 1200 instead of just 12 ) but the script will be slightly more immune to line noise (ie. corrupted data) when the to-be-matched data is shorter. The NO pattern will match any of the following, which all mean no connection: NO CARRIER, NO DIAL TONE, NO ANSWER. The 300 baud connection result code is CONNECT , hard to distinguish from CONNECT 1200 because the IF will match CONNECT without waiting for the 1200 or whatever follows. The ECT r means that it will only match that word at the end of a line, that is, followed by a CR character. With a loop of approximately this size, it would take many thousands of characters at high speed to cause character loss. In the example above, speed is not a problem; the modem issues very little text. Further Notes on Pattern Matching The strings you provide to the MATCH and IF instructions have some characteristics that make for easier comparisons. All searches are case in -sensitive. ANC is the same as anc , etc. You can specify it in your script in either way. ? is a wildcard character; it matches any character. CONNECT ??00 will match CONNECT 1200 , CONNECT 2400 , etc. Control characters are treated just as any other character. ``End of line'' characters will vary with the bulletin board program or whatever it is you call; Fido for instance is like most BBSs, and uses a CR/LF sequence (decimal 13, decimal 10). You can search for `` r'' or `` 13'' or for `` r n'' or `` 13 10'', but keep in mind that other systems could use LF/CR, or other combination. Register and Arithmetic Instructions Please note that there must be at least one space after the ``=''. &S= is a single word. &S= text &R= text &1= text or number &2= text or number &3= text or number &8= text or number Store the specified string or number in a register. The string must be under 20 characters. &A= value Set the accumulator to the specified value. The accumulator is numeric only, 0--65535. &B= value Set the baud rate register to the specified value; if the value is not a valid baud rate then the &B register will not change. &C= value Set the free-running clock to an initial value. The clock counts up continuously every second. &T= value Set the trap register to the specified value. Setting it to zero disables the trap. ADD value SUB value Add or subtract the value to the accumulator. PUSH text Puts the text onto the top of data stack. There are only 10 levels so watch out. Anything can be pushed onto the stack. POP register Take the top item off the stack and place it in the specified register. If you try to put non-numeric text into a numeric register it becomes ``0''. You cannot POP items not PUSH ed. Flow Control Instructions JMP label Branch to the specified label unconditionally. JZ label JNZ label Branch to the specified label in the current script file if the accumulator &A is zero (JZ) or not zero (JNZ). (Test other registers by first storing them in &A .) DJNZ label A basic looping instruction: ``Decrement and Jump if Not Zero''. Subtracts 1 from &A , and if the result is not zero, branches to the specified label. JERROR label Branches if the &E error register is not zero. &E is set by the MATCH instruction timeout, and the RETURN (from subroutine) instruction. It may of course be set as any other register. CALL scriptfile parameters Execute the script file as a subroutine. The filename is scriptfile .SCR . The called script file can in turn call other scripts, and each executes until the end of the script file or a RETURN instruction is executed. Each subroutine has it's own set of registers, &1 to &8 . Parameters can be passed to the called routine, which set the initial value of the local registers. The contents of the local registers are lost when the subroutine returns. RETURN value Return to the calling subroutine (if any) and optionally set the error register to the specified value. TRAP label This instruction is used to set a time limit on script execution, usually loops searching for a pattern. The trap uses the &C clock. The &T trap register is set to the specified number of seconds, and the &C clock is reset. Before each script instruction is executed, the clock is compared against the trap time; if the time limit is exceeded, the script branches to the specified label in the script file that initially set the trap; therefore the trap can even abort scripts running many subroutine calls deep. Setting the &T trap register to zero disables the trap. &T= 0 &C= 0 TRAP label If at any time during script execution the &C clock reaches or exceeds the &T trap register, script execution proceeds from the specified label in the current script file. String Comparison Instructions MATCH pattern, limit Wait until the pattern is found in the incoming character stream before executing the next instruction in the script. The pattern can contain ``?'' wildcard characters. There is an implicit limit of 60 seconds; if a match is not found with the time limit the error register is set and the next instruction executed. (Presumably a JERROR instruction.) Optionally a time limit, in seconds can be specified. SAMPLE Shifts one character into the shift register; to be used in SAMPLE/ IF/ JMP loops. IF pattern, label Compares the given pattern against the contents of the &S shift register, and branches to the specified label if it matches. The pattern can contain ``?'' wildcard characters. User Input Instructions INPUT prompt The prompt is displayed and the user enters a line of text from the local keyboard, terminated with an ESCape or CR. Text strings are placed in variables &1 through &8 . MINPUT prompt Prompt for an input a line of text from the modem or serial port, not the local console. Text is stored as a single string in the shift register, &S . ASK question The question is displayed and ``Y'' or ``N'' is input as a response, with &E set true if the answer is ``Y''. PAUSE prompt The prompt is displayed and the user must hit any key to continue. MESSAGE message Output the message to the command status line. KEYBD char Temporarily suspend script file operation until the user types the specified key; CR if none specified. All characters the user types, including the terminating one, are output to the modem. This allows the user to manually enter something such as password. Character Input/Output Instructions OUTPUT string Queue the string for output to the modem, simulating manual keyboard entry. The speed with which characters are output is determined by the THROTTLE setting. COPY string Output the string directly to the modem at maximum speed. QUIET milliseconds (1--65000) Read characters from the modem, if any (throwing them away) until the modem is quiet for the specified time. In other words, wait for activity to pause or stop. THROTTLE n (0--500) This controls the maximum speed that FidoTerm will output characters queued up by the OUTPUT command. The speed is specified in a minimum wait between characters, in milliseconds. The default is 20 milliseconds. File I/O Instructions FidoTerm's file system is very simple; there can only be one file open at a time. It is not a coincidence that the file format is compatible with most BASICs; each record in a FidoTerm file contains 8 fields, each field is a quoted string separated by commas. Each record is delimited with a CR/LF. There is no Control-Z or other end of file terminator. FOPEN filename Opens a file for reading or writing. The script is aborted if the file cannot be found, or if UNATTENDED is set, then the error register &E is set. The file must be FCLOSE d when not needed. FNEW filename Creates a new file of the specified name. The script is aborted if the file cannot be created. The file will be empty after creation. FREAD Reads one record from the file, and deposits the contents of the record into the eight registers &1 to &8 . Each record can contain any number of items, but only the first 8 will be used. Each should be an argument as described elsewhere, preferably quoted. Lines are read from the file one per FREAD instruction, starting with the first line in the file, until the last line is read; all FREAD s after the last line will leave all registers empty and set the error register &E . FWRITE A new record is added to the end of the open file, that contains the contents of the eight registers &1 to &8 . Each is ``quoted''. The script is aborted if the disk becomes full, or if UNATTENDED is set, execution continues with error register &E is set. FCLOSE This closes the current file and allows the FOPEN ing of another file. Special Instructions FIDOTERM FidoTerm commands You can execute any FidoTerm built-in command from within a script using this command. You must supply the exact keystrokes you would have used to execute that command exactly except for the ESCape character; for example, to set the baud rate to 2400 you could use: FIDOTERM B 2400 (Even though &B= 2400 would be simpler.) Though you must supply the exact keystrokes that you would if you were executing the command manually, you can add spaces for readability. The two examples below are equivalent: FIDOTERM FT*.EXE FIDOTERM F T *.EXE Which is equivalent to ESCape FILE TRANSMIT *.EXE . The second example it more readable. Of course you can use the script language conventions as always: FIDOTERM F T &1 Would be similar to the previous example, except the filename is the contents of register &1 . DELAY milliseconds (1--65000) Waste some time; delay execution of the script until time elapsed. NODE zone:net/node Can be used only with a Fido/FidoNet bulletin board system, or after creating the nodelist files using Fido's MAKELIST tool. FidoTerm searches for the specified node in the nodelist; if not found, or nodelist files are missing or the wrong revision, &E is set non-zero. Otherwise the node information is set as follows: xxxxxxxxxxxxxxx &1 = baud rate (300, 1200, etc) &2 = phone number &3 = name of the node &4 = city TIME hh:mm (00:00--23:59) Wait until the specified time of day before executing the next line in the script file; a crude tool for scheduling events. FILES filespec Sets &A to the number of files matching the file specification. File-transfer instructions These instructions control the behavior of the file transmit and receive functions in FidoTerm. ZMRXTYPE and ZMTXTYPE are obscure and can be ignored. They are most useful when put in the startup script, FIDOTERM.SCR . ZMODEM-PATH pathname Specifying a pathname (directory name or drive letter) enables ZMODEM auto-receive. When enabled, FidoTerm will detect ZMODEM file transfers from the remote computer and automatically receives files to the specified pathname. You can use a regular, forward slash character in pathnames, since the backslash has special meaning to FidoTerm's script processor; C:/DEFAULT/FILES is exactly equivelant to C: DEFAULT FILES . COLOR n Specify a color and video attribute for FidoTerm's status line display. The method used is rather crude. The number you enter is the bit pattern directly stored in the video adapter card's memory. (Luckily you only have to do this once.) If you have a monochrome adapter, using color values will probably do odd-looking things to your display, but is otherwise harmless. Choose a character color, a background color, add them together, and use the resulting number. For example, red characters on a blue background (yuck) would be or 20. Do not use the same color for both characters and background; FidoTerm will do exactly what you tell it to do # # # # Characters Background 0 black 0 black 4 red 64 red 2 green 32 green 6 orange 96 orange 1 blue 16 blue 5 magenta 80 magenta 3 cyan 48 cyan 7 white 112 white This command is most useful when used in the FIDOTERM.SCR startup script. CURSOR-HEIGHT n Controls the size of the cursor. The allowable range is 1 -- 6, and the default is 1, for a normal underline cursor. For LCD laptop cursors, 6 is recommended. This command is most useful when used in the FIDOTERM.SCR startup script. PROTOCOL protocolname Selects the default file transmit/receive protocol to use. (Which may be changed manually at any time with the ESCape FILE PROTOCOL command.) Allowable protocol names are (first letter required): Zmodem, Xmodem, Telink, Ascii. This command is most useful when used in the FIDOTERM.SCR startup script. FILE-LOG logfilename If one is specified, FidoTerm logs file transmit/receive activity to this file. See the comment in the ZMODEM-PATH definition above regarding the use of the slash character. TEST-LOG logfilename If a filename is specified, bit test activity is logged into this file, at the specified log interval (entered following the test duration) or 1/10th the test duration. See the comment in the ZMODEM-PATH definition above regarding the use of the slash character. ZRXTYPE 0, 1 Controls Zmodem's receive behavior: 0 means accept full streaming, the default. Change this to 1 only if your system cannot handle full streaming; this is possible if you are running under a multitasker. ZTXTYPE 0, 1--64, 1024-65536 Controls Zmodem's transmit behavior: 0 means non-stop full streaming, the default. All other values force the use of a sliding window: 1 -- 64 means the window size is that many blocks; 1024 -- 65536 defines the window size in bytes. Line control and hardware instructions These instructions affect the serial port settings, and are most useful when put into the startup script FIDOTERM.SCR . IO-PORT n (1--4) Select the serial port to do business with; the default is the first port, on a pclone COM1. The most useful place for this instruction is in the start up script, FIDOTERM.SCR . Note that to use COM3 or above ( io-port 3 , etc) you must use a FOSSIL driver.) CDBIT (1,2,4,8,16,32,64,128) Set the Carrier Detect (CD) mask bit for proper operation of the on-screen online/offline display. The default is 128, correct for all pclone Async ports. If the display always says ONLINE, it may be that you have the ``CARRIER DETECT: ALWAYS ON'' option switch set on your modem. CD-TRAP label Similar to the TRAP instruction, but causes an immediate branch to the specified label if the Carrier Detect (CD) signal goes false. (Carrier Detect is a signal provided by the modem or external device; see the CDBIT instruction.) DTR Lowers the modem control line Data Terminal Ready (DTR) for one half second. (Makes most modems disconnect and go into command mode.) BREAK Causes a 500 mS line break. A ``break'' is not a character, but a phenomenon of RS-232 design; it causes most modems to interrupt whatever it is doing. Please refer to your modem documentation. Script execution instructions These instructions control how scripts themselves behave. TRACE n When on ( n not 0) FidoTerm displays each instruction on the status line before it is executed, and requires you to hit the space bar to execute it. In other words, single-step execution. 0 turns it off. CONSOLE n Causes modem input/output to go to/from the local keyboard, allowing you to debug scripts that would otherwise require a second computer and special cabling. 0 is off (default), non-zero turns this feature on. UNATTENDED n Controls FidoTerm's error handling and user interaction requirements. Normally, FidoTerm will abort script execution upon certain errors, such as ``no such file'' for a file transmit, or require the user to ``type any key'' after completion of some commands. This causes errors to set the error register, &E , instead of aborting the script, and to skip ``type any key'' type delays when n is non-zero.