les, I have the CRC variables in direct page ram. 24 Ultimaterm Clock files One thing Ultimaterm had that many people liked was the ability to support a hardware or software clock. To add the clock display to Ultimaterm, one had to run a program called "ADDCLOCK.BAS" which appended the ML clock to Ultimaterm so they would both be loaded at the same time. Unfortunately, in the course of it's travel to Delphi, Ultimaterm ended up some 512 bytes shorter than when it left me, and the appending of the clock didn't work. All you have to do for Ultimaterm V4.0 is rename the clock file you wish loaded to "ULTCLOCK.BIN" and when you LOADM Ultimaterm, it will load that file automatically. I have included three sample clock files with Ultimaterm for some of the more common real time clocks that are available for the CoCo. The first of these files is called "MC146818.CLK" and allows the displaying of time using that particular clock chip. The Speech Systems RTC will work with that clock file as will most home-made clocks. The second file is called "DISTO.CLK" and will work with the Disto clock or any other clock that uses the MSM5832 chip. The third clock file that comes with Ultimaterm is a software clock. If the software clock is selected and loaded into memory by Ultimaterm, then the time can be set from the terminal mode with [ALT]-[Z]. The software clock is by no means reliable, but will give you a general impression of just how long you've been using a system. The clock speed will vary with what baud rate you have and whether you use the serial port or the RS232 pak. 25 Ultimaterm's Keyboard Another area of Ultimaterm not left untouched was the keyboard driver. I wrote a new one that allows much better control over the speed and delay of the key repeat. Besides all the regular keys (like [A], [S], [D] and [F]) I have assigned a few unique values to a few keys or key combinations (some you know of course). They are as follows: To generate Press -------------------- ------------------ Up arrow pic [^@] Caret ^ [SHIFT]-[@] Underscore _ [SHIFT]-[up arrow] Left Brace [ [SHIFT]-[dn arrow] Right Brace ] [SHIFT]-[rt arrow] DELETE ($7F) [SHIFT]-[lf arrow] Right parenthesis [F1] Pipe [F2] Left parenthesis [SHIFT]-[F1] Tilde [SHIFT]-[F2] ^C ($03) [BREAK] BS ($08) [lf arrow] TAB ($09) [rt arrow] LF ($0A) [dn arrow] VT ($0B) [up arrow] FF ($0C) [CLEAR] CR ($0D) [ENTER] ESC ($1B) [SHIFT]-[BREAK] -------------------- ------------------ All [CTRL] key combinations are also enabled. Screen Control Certain characters or combinations of characters will perform various controls over the screen. The following lists the characters and what they do no matter what terminal emulation is set: Character rcvd What it does -------------- ---------------------------------------- BEL ($07) Rings Ultimaterm's bell BS ($08) Backs the cursor up one column HT ($09) Moves the cursor to the next 10's column LF ($0A) Moves the cursor down one row VT ($0B) Moves the cursor up one row FF ($0C) Clears the screen, homes the cursor CR ($0D) Moves cursor to column 0 of the same row -------------- ---------------------------------------- 26 DEC VT-52 Control Codes The following is a list of the supported VT-52 control codes that are received or transmitted when Terminal Type is set to VT52: A Move cursor up mpts at checksum. If you say no, you will be returned to terminal mode. While the transmission is coming across, you will get to watch it through a 20 byte window along the bottom of the Xmodem Receive window. At any time during ANY transmission (be it Xmodem or Ymodem) you can abort the transfer by pressing [SHIFT]-[BREAK] (ESC). If you're receiving a file, Ultimaterm will wait until the transmitter stops sending the current block and then let the sender know the transmission is aborted. If you are receiving a file to disk, and the disk becomes full to capacity, the transmission will be aborted to save you any further charges on long distance transmissions. 22 CRC Option The formal definition of the CRC calculation is "The message polynomial is first multiplied by X^16 and then divided by the generator polynomial (X^16 + X^12 + X^5 + 1) using modulo two arithmetic. The remainder left after the division is the desired CRC" (XMODEM/YMODEM PROTOCOL REFERENCE, Edited by Chuck Forsberg, 5.1.1 Formal Definition (CRC Calculation)). A sample calculation under 'C' (right from the above source) is /* This function calculates the CRC used by the XMODEM/CRC Protocol. * The first argument is a pointer to the message block. * The second argument is the number of bytes in the message block. * The function returns an integer which contains the CRC. * The low order 16 bits are the coefficients of the CRC. */ int calcrc (ptr, count) char *ptr; int count; int crc, i; crc = 0; while(--count >= 0) crc = crc ^ (int)*ptr++ << 8; for (i=0; i < 8; ++i) if(crc & 0x8000) crc = crc << 1 ^ 0x1021; else crc - crc << 1; return (crc & 0xFFFF); Since I don't understand 'C' yet, and the formal definition went above my head, CRC seemed an impossibility until Rex Hebert sent me the OS9 assembled source under the 6809 which he in turn got from Delphi. In Ultimaterm V3.0 I waited until the block was received and then calculated the CRC on the block. In Ymodem transmissions, block lengths of 1024 characters caused a noticeable delay while the CRC was being calculated and I realized that this delay would be costing users of DELPHI and CIS a bit extra money. I rewrote my CRC calculation subroutine so that as each character was received, it would be added to the 16 bit CRC which would be started at zero. 23 Because the original CRC calculator was not written by me, I would like to offer the subroutine used in Ultimaterm to public consumption. It is as follows: * * CRC Calculator for X/Ymodem * * enter with (A) holding the byte to add * to the CRC. Exit with the two-byte * variable 'CRC' holding the updated CRC * calculation. * CRC FDB $0000 Variable to hold the CRC CRCVAR FCB $00 Variable to count the SHIFTs * CALCRC PSHS D Preserve registers used LDB #8 Get ready for the 8 bit shift STB CRCVAR Hold it for later EORA CRC XOR byte to the CRC LDB CRC+1 Make (D) the entire CRC value CRC1 ASLB Rotate the (D) register to get the ROLA dropped bit (X^16) in the carry flag BCC CRC2 Branch if not X^16 EORA #$10 Otherwise XOR with the rest of EORB #$21 the polynomial (X^12 + X^5 + 1) CRC2 DEC CRCVAR All 8 bits shifted through? BNE CRC1 Not yet STD CRC Else save the new CRC PULS D,PC and return * With the CoCo 3 running at double speed, the above CRC routine doesn't seem to slow down any running 2400 baud through the serial port. To save a few extra cycaterm also allows files to be sent from the text buffer or right from disk (or ramdisk if 512K is present). When you select [ALT]-[X] the following window will appear: Transfer Files T Transmit Buffer R Receive Buffer S Xmodem Send U Ymodem Send X Xmodem Receive Y Ymodem Receive D File Transfers to DISK "Transmit Buffer" simply sends the contents of the buffer across the modem in a straight ASCII dump. If a CAN (^X) is received from across the modem or you press [SHIFT]-[BREAK] (ESC), the transmission will be aborted. "Receive Buffer" simply waits for an ASCII transmission from across the modem and then opens the buffer and captures all incoming text. If no text is received within one minute of selecting "Receive Buffer" then the message "Timed out on Remote" will be displayed. If, after the transmission is started, no text is received within two seconds, then Ultimaterm will assume a successful transmission and close the buffer. If "Auto-Clear" is enabled, Ultimaterm will not clear the buffer until the first character is received. This allows you to abort the transmission with [SHIFT]-[BREAK] and not loose any contents in the buffer. Pressing [D] allows you to perform Xmodem or Ymodem transfers to/from disk. When disk is selected, the choice on the menu will change from "File Transfers to DISK" to "File Transfers to BUFFER". Press [B] and Xmodem or Ymodem transfers will be performed to/from buffer. The status of the disk/buffer flag is saved with the default options. If transfers to disk are selected and you choose Xmodem or Ymodem Receive then the top five lines are scanned for a filename. First it looks for the word "File" in any case. Then it looks for a ":" within ten characters from the word "File". Finally it skips over any spaces (up to ten) to the filename which it reads in and converts to uppercase. Correct formats which Sysops might want to implement in their file sections could be as follows: File : Ultimate.bin or FILENAME: ULTIMATE.BIN or File: Ultimate.BIN I'm sure you get the idea. 21 "Xmodem Send" allows you to transmit a file from either disk or buffer using Ward Christensen's original protocol or the CRC option as explained by John Byrns in "XMODEM/YMODEM PROTOCOL REFERENCE" edited by Chuck Forsberg. "Ymodem Send" allows you to transmit a file from either disk or buffer using the Ymodem protocol explained by John Byrns in the aforementioned document. "Xmodem Receive" allows you to receive a file to disk or buffer using either the original Xmodem checksum protocol designed by Ward Christensen or the Xmodem CRC protocol explained by John Byrns. "Ymodem Receive" allows you to receive a file to disk or buffer using the Ymodem protocol explained by John Byrns. If you are receiving to disk, you will be asked for the filename, extension and drive to receive to (select drive 4 to receive to ramdrive) and then you will be asked for the file type (ASCII, BASIC binary, etc.). If you are transmitting from disk, you will be asked for the filename, extension and drive of the file you wish to send. The X/Ymodem window will pop up and transmission will start. First thing that happens is the CRC option is attempted. A "C" is sent across the line signaling the transmitter that Ultimaterm will accept the transmission using CRC protocol. If the receiver doesn't work with CRC, it will ignore the three attempts Ultimaterm makes at CRC and should catch when Ultimaterm switches over to checksum. If, after ten attempts at checksum, no response is received from the transmitter, Ultimaterm will print the window "Timed Out" and ask if you would like to try again. If you select yes, Ultimaterm will restart the transmission making three attempts at CRC and ten atte the computer picks up (in case you didn't know!). I find it very useful myself while others find it annoying. You can toggle keyclick on and off by pressing [ALT]-[K]. [ALT]-[M] Monochrome/Composite toggle Not everyone is blessed with an RGB monitor of any brand. If you are using a television or monochrome monitor, [ALT]-[M] will be especially of interest to you. This command toggles the display between black on white and shades. When in "black on white", the colorburst will be disabled to make an even clearer picture on a TV set. [ALT]-[O] Set Options Please refer to the beginning of this manual so I don't have to type this section in all over..! [ALT]-[P] Print Screen This does a straight dump of the screen to an 80 column printer so that you can forever keep a copy of the current display on the screen. If the printer is not ready, the screen dump will be aborted so as Ultimaterm doesn't sit around waiting for a printer to come online. If you have to, use [ALT]-[F] to freeze the screen while you get your printer ready. [ALT]-[Q] VT Keypad Toggle For all you people who use your terminal program on a VAX network of any kind, Ultimaterm will not only support screen controls sent out by these systems, but will also do it's best to emulate the keyboard of one. When [ALT]-[Q] is turned on, you will see a "%" on the top status line and some keys will be reassigned new values. They are as follows: VT-100 or ANSI emulation Key New Assignment Transmitted codes ------------- -------------- ----------------- Shift @ Home cursor (1B5B48) Up arrow Cursor up (1B5B41) Down arrow Cursor down (1B5B42) Right arrow Cursor right (1B5B43) Left arrow Cursor left (1B5B44) CLEAR Clear screen (1B5B481B5B324A) Shift ENTER Erase to end of line (1B5B4B) 19 VT-52 emulation Key New Assignment Transmitted codes ------------- -------------- ----------------- Shift @ Home cursor (1B48) Up arrow Cursor up (1B41) Down arrow Cursor down (1B42) Right arrow Cursor right (1B43) Left arrow Cursor left (1B44) CLEAR Clear screen (1B481B4A) Shift ENTER Erase to end of line (1B4B) If in VT-100 emulation and the host asks for application control functions, then Ultimaterm will change all the "1B5B" sequences in cursor movements to "1B4F". If you're not familiar with what I mean by "Transmitted codes", all I'm saying is that when you press a key (e.g., CLEAR under VT52), the codes 1B (ESCape) 48 ("H") 1B (ESCape) 4A ("J") will be transmitted across the modem. [ALT]-[S] Buffer checksum This command adds together the 8-bit values of the bytes in the buffer and comes out with an 8-bit checksum value. The only real use for this is to check a file after it's been received to make sure the receiver got the file properly. Since Xmodem and Ymodem have their own error detection and correction processes, this command's value will lie in ASCII transfers. The larger the file is, the longer you'll have to wait to be told the calculation of the CRC. [ALT]-[T] Buffer Toggle Any incoming text can be stored in the text buffer for future saving to disk or transmission. To open or close the buffer, press [ALT]-[T]. When the buffer is open, the cursor will change to a block and an "*" will appear on the top status line. When closed, the cursor will appear as an underscore. [ALT]-[V] Ultimaterm Version This is just a single window that serves no other purpose than to display the version of Ultimaterm that you are using. 20 [ALT]-[X] Transfer Files The "Transfer Files" section allows you to transmit or receive files using three different methods. Ultim too long to fit on the current disk, you will be told the file will not fit and the save will be halted. If the file saved is an ASCII File, you will be asked if you want to strip linefeeds during the save. If you reply yes, then any time a linefeed is encountered in the file, it will be ignored and won't make it to the file on disk. If the filename you wish to save under already exists on the disk, you will be told so and asked if you want to save the file anyway. "Directory" simply allows you to take a directory of the RSDOS disk or ramdrive (if 512K is present). It will also display the number of granules that are free. "Kill File" allows you to kill a file on the RSDOS disk or ramdrive (if 512K is present). It is the same as the KILL command under RSDOS. "Format Ramdisk" allows you to erase the contents of the ramdisk giving you 68 granules free. "Backup to Ramdisk" allows you to BACKUP from a floppy to the ramdisk to make file transfers go much faster. Of course, this will only work if 512K is present. "Backup to Floppy" allows you to do just the opposite of the previous. The disk you want to backup onto must be formatted in RSDOS or an error will occur. "Default Option Save" allows you to save all the changeable parameters of Ultimaterm onto disk. The parameters are saved onto track 17, sectors 17 and 18 where they are out of the way of regular RSDOS operation. "Default Option Load" allows you to load all the changeable parameters of Ultimaterm from disk. Although these parameters are loaded upon the initial execution of Ultimaterm, you may have changed a few of the parameters and would like to load the originals back. For this reason, I've provided "Default Option Load". 17 [ALT]-[E] Exit This command allows you a clean exit back to RSDOS to save you the trouble of pressing [ALT]-[CTRL]-[RESET] or turning your Coco 3 off and on. When you select EXIT, the ROMS are copied back to RAM and the reset vector is called to perform a warm start. [ALT]-[F] Freeze Screen For those of you who hate watching text scroll by you at 2400 baud with no means of stopping it temporarily, I've provided a screen freeze command that will halt screen display while still giving you all the [ALT]-[commands] at your fingertips. To enable text-to-screen again, simply press any key other than one of the [ALT]-[commands]. ** NOTE ** Only 3K of text will be buffered. When the buffer is full it will start to write over the text that has already been received. [ALT]-[H] Hang-up Modem This command will try to hang-up the modem in one of two ways. If you have an RS232 pak, the first thing that the modem tries is dropping DTR for a second and then raising it again. If a connection is still present, it tries the second method. The second method is the only method tried if you don't have the RS232 pak. The hang-up string (changeable from the Autodial Options) is sent to the modem. If none of these work, you can always unplug your modem from the wall or turn it off?! [ALT]-[I] Freeware Information This is the section that asks you to send me a donation for my efforts in bringing you Ultimaterm. Please remember that Ultimaterm is Freeware which means you are under no obligation to support any future efforts I might decide to bring to the CoCo 3 world... If you do decide to send some money, I will send you back a licensed copy of Ultimaterm with a printed copy of the manual. If anyone should send a donation to me and says they got it from "such and such"'s serialized copy (please include the serial number) then I will send them back 10% of your donation. ** NOTE ** The only copy of Ultimaterm that will appear on Delphi or CIS or any other major network will be '000000' to be fair to everyone else who has donated. 18 [ALT]-[K] Keyclick toggle Keyclick is simply a sound that is generated each time you press a key on the keyboard thatfer" simply resets all the buffer end pointers so that the buffer is cleared and ready for taking in new text or receiving new files across the modem. "Display Buffer" simply dumps the contents of the buffer in a straight list. You can pause the display by pressing any key and abort it by pressing [BREAK]. "Print Buffer" does the same as "Display Buffer" but directs the contents to the printer. "Buffer Status" shows you how much memory is used, how much is free, how many disk granules it will require to save the contents of the buffer and how many Xmodem and Ymodem blocks it will take to send the buffer. [ALT]-[C] Conference Mode Sometimes known as "Chat Mode", Ultimaterm's conference mode allows separate entry of text from the received text so that many people can hold a conference without incoming text splitting apart text you're trying to type. When you press [ALT]-[C] the Conference Mode window pops up which asks you how many lines you want to use for your personal text entry. Remember that the more lines you allocate for yourself, the fewer there will be to view received text on. You might want to limit yourself to using one or two lines at the most just to ensure you don't babble on! 15 After you select how many lines you would like for the conference mode, the screen will clear and a bar will split the lines you have to type in text (on the bottom of the screen) with the lines that received text will appear in. Each section of the screen will have it's own cursor. If you wish to capture the incoming text in your own buffer, press [ALT]-[T] to open the buffer. The cursor in the top section will turn from an underscore to a box and a "*" will appear on the top status line. While in conference mode all [ALT]-[key] options will be available to you with the exception of [ALT]-[A] (autodial), [ALT]-[C] (conference) and [ALT]-[Q] (VT Keypad toggle). To exit from conference mode, simple press [BREAK]. [ALT]-[D] Disk Commands Disk Commands provides you with a bit of control over disk files. Pressing [ALT]-[D] will bring up the following window: Disk Commands L Load from disk to buffer S Save buffer to disk D Directory K Kill File F Format Ramdisk R Backup to Ramdisk B Backup to Floppy F1 Default Option Save F2 Default Option Load "Load from disk to buffer" allows you to load any RSDOS file from an RSDOS disk into Ultimaterm's buffer. You can then send that file using one of the transfer methods. If the file being loaded is in ASCII format, you will be asked if you want to add linefeeds to the file while it's being loaded. If you answer yes, then any linefeeds in the file will be ignored and any carriage returns in the file will be complemented with a linefeed. "Save buffer to disk" allows you to save any file you've received (or loaded) into the buffer to an RSDOS formatted disk. When you select save you will first be asked for the filename to save the file under and then asked for the file type. The file types are as follows: File type appear as ------------------------ --------- ASCII File 1 A XX BASIC ASCII File 0 A XX BASIC Binary File 1 B XX Machine Language File 2 B XX Text Editor Source File 3 A XX 16 If the file saved is an ASCII File, and it is too long to fit on the current disk, you will be asked if you would like a multiple save performed. In a multiple save, the file is saved as much as can be on the current disk and then you will be prompted to insert another disk to continue saving the file (under the same name) on. If the file saved is any other type and it is the string that is sent to abort the current dial attempt and prepare for the next attempt. On Hayes compatibles, one simply pushes [ENTER] or [SPACE] and the dialing command is immediately aborted and the modem returned back to command mode. I use a hang-up string of just one carriage return (^M). The "Connect string" is used to identify the response the modem gives to indicate it has connected to the system being dialed. On Hayes compatibles, "CONNECT" will cover "CONNECT 300", "CONNECT 1200" and "CONNECT 2400". The "Busy strings" are used to identify the responses the modem gives to indicate it cannot make a connection and a redial should take place. I've squeezed room for four possible busy strings such as "BUSY", "NO CARRIER", "NO ANSWER" and "ERROR". 13 "carrier Method" is used to decide the best way to recognize that a successful connection has been made. If set to "String", then the "Connect string" and "Busy strings" will be used in autodialing. If set to "DCD", then the CD status of the RS232 pak will be monitored until a connection has been made. DCD is by far the most reliable but will only work if you have an RS232 pak AND DCD on your modem is set to active (or normal). When all the "Dialing Options" are set to work with your modem, you can use the "Default Option Save" available from the "Disk Commands" window (ALT-[D] from terminal mode) to permanently save them to disk. Dialing a number There are two ways to dial a number from the dialing directory. You can select [M]anual dial whereby you get to enter the phone number you wish to dial (basically for a once-only dial) or press [ENTER] or [SPACE] to dial the inverted entry. When the dialing process starts, you will be shown the "Autodialer" window which is basically for your own entertainment. It displays the number being dialed, the number of times it's been redialed, the countdown to the next dialing attempt, and the status of the last attempt. The "Autodialer" window also allows you quick changing of both the "Dial time" and the "Hang-up time" to quickly and easily adjust the autodialer to the fastest possible dialing attempts. The window also allows you to manually abort the current dial attempt and try again, to abort the dial attempt and exit from the dial window or to just exit from the dial window while leaving the number dialing away. The "Autodialer" window looks like this: Autodialer Dialing : 242-3515 Attempt # : 15 Countdown : 005 seconds Last attempt: Not connected [D]ial time : 020 seconds [H]ang-up : 002 seconds [SPACE] to restart [ENTER] to exit [BREAK] to abort and exit The phone number following "Dialing" will be displayed one digit at a time as the digit gets sent to the modem. The "Attempt #" counts down from the "Dial time" to zero, at which time it sends the abort string and redials the number; printing the words "Not connected" for the "Last attempt". If you're using the connect and busy strings, then "Last attempt" will also display "BUSY" or "NO ANSWER" or whatever busy string was received by the modem. 14 Before an autodial is started, the parameters for that selection are set and then initialized. If you have a switch on your modem that manually selects 300 or 1200 baud, you must set that switch to the baud rate you choose to call the system at before you can autodial the number. [ALT]-[B] Buffer Commands Buffer Commands gives you minimal control over a few buffer functions. Pressing [ALT]-[B] will give you the following menu: Buffer Commands C Clear Buffer D Display Buffer P Print Buffer S Buffer Status "Clear Bufhold voice numbers of friends. When the dialing directory is complete (or any time you make changes) you should use the "[S]-Save Directory" option to save the directory to disk (under the filename "ULTDIAL.DIR"). Should you wish to list the directory to your printer, you can use the "[P]-Print Directory" option which prints all fourty-five possible entries; even if they're blank. Before you can dial entries, you should first set the dialing prefix [^P] and dialing suffix [^S]. Just so you understand what the dialing 'fixes are, possible dialing prefixes for Hayes compatibles would be "ATDT" or "ATDP 9," while a possible dialing suffix for Hayes compatibles would be "[ENTER]". To slow down the sending of the dialing string to the modem, simply start the dialing prefix with a [^B] and a 1/4 second pause will be performed between each character. The next thing that needs to be done before an entry can be dialed successfully is the setting of the dialing directory options ([O]-Options). Pressing [O] will display the following screen: Dialing Options Dial time : 020 seconds Hang-up time : 002 seconds hang-up String: ue+++uuATH0 Abort String : Connect string: CONNECT Busy strings : BUSY : NO CARRIER : NO ANSWER : ERROR carrier Method: String A bit of explanation is in order for the "Dialing Options". To make it possible for Ultimaterm V4.0 to work with almost any smart modem, I had to make Ultimaterm a little smart itself. Most smart modems send messages to the terminal so that you can see what the modem detects on the phone line, whether it be a busy signal, or no dialtone, etc. Ultimaterm V4.0 will send the dialing prefix to the modem followed by the phone number selected (with no spaces, unless 12 you include them in the number or dialing 'fixes) and finished off with the dialing suffix. It then has to assume that the modem is dialing the number and will alert Ultimaterm to the modem's status. If Ultimaterm receives no response from the modem for the set length of the dialing time, it will send the abort string to hang-up the modem and then dial the phone number again. If a connection is made and the modem responds with the connect string or puts DCD on the RS232 pak low, Ultimaterm makes some noise and drops to terminal mode. The "Dial time" can be changed by pressing [D] and typing in a new time. "Dial time" is how long Ultimaterm will wait for a response from the modem before attempting the dial again. If you're going through many switchboards (i.e., long distance calls) you can lengthen the dial time. If you're calling a local number that rings right away, you might choose to shorten the dial time to get in more autodial attempts (and therefore a better chance at being the next caller on the system). The "Hang-up time" can be changed by pressing [H] and typing in a new time. "Hang-up time" is the length of time to wait after sending the abort string and before attempting to dial again. This is useful for making sure the modem is ready to accept the dialing string (preventing half the string from being ignored by the modem). The "hang-up String" is actually used by the ALT-[H] while in terminal mode and not by the dialing directory. The reason I chose to place the hang-up string here is these options are modem-specific options, while "Modem Options" are general settings. I use a hang-up string of "[^A][^B]+++[^A][^A]ATH0 [ENTER]" which sends a one-second pause (^A), sets the rest of the string to be sent at 1/4 second intervals (^B), sends +++ which returns my modem to the command state, pauses for 2 seconds (^A^A) to give the modem a chance to catch it's breath, and finally sends the hang-up command ATH0 followed by a carriage return (^M). The "Abort string" is d previous versions and asked for many of the features now available in Ultimaterm V4.0. Without all this support, I don't think I'd have put as much effort into bringing you version 4.0 as I have. Now that 4.0 is complete, I will take the time to respond to all those letters!? [ALT]-[A] Autodial This is the section everyone has been asking for (well, everyone with a smart modem that is). This section replaces both the Autodial and Redial found in V3.0 with a complete and proper dialing directory. If you're not sure what a dialing directory is, simply put; it's a list of System Names, phone numbers, and terminal parameters that allows you to select a specific system to call and have the terminal program automatically set the parameters for that system and redial until that system is online. (whew!). Anyone vaguely familiar with terminal programs like Telix or Procomm on the IBM will know that we've been lacking a very useful feature for too long. Creating a dialing directory The first thing that happens when you select ALT-[A] from terminal mode is Ultimaterm looks for the dialing directory in memory. If found, it will display the directory and allow you to enter or dial various systems. If not in memory, Ultimaterm looks on the current disk to see if the dialing directory is present (under the filename "ULTDIAL.DIR"). If not, it checks to see if there's enough room on the disk for the dialing directory (at least 2 granules) and asks you if you want to create the directory to that disk. 10 When the directory is finally loaded into memory, it will be displayed on the screen as follows: System Name (30chrs) Phone W P S Baud Term ========================= ================ = = = ===== ====== . (15 entries per screen * 3 screens) . ======================== ================ = = = ===== ====== The list of possible keypresses will be displayed along the bottom (too wide to display here, but I'll explain 'em!) and an inverted bar will be placed at the top of the entries on the screen. Cursor Movement You can move the inverted bar up and down through the entries on screen by using the up and down arrow keys. To move through the three possible screens that can contain fifteen entries each, use [SHIFT] with the up and down arrow keys. Adding or Changing an entry Move the inverted bar to the place you'd like to add or change an entry by using the cursor keys. Then press [C] to start changing that entry. The first window that pops up asks you to enter in the "System Name". If you're changing an entry, you can just press [ENTER] to leave the system name unchanged. The next window that pops up asks you to enter the phone number for the system. Just type in the phone number and NOT any dialing commands (like ATDT). If you're changing an entry, you can just press [ENTER] to leave the phone number unchanged. The next window asks for the word length, 7 or 8 bits. Press [ENTER] to leave it unchanged. The next window asks for parity - None, Odd, Even, Mark or Space. Again, press [ENTER] to leave it unchanged. The next window asks for stop bits - 1 or 2. As always, press [ENTER] to leave it unchanged. The next window asks for baud rate. Select the baud rate you call that system at or press [ENTER] to leave unchanged. 11 The last window asks for the terminal emulator you want to use when you call the system. Again, select the emulation or press [ENTER] to leave unchanged. You will then be taken back to the dialing directory screen in which the entry you just created or changed will be displayed. At this point, go ahead and start adding entries into the dialing directory. The entries do not have to be sequential in the list so you can use one screen for certain types of systems, another screen for other types of systems, or like I do; a screen to g if the buffer is opened or closed is by the "*" on the status line. VT-Keypad toggle allows for the CoCo 3's keyboard to emulate that of the appropriate VT emulation. When toggled on, a "%" appears on the top line and the certain keys on the keyboard behave differently than usual. They are as follows: SHIFT-@ Home Cursor Up Arrow Sends Cursor Up sequence Down Arrow Sends Cursor Down sequence Right Arrow Sends Cursor Right sequence Left Arrow Sends Cursor Left sequence CLEAR Sends Clear Screen sequence SHIFT-ENTER Sends Erase to End of Line sequence [ALT]-[0-9] Send Keypad Application Mode 0-9 sequences [ALT]-[-] Send Keypad Application Mode - (dash) sequence [ALT]-[,] Send Keypad Application Mode , (comma) sequence [ALT]-[.] Send Keypad Application Mode . (period) sequence [ALT]-[ENTER] Send Keypad Application Mode ENTER sequence [ALT]-[F1-F4] Send Programmable Function 4 sequence 8 NOTE: F3 and F4 are SHIFT-F1 and SHIFT-F2 respectively If you have no idea what the VT-Keypad is for, keep it off (make sure the "%" isn't on the top line by pressing [ALT]-[Q]). Saving all the default options ------------------------------ At this point you have just set all the options you need set upon each loading of Ultimaterm. Next step is to save all these default options to disk. This can be accomplished by pressing [ALT]-[D] from terminal mode to pull up the "Disk Commands" menu and then pressing [F1] to save all the parameters to disk. If you're wondering where the parameters are being saved, they take up two sectors on the disk - Track 17, Sector 17 and Track 17, Sector 18 - hidden behind the disk directory in two unused RSDOS sectors. I'll discuss all the features on the "Disk Commands" menu a bit later in the manual. For now, you're free to roam around Ultimaterm and use the rest of the manual as a reference should you need any further explanation on any commands. Ultimaterm Commands ------------------- When you load up Ultimaterm, you'll find yourself in terminal mode. To pop up one of the many windows that allow you some control over Ultimaterm, simply push the [ALT] key with one other key. In order to see what all the [ALT] key combinations are, press [ALT] in conjunction with the [/] and a command summary window will be displayed on your screen. Actually, this is just one of two command summary windows which are displayed. To see the second command summary window, press any key other than [BREAK]. [ALT]-[@] Credits I alone can not take credit for what Ultimaterm V4.0 has become over the past 3 months. In an effort to list some of the people who have made significant contributions to Ultimaterm V4.0, I have created this credit section. Fred McDonald has kept me in touch with Delphi so that I could see what people wanted from Ultimaterm V4.0. Rex Hebert provided me with the source for a CRC calculation which I used in V3.0. While making every attempt to improve upon various subroutines which I considered too slow in Ultimaterm, I wrote a new CRC calculator from the original which I'll provide further on in the manual. 9 Laverne Kelly has become my official voice to keep me in touch with Delphi officials and has also done much beta-testing to make sure V4.0 will stand bug-free for a long time. Jeff Mercer sent me a complete list of VT52 and VT100 control codes which made it possible to write support for these two terminal emulations. Guy Loucks provided me with the VT52 and VT100 keyboard control sequences and also helped me test the VT emulators out on his account on a local VAX. Dan Damron was the first to lay eyes on Ultimaterm and spent much of his own time helping me prepare this manual. I received many, many letters over that last three months (a few even had donations!) of people who were impressed with Ultimaterm V3.0 and [CLEAR] to clear this string should you not have a smart modem. Sorry this string could not be longer, but you can use the keyboard string to send a couple of [ALT]-[#] keys to set up more complex modem strings. When the Intialization strings are set to your needs, press [BREAK] to return to the "Set Options" menu. 6 [Z] Miscellaneous Options -------------------------- This is probably the most important option you need to look at before you can really do anything with V4.0 as it allows you to designate which slots of your multi-pak (if you're using one!) you keep your drive controller and RS232 pak in. The window looks like this: Miscellaneous Options D Repeat delay time ....016 R Repeat speed .........128 T Keyclick tone ........032 S Sound .................On B Destructible BS ......Yes Y RS232 Pak slot .........1 Z Disk drive slot ........4 "Repeat delay time" is the length of time you have to hold down a key before it starts to repeat. Just increase or decrease this value to your liking. "Repeat speed" is how fast the key will repeat. Increase or decrease this value to your liking. "Keyclick tone" is the tone of the keyclick (if you have the keyclick turned on and the sound turned on). "Sound" allows you to silence any noise Ultimaterm makes. "Destructible BS" allows you to change the conditions under which a backspace will be performed. If set to "Yes", then whenever a backspace is received, the character over which you're backspacing will be erased. If set to "No", then the cursor will just move back over the previous character without destroying it. "RS232 Pak slot" allows you to select which slot in your Multi- Pak you have the RS232 pak in. Please do not neglect this (unless you don't have the RS232 Pak or Multi-Pak!) as the Receiver Interrupt can only be enabled if Ultimaterm knows what slot the pak is in. Otherwise received characters will not cause an interrupt condition and will be ignored by Ultimaterm. "Disk drive slot" allows you to select which slot in your Multi- Pak you have the disk controller in. Please do not neglect this one either (unless you don't have a Multi-Pak) as it enables the CTS line to the drive controller. When you have finished with the "Miscellaneous Options" press [BREAK] twice to return to terminal mode. 7 Other Ultimaterm Parameters Now it'd be wise to set up the miscellaneous settings on Ultimaterm V4.0 before we save the defaults to disk. The miscellaneous settings include the Mono/Comp toggle ([ALT]-[M]), Screen position ([ALT]-[<] and [ALT]-[>]), Keyclick ([ALT]-[K]), Upper/Lowercase (SHIFT-0), Buffer Opened/Closed ([ALT]-[T]), and VT- Keypad toggle ([ALT]-[Q]). The Mono/Comp toggle selects the screen between color and B&W and also will enable or disable the colorburst signal. Set [ALT]-[M] according to what's most readable on your display. Screen position uses the Vertical Fine Scroll register designed for doing a smooth scroll to adjust the display up or down the screen. This should be most useful to those who have to constantly adjust the horizontal on their monitors to get the best centering possible. Keyclick just enables or disables keyclick. Keyclick can be over-ridden by the "Sound" option in "Miscellaneous Options". Upper/Lower case really needs no explanation, except for pointing out that when upper-case is selected, a "#" appears on the top status line. Buffer Opened/Closed simply opens or closes the door to the input buffer. When OPENed, the cursor will change to a block and an "*" will appear on the top line. When closed, the cursor is an underscore. NOTE: Since VT-100 or VT-52 terminal emulation can alter the state of the cursor, the only sure-fire way of knowine set all the "Modem Options" to your liking, press [BREAK] once to return to the "Set Options" window. 4 [P] Printer Options -------------------- There are three printer options in V4.0. The window will look like this: Printer Options B Printer Baud Rate ...9600 L Printer Linefeeds .....No D Printer Line Delay ...000 These are changed exactly like the "Modem Options" were. "Printer Line Delay" might come in handy for anyone with an older printer. All it does is cause a set delay to occur at the end of each line to the printer. When the "Printer Options" are set to your taste, press [BREAK] once to return to the "Set Options" window. [K] Programmable Key Set ------------------------- This section took a major overhaul when I went through V3.0 fixing up all that needed fixing. You should find much power to the user has been added to this section. Though getting used to pressing [ENTER] and not [BREAK] to exit from entering a macro will take some time. The keys [0] through [9] can be changed to hold any name, alias, password, etc. that you want to send across the modem with one keystroke. You can send any control character in the programmable key by using the [CTRL] key. If you make a mistake while entering the keystroke, you can just use the [Left Arrow] key to backup and fix that mistake. To add the [ENTER] key as part of the keystroke, use [^M]; to add the [BREAK] key, use [^C] and to add the [Left Arrow] use [^H]. Press [CLEAR] to clear the programmable key, press [BREAK] to leave the key unchanged, or press [ENTER] to accept the key as is. There are two special CTRL key combinations that can be used in conjunction with ALT-[0] through ALT-[9]. They are [^A] and [^B] and perform time functions during key transmissions. [^A] in the key causes a single, one-second pause before the next character in the string is processed. [^B] in the key causes all following characters (up to the next [^B]) to be sent at 1/4 second intervals. This is most useful for PBBSes which don't accept programmable keys at full speed. 5 The 'F' keys serve a slightly different purpose. Ultimaterm V4.0 was designed with a keyboard buffer in mind to add much power to window control. The 'F' keys are programmable keyboard strings. When you first load V4.0, you'll notice that the keys are set to [ALT]- [X];X, [ALT]-[X];Y, [ALT]-[X];S and [ALT]-[X];U. (In any of the options, any letter that is underlined means it's an ALT-letter). From terminal mode, you can press [ALT]-[F1] and [ALT]-[X];X will be entered into the keyboard input buffer which will take you immediately to Xmodem Receive. The remaining ALT-[F's] are set to Ymodem Receive, Xmodem Send and Ymodem Send. After playing around with V4.0 for a while, you can set these keys up to do whatever you prefer. When all the programmable keys are to your satisfaction, press [BREAK] once to return to the "Set Options" window. [I] Initialization Strings --------------------------- Remember that "Initializing the keyboard and modem strings" window that popped up when you first loaded Ultimaterm? Well, this is where you get to set the Keyboard and Modem strings for your own needs. The [K]eyboard string is just like one of the [ALT]-[F keys] mentioned in the "Programmable Key Set" section but it is executed when Ultimaterm first loads up and is only executed once. It's basically my version of a safety net that will allow you to set up some parameter I may have overlooked; but most people will find it more useful to execute some command (like dial a phone number) whenever they load up V4.0. The [M]odem string is just like one of the [ALT]-[0] through [ALT]-[9] keys that gets sent to the modem. Currently, it sends "ATZ [ENTER]", a 2 second pause, "ATS0=0 L0 V1 X4 [ENTER]" to set up some initial parameters on your modem. You can just press [M] anible disk error which could cause you to loose files you just spent much time downloading. "Stepping rate" just allows you to set the stepping rate at which the DSKCON routine will execute STEP commands.. Most drives will handle the 6 ms rate but if you're not sure just experiment with them to find the fastest your drives will handle. "Double sided drives" allows you to switch the drive select masks of Ultimaterm V4.0 between 4 single sided drives and 2 double sided drives. After you have set all the "Disk Options" to your liking, press [BREAK] once to return to the "Set Options" screen. [M] Modem Options ------------------ Press [M] to pop up the "Modem Options" window. The following will appear on your screen: Modem Options B Baud Rate ...........1200 W Word Length ............8 P Parity ..............None S Stop bits ..............1 D Duplex ..............Full L Linefeeds ............Yes A Auto-Buffer ...........No T Terminal Type .......ANSI R Deluxe RS232 Pak .....Yes F Linefeed Filter .......On I'll assume I don't have to explain what "Baud Rate" is or "Parity", etc. However, I will explain some of the not-so-obvious options and will also explain how to change the options. 3 There are two ways to change any of the above options. Either pressing the designated key will automatically switch that option between one of two states, or pressing the designated key will hi- light that option and allow you to sequence through all choices with the left and right arrow keys. When the right choice is selected, press [ENTER] to accept the change or [BREAK] to leave it like it was. NOTE: If in monochrome mode (via the [ALT]-[M] option from terminal mode) the option won't be hi-lighted but will be underlined instead. There are three duplex settings: Full, Half and Echo. When in FULL, any keys you press in terminal mode will be sent to the modem and any keys received will be sent to the screen. When in HALF, keys you press will also be sent to the screen. When in ECHO, characters received from the modem will be echoed back to the modem and any keys you press will be sent to the screen. When setting the baud rates, you should keep a few things in mind... If you're using the RS232 pak, all baud rates can be selected with the exception of 450 baud. If you're using the serial port, all baud rates between 450 baud and 2400 baud can be selected (i.e, 450, 50, 75..300, 600...2400). I'm pretty sure 2400 baud through the serial port is reliable for standard communicating considering I sent a 100 block YMODEM file (yes, that's 'Y') using a null-modem cable at 2400 baud with no errors; but a LOT of time goes to interrupt processing and the machine slows down noticeably. "Autobuffer" is a feature which is very useful for downloading text files from a BBS. When the system you're connected to sends a CHR$(18) (aka DC2), Ultimaterm will open it's receiving buffer. When the system you're connected to sends a CHR$(20) (aka DC4), Ultimaterm will close it's receiving buffer. This feature can be turned on or off with this Autobuffer toggle. "Terminal Type" switches Ultimaterm's screen driver to act as one of four different types of terminals. The system you are calling should let you know what type (if any) of terminal you should set Ultimaterm to. A more thorough explanation of the terminal types and their control codes will be explained further on in this manual. If the system you are connected to doesn't support any control sequences, just set "Terminal Type" to TTY (Teletype) which acts as a dumb terminal. "Deluxe RS232 Pak" can only be kept at "Yes" if you have a Deluxe RS232 Pak present. If you do have a pak and want to use the serial port for any reason, this is where you can switch over. After you havnks in 6809 be expected to write in English? I 'spose this is why software authors are hardly ever the ones to document their software, unless it's just a simple program that just needs a bit of explaining. I'll try to keep in mind that I'm not writing a novel here and explain things as precisely and simply as possible. I'll even make an effort to include original sources of my information so as anyone who actually will read this manual can have a reference should I be unclear. Just so we're thinking on the same wavelength, I'll designate control key combinations by preceding the key with a caret (^) and designate alternate key combinations by using the sequence [ALT]- [key]. One last thing I should mention here. Many things about Ultimaterm V4.0 won't be readily apparent just by using the terminal (as I tried to make Ultimaterm V3.0). I suggest that even if you don't read through manuals (like me?!) you glance through a few sections just to pick up on some tips I might leave lying around... Ken Johnston 1 GETTING STARTED WITH ULTIMATERM V4.0 I wouldn't strongly suggest you just LOADM and EXEC Ultimaterm V4.0 without reading at least this first section. One of the major considerations I kept in mind while writing V4.0 was the fact that every system is not the same. Especially these days now that everyone has become more confident in making hardware mods due to lower repair or replacement costs. The first thing you'll have to do is LOADM and EXEC Ultimaterm V4.0. You should notice two things above V3.0: First, it'll take longer to load (wonder why?!) and second, when it is loaded, you'll see a window that states "Initializing the keyboard and modem strings". A second or two later, that window disappears and the version window pops up that simply states "Ultimaterm V4.0". Hit any key to drop to terminal mode. The Initial Setup ----------------- Before you go off playing with all the new ALT keys, you'd best take the time to customize this version to your system. First, press [ALT]-[M] to toggle the display between monochrome and composite (not really necessary if you're using an RGB display). Second, use [ALT]- [<] and [ALT[-[>] to move the screen up or down on your monitor to center it as best as possible. If keyclick annoys you, press [ALT]- [K] to shut keyclick off (press it again to turn it back on). Press [ALT]-[O] to pop up the "Options Menu". If you had Ultimaterm V3.0, you'll probably immediately notice the addition of two new options: "Initialization Strings" and "Miscellaneous Options". [D] Disk Options ----------------- The first step will be setting up the disk options. Simply press [D] and the following window will pop up: Disk Options D Default Drive ..........0 E Default Extension ....BIN A Auto Clear ...........Yes V Verify ...............Off S Stepping rate ......30 ms B Double sided drives ...No 2 "Default Drive" and "Default Extension" are both used for the window that asks for a filename. To set the default drive, press [D] and use the left and right arrow keys to rotate through available choices. To set the default extension, press [E] and type in the new extension. "Auto Clear" is simply a flag that indicates if the buffer should be cleared automatically before LOADing a file from disk. It also decides if the buffer should be cleared upon receiving a file from across the modem. Press [A] to toggle Autoclear on or off. "Verify" is the same as the VERIFY ON/OFF command under RSDOS. If on, then any sector written to the disk will be reread for verification purposes. This slows down disk output (especially during an X or Ymodem transfer), but greatly improves the chances of catching a poss "carrier Method" ................... page 14 Saving Dialing Options ............. page 14 Dialing a number ........................ page 14 [ALT]-[B] Buffer Commands ................... page 15 "Clear Buffer" .......................... page 15 "Display Buffer" ........................ page 15 "Print Buffer" .......................... page 15 "Buffer Status" ......................... page 15 [ALT]-[C] Conference Mode ................... page 15 [ALT]-[D] Disk Commands ..................... page 16 "Load from disk to buffer" .............. page 16 Adding LF's to a load .............. page 16 "Save buffer to disk" ................... page 16 File types ......................... page 16 Files to big for one disk .......... page 17 Stripping LF's during a save ....... page 17 "Directory" ............................. page 17 "Kill File" ............................. page 17 "Format Ramdisk" ........................ page 17 "Backup to Ramdisk" ..................... page 17 "Backup to Floppy" ...................... page 17 "Default Option Save" ................... page 17 "Default Option Load" ................... page 17 [ALT]-[E] Exit .............................. page 18 [ALT]-[F] Freeze Screen ..................... page 18 [ALT]-[H] Hang-up Modem ..................... page 18 [ALT]-[I] Freeware Information .............. page 18 [ALT]-[K] Keyclick toggle ................... page 19 [ALT]-[M] Monochrome/Composite toggle ....... page 19 [ALT]-[O] Set Options ....................... page 19 [ALT]-[P] Print Screen ...................... page 19 [ALT]-[Q] VT-Keypad toggle .................. page 19 VT-100 or ANSI emulation ................ page 19 VT-52 emulation ......................... page 20 [ALT]-[S] Buffer Checksum ................... page 20 [ALT]-[T] Buffer Toggle ..................... page 20 [ALT]-[V] Ultimaterm Version ................ page 20 [ALT]-[X] Transfer Files .................... page 21 "Transmit Buffer" ....................... page 21 "Receive Buffer" ........................ page 21 Transfers to disk or buffer ............. page 21 Scanning a filename ..................... page 21 "Xmodem Send" ........................... page 22 "Ymodem Send" ........................... page 22 "Xmodem Receive" ........................ page 22 "Ymodem Receive" ........................ page 22 Receiving to disk ....................... page 22 Transmitting from disk .................. page 22 Starting Xmodem receive with CRC ........ page 22 Aborting a transmission ................. page 22 Disk Full ERROR on receive to disk ...... page 22 CRC Option .............................. page 23 Sample calculation under 'C' ....... page 23 Sample calculation under assembly .. page 24 Ultimaterm Clock files ............................ page 25 Ultimaterm's Keyboard ............................. page 26 Screen Control .................................... page 26 DEC VT-52 Control Codes ...................... page 27 DEC VT-52 Keyboard controls .................. page 28 DEC VT-100 Control Codes ..................... page 29 DEC VT-100 Keyboard controls ................. page 30 ANSI-BBS Control Codes ....................... page 31 Vidtex Control Codes ......................... page 32 PREFACE Ughh.. Documentation. How can one who thi ULTIMATERM VERSION 4.0 Documentation Manual Ultimaterm V4.0 written by Ken Johnston Documentation written by Ken Johnston Freeware - March 1988 Voice : (403) 242-3485 MST Modem (DIGITS) : (403) 242-3515 300/1200 baud Table of Contents ----------------- Preface ........................................... page 01 Getting Started with Ultimaterm V4.0 .............. page 02 The Initial Setup ................................. page 02 Disk Options ................................. page 02 "Default Drive" ......................... page 03 "Default Extension" ..................... page 03 "Auto Clear" ............................ page 03 "Verify" ................................ page 03 "Stepping Rate" ......................... page 03 "Double Sided Drives" ................... page 03 Modem Options ................................ page 03 Duplex settings ......................... page 04 Baud rates .............................. page 04 "Autobuffer" ............................ page 04 "Terminal Type" ......................... page 04 "Deluxe RS232 Pak" ...................... page 04 Printer Options .............................. page 05 "Printer Line Delay" .................... page 05 Programmable Key Set ......................... page 05 Keys [0] through [9] .................... page 05 One second pause in key ............ page 05 Quarter second delay between keys .. page 05 [F-keys] ................................ page 06 Initialization Strings ....................... page 06 Keyboard String ......................... page 06 Modem String ............................ page 06 Miscellaneous Options ........................ page 07 "Repeat delay time" ..................... page 07 "Repeat speed" .......................... page 07 "Keyclick tone" ......................... page 07 "Sound" ................................. page 07 "Destructable BS" ....................... page 07 "RS232 Pak slot" ........................ page 07 "Disk drive slot" ....................... page 07 Other Ultimaterm Parameters .................. page 08 Mono/Comp toggle ........................ page 08 Screen positioning ...................... page 08 Keyclick toggle ......................... page 08 Upper/Lowercase toggle .................. page 08 Buffer opened/closed toggle ............. page 08 VT-Keypad toggle ........................ page 08 Saving all the default options ............... page 09 Ultimaterm Commands ............................... page 09 [ALT]-[@] Credits ........................... page 09 [ALT]-[A] Autodial .......................... page 10 Creating a dialing directory ............ page 10 Cursor Movement ......................... page 11 Adding or Changing an entry ............. page 11 Dialing Options ......................... page 12 Dialing Prefix and Suffix .......... page 12 "Dial time" ........................ page 13 "Hang-up time" ..................... page 13 "hang-up String" ................... page 13 "Abort string" ..................... page 13 "Connect string" ................... page 13 "Busy strings" ..................... page 13 Table of Contents ================= Purchase of DIGITS............1 GETTING STARTED...............1 Stepping Rate...............1 Double Sided Drives.........1 Clock Selected..............2 Clock Set Routine...........2 Number of users.............2 Drive designators...........3 System Variables............3 Data files..................3 USR calls...................4 Detecting Carrier...........4 Hanging up the modem........4 SETUP.........................5 File Creation...............6 RUNNING DIGITS................6 Takedown....................7 Examine Users' Info.........7 List all accounts.........7 New Accounts..............7 Individual Accounts.......7 Terminal Mode...............8 The Message Base............8 ML ROUTINES...................9 ANSI.BIN....................9 CLOCK?.BIN..................9 K-REM2.BIN..................9 PARAM....................10 UPPER....................11 UPLOW....................11 RESTORE xxxx.............11 CHAT.....................11 SCAN$....................12 Filter...................12 RAMDRIVE.BIN...............12 MBASE.BIN..................12 XMODEM.BIN.................14 DIGITS BASIC programs........15 Lines 0-299................15 Lines 300-399..............15 Lines 400-499..............15 Lines 500-599..............15 Lines 600-699..............15 Lines 700-749..............16 Lines 750-799..............16 Lines 800-899..............16 Lines 900-949..............16 Lines 950-999..............16 Lines 1000-1099............16 Lines 1100-1199............17 Lines 1200-1299............17 Lines 1300-1339............17 Lines 1340-1399............17 Lines 1400-1499............17 Lines 1500-................18 BBS Errors...................19 Forseen Problems.............20 FINALE.......................22 Purchase of DIGITS ------------------ Thank you for purchasing DIGITS! As a surprise bonus, I'm including a licensed copy of Ultimaterm V4.0 which you'll be able to place in your download section and hopefully make a bit of money off to help compensate for the cost of the BBS. The first part of this tutorial will describe how to get DIGITS up and running on your system. There will also be some description of the ML routines and beyond that; an explanation of some of the BASIC subroutines. I have also included some information on what to do for a few foreseen problems.                                                                                                                                                                                                                                                                 :    !"#$%&'()*+,-./0123456789─;<=>?╞├   AL BAS@                                                                                                                                                                SYSOP MAN  UMANUAL TXT MANUAL BAS@Б                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 GETTING STARTED The first step is to format four or five diskettes and make at least TWO backups of the disk you received in the mail. Take one of the backups and keep it in a safe place so you can start from scratch in case something goes awry. Take the other disk and we'll get ready to customize DIGITS to your hardware. Load the program called "*.BAS". This is the initial boot routine that sets up the ML subroutines and copies all system files to the ramdrive. Take a look at lines 50 through 160. You'll see a few POKEs for DOS 1.0 and DOS 1.1. For the following steps, change the lines corresponding to whatever DOS you are using. Stepping Rate ------------- Line 70 (DOS 1.0) and line 140 (DOS 1.1) have POKEs that set up the stepping rate. Values to POKE are as follows: First POKE Second POKE Stepping Rate ---------- ----------- ------------- &H00 &H14 6 ms &H01 &H15 12 ms &H02 &H16 20 ms &H03 &H17 30 ms Standard RS-DOS comes with these POKEd for 30ms. I suggest you keep them this way if you have the old grey drives. Most other drives you can speed up to 6ms which makes the heads much more quiet. Double Sided Drives ------------------- Line 80 (DOS 1.0) and line 150 (DOS 1.1) have POKEs that set up the drive masks for double sided drives. If you are using two double sided drives you can keep these POKEs the way they are; making drive 2 the second side of drive 0 and drive 3 the second side of drive 1. 1 If you are unfamiliar with drive selecting, leave the POKEs the way they are if you have double sided drives and remove them if you have single sided drives. First Poke: drive select for drive 2 Second Poke: drive select for drive 3 POKE Drive ---- --------------------------------- &H03 Select third single sided drive &H40 Select fourth single sided drive &H41 Select second side of drive 0 &H42 Select second side of drive 1 Clock Selected -------------- Another important line to change is line 210. As it comes, it says LOADM"Clock1":EXEC. Change "Clock1" to one of the following clock routines you wish to use: Clock1 - Speech Systems Real Time Clock (RTC) Clock2 - Disto CRC Real Time Clock Clock3 - Software clock Now you can SAVE"*.BAS" back onto the disk and LOAD"*.BBS" to make changes to the second portion of the boot process. "*.BBS" is the second program in the boot which POKEs initial values into a small block of RAM and sets up some variables and USR functions used by the BBS. Clock Set Routine ----------------- Lines 50 through 170 set the software clock. If you are going to use a hardware clock type DEL 50-170 to remove these lines. Number of users --------------- Lines 210 and 220 are the LSB and MSB of the number of user accounts there will be on the board. I've found that 200 accounts is plenty. Depending on how many callers you are expecting, you may want to increase or decrease this value. Line 230 is the number of messages there will be in the message base. You can change this value depending on how active you think your message base might be. I find 120 messages is plenty. 2 What you must remember is that you only have 65 grans to split between messages and user accounts. Each message takes up 1056 bytes of disk space and each account takes up 80 bytes of disk space. One other note about user files is that an extra account is added on for the 'public user'. Therefore, if you select 150 accounts, 151 accounts will be created. Drive designators ----------------- Line 280 designates which of your drives will be reserved for the message base. I suggest you keep it on drive 0 as that is the drive all files are backed up onto so you may as well keep all data files on the same disk. It'll also free up the rest of the disks for file transers. However, if you want to use all 68 grans of disk space for messages, you might decide to put the message base on a seperate disk; which also gives you MUCH more room for user accounts. Lines 290 through 310 designate which drives are free for file up/downloading to. I have it set now for area one on drive 1, area two on drive 2 and area three on drive 3. Line 330 designates which drive the system will run out of. I suggest you keep the system in a ramdrive as that's the fastest place for file access. I also suggest you keep it in drive 4 as I have the file section using drive 5 for sending/receiving files as quickly as possible. Line 340 designates which drive the games will run out of. If you plan on a theme BBS with a few games, you might choose to have all your games on a seperate drive. This POKE allows you to accomplish that task very easily. System Variables ---------------- The rest of the POKES in "*.BBS" are variables the BBS uses to pass parameters back and forth between programs. These are all cleared to '0' to keep strange things from happening to the system. Data files ---------- Lines 530 to 600 copy the user files and system files from the data disk into the ramdrive to speed up operations. You'll be told how to create these files very shortly. 3 USR calls --------- Lines 610 through 650 set up 3 of the 10 user functions for system use. They simply allow the passing of variables between ML subroutines and BASIC. Lines 660 through 770 set the password required by the system if the password protection is on (explained a bit later) when the BBS drops down to the BASIC "OK" prompt. Line 790 just sets the default drive to point to where the system files are and then runs the logon procedure. At this point, you have customized the second portion of the boot routine so you can SAVE "*.BBS" back to the disk. Detecting Carrier ----------------- DIGITS currently scans bit 5 of the Status Register in the RS232 pak for carrier detect (line 1120 of "Logon.BBS"). I suggest you keep DCD on your modem active (or normal; depending on what the manufacturer calls it). When bit 5 gets set to logical 0, a caller has just connected and DIGITS proceeds to ask for the calling baud rate. You might choose to keep DCD forced active and then watch for a "CONNECT" or "CONNECT 1200" string. If this is the case, you must also be able to turn the modem ECHO off. Hanging up the modem -------------------- Probably the toughest part of setting up DIGITS will be how you hang up the modem. The easiest way around this is setting DTR on your modem to active (or normal; depending on what the manufacturer calls it). Currently, DIGITS trys to hang up the modem by dropping DTR for approximately one second and then raising DTR to allow the modem to answer the next call. If this doesn't work with your modem, you can play around with lines 370-390 of "Logon.BBS" and lines 250-270 of "Logoff.BBS" to find the best way to disconnect the present user. Some methods you might try include sending disconnect strings (such as "+++") or connecting the phone line to the cassette motor and using MOTOROFF / MOTORON. *** NOW do a cold start and LOAD "SETUP" *** 4 SETUP ----- IMPORTANT: Before RUNning SETUP, reserve some file space by entering FILES3,1150. "SETUP" creates the user files and the message base so that the BBS can run. When you RUN "SETUP" your screen will be cleared and you'll see a message that states not to run this program unless you've done a cold start. This is just to make sure no ML routines are present (like the RAMDRIVE, or K-REM2). When RUN, the ML file "K-Rem2.BIN" is loaded to take advantage of two ML subroutines. The first one converts all text to uppercase while the second one converts text to an upper/lowercase combination. First you will be asked how many accounts you want to create for users. This will be the number you decided on above. Since I found 200 to be plenty, I'd enter 200 at the prompt. You can enter the number you used above. Next you will be asked how many messages to put in the message base. Again, use the number you decided upon from above. In my example, I'd use 120. After you select the amount, the screen will clear and you'll be asked to insert a blank disk and press [ENTER]. This disk is the one that all the user files will be created onto. When you press enter, you will be prompted to create the Sysop account. This will be your initial account and will save you the trouble of trying to patch in your sysop access level (which can only be done by a Sysop!). First, enter the name you plan to use as Sysop. I left no room for aliases in any of the user accounts so at this point enter in your name. Second, you are asked for your password. Use anything up to 12 characters. Next, you are asked for your phone number. To make it easy programming-wise, I didn't bother to include any formatting routines in SETUP. Enter your phone number with no spaces, brackets, dashes, etc.. Also, include your area code. The phone number (403)242-3515 should be entered as 4032423515. Don't worry about making a mistake as you can change any field once you are properly in the BBS. Finally, you are asked for where you are calling from. Just answer with your city, province (or state). Eg., Calgary, Alberta. 5 File Creation ------------- At this point, the files will start to be created to the blank disk. First, 'Namelist.DAT' is created with the number of user accounts you selected (plus on public account). Then, 'Userlist.DAT' gets created with the number of user accounts you selected (plus one public account). Third, 'Last50.DAT' is created with 50 records. Then 'BBSlist.DAT' is created with 50 records to hold the names/numbers of 50 other bulletin board systems (local or long distance). On the BOOT disk, I've included my "BBSlist.DAT" file which contains the numbers of various CoCo BBSes across North America. Lastly, the 'Messages.DAT' file is created. When the process is finished you'll see that familiar 'OK' prompt of BASIC's. At this point, I suggest you make backups of your customized boot disk and the freshly created data files. RUNNING DIGITS -------------- Now that you've got all files set up, all that's left is booting the BBS up for running. ** DO ANOTHER COLD START ** From now on, all you need to do to run the BBS is as follows: 1) Place your customized boot disk in drive 0 2) RUN "*" 3) Enter in the current date and time (if using a software clock) 4) Wait for the "Insert proper diskette and press a key" prompt 5) Remove the boot disk 6) Place the data disk in drive 0 7) Place any file disks in the other drives. 8) Press a key If all is done properly, and all works, then the BBS will have booted up and will be waiting for a caller. As the sysop, you can log into the board from the keyboard by simply pressing [ENTER] and entering in your name and password. Once you log into DIGITS you should see your name, computer type, calling from, phone number, ID number and level on the top two status lines. You should also see the current time constantly in the upper right corner and the logoff time just below that. Level should say "Sysop" and ID should be 001. When you get to the Main Menu, press [?] to list out the menu. You should see three choices in the menu that only you as Sysop can see: (1) Takedown, (2) Examine Users' Info and (3) Terminal Mode. 6 Takedown -------- This feature is mainly for when you are calling the BBS from a remote location. It allows you to take the BBS down to perform any maintenance on the system. It also disables the password protection to save you the hassle of entering in a password each time you want to take the BBS down. You might find it wise to keep the password protection enabled to ensure no-one can get into your account and get to BASIC to DSKINI or whatever. Examine Users' Info ------------------- This is the section you will use most for your Sysop functions. It allows you to view user accounts, change levels, and delete accounts. You might also want to add some password protection to this section. In this section you can choose either (L)ist all accounts, list (N)ew accounts or view (I)ndividual Accounts. List all accounts ----------------- This simply does a straight dump of the account info for you to do user verification and whatnot. The info listed is the user ID, name, phone number, password, computer type, level, and times on the system. Your account will not be included in the list. New Accounts ------------ This goes through all the user accounts and searches for users who have levels below 10. New users are given an initial level of 5 to allow them access to most of the BBS. You can use (I)ndividual accounts to raise a members level to 10 or above to keep them from being continually scanned by the (N)ew accounts. Individual Accounts ------------------- This section allows you to scan through the user files one account at a time. First you are asked for the ID or name of the user you wish to look at. If you enter '1', or your name, you can look at your account. The account information displayed is as follows: 7 User Name: Ken Johnston Password : PASSWORD Phone : (403) 242-3515 Computer : CoCo (1,2, or 3) From : Calgary, Alberta Columns : 80 Level : 255 Times on : 1 ID No : 1 Last on : Jan 1 (L)evel (D)elete (N)ext (Q)uit ) LEVEL- allows you to change that user's level DELETE- allows you to delete that user NEXT- displays the next sequential user QUIT- returns to the Examine Info menu Terminal Mode ------------- The terminal mode is accessed both by (3) from the Main Menu or pressing (CLEAR) when the BBS is in Login waiting for the next caller. Terminal mode is used to give you a somewhat featured terminal program using what's available with the DIGITS software. It allows you to perform file transfers via X or Ymodem, as well as having the full ANSI screen driver. The menu in this section is pretty self explanatory. (M)ain Menu returns you to the Main Menu if that's where you called the terminal from. (L)ogin returns to the login to wait for the next caller. The Message Base ---------------- When you select (M) from the Main Menu, it will take you to the message base. The first time you enter the message base, you will see "Message range from 1 to 1", "'Your' flag is off" and "Enter a ? for help". Since there is no message '0', you will be at message '1' which should have the word "(deleted)" above it. The reason for the "deleted" is simply because when the message base is created, it is created with records who are flagged as deleted and ready for holding a new message. At the prompt, press the [?] key. You will see before you the menu that controls the message base. The first two options will be available only to you and are (Z) for Sysop message and (A) for Advertisement. 8 If you press [Z] at the prompt, you will be asked to enter in your message which will become the message displayed to all users when they log into the BBS. You might choose to take the time right now and enter in some sort of welcome message. If you press [A] at the prompt, you will be asked to enter in your message which will become the message displayed when a member selects [A]dvertisement at the Main Menu. This advertisement has a variety of uses, of which you might choose to enter in information about your system, or something that someone has for sale.. ML ROUTINES =========== Now I'll try to explain the machine language routines and some commands and switches they provide. There are nine machine language files on the boot disk of which five are LOADMed and EXECed just once and two are copied into the ramdrive to be EXECed only when needed. The five routines that are EXECed just once are "ANSI.BIN", "Clock?.BIN", "K-Rem2.BIN", "Repeat.BIN" and "RamDrive.BIN". ANSI.BIN This is an ANSI driver for Super Extended Color BASIC that makes a few changes to the screen driver routine. The changes include shortening some wasteful code, increasing the screen size to 80*28, and allowing for ANSI control sequences to alter cursor position and character attributes. Since ANSI uses only an 80*25 screen, the top three lines of the display are used for status lines. A modified HPRINT command will print text in these lines which are otherwise protected from the rest of the screen. The syntax for the new HPRINT is the same as that of the old, except for the row being limited from 0 to 2. CLOCK?.BIN There are three CLOCK.BIN files. Clock1, Clock2 and Clock3 which I mentioned before in this manual simply install into the interrupt routine and display a clock on the top right-hand corner of the 80*28 display. To make the clock readable, I also have them being printed in the top right-hand corner of the 32*16 display. To see how to read the clock, take a look at lines 600-699 of "MainMenu.BBS". K-REM2.BIN This is the remote that installs into the console in (CONIN) and console out (CONOUT) routines of Color BASIC. All it does is echo any characters to the modem that are sent to the screen and look for characters from the modem whenever characters are looked for from the keyboard. I've added quite a few extras to the remote that I've found useful in running the BBS that also need to be explained. Most of these are switches which can be changed by the command PARAM. It's syntax is as follows (defaults in brackets) 9 PARAM n,v where 'n' is the parameter number to change and 'v' is the value to assign to it. Eg., PARAM 0,1 turns linefeeds on, PARAM 0,0 turns them off. PARAM Description ----- -------------------------------------------------- 0 Linefeed toggle. If set to 0, no linefeeds are (0) sent with CR's to the remote terminal. If set to any other value, LF's are sent. 1 Baud Rate toggle. Set the value here according to (8) the chart in the RS232 pak manual. Eg, to set the baud rate to 300, use PARAM 1,6. For 1200 use 8, and for 2400 use 10. 2 I/O toggle. If set to 0, the modem i/o is detached (1) from the remote and will have not be written to or read from. 3 Run on DCD toggle. If set to 0, a loss of carrier (0) will be ignored by the remote. If set to any other value, a loss of DCD causes the remote to execute a RUN 950 at which point the BASIC program will reboot the BBS. 4 Character Mask. If set to 0, all characters are (0) sent to the modem without any modification. If set to any other ASCII value, that ASCII value is sent to the modem instead of the character. The use is for hiding passwords. The space and enter are not effected by this mask. 5 Keyclick toggle. If set to 0, no keyclick is heard. (1) If set to any other value, a click is made through the speaker for every character pressed on the key- board. 6 Keyclick tone. We all have different tastes, so (80) adjust the tone of the keyclick with this parameter. 7 BREAK enable. If set to 0, a CTRL-C received across (1) the modem is processed as if it were the BREAK key on the keyboard. If set to any other value, any CTRL-C from the modem is immediately filtered. 8 Nulls on CR. Set to the number of nulls needed to be (0) sent after a CR. 10 9 Password protection toggle. If set to 0, any drop to the BASIC command line ("OK" prompt) will be allowed without question. If set to any other value a password will be asked for (set in *.BBS) and if the correct password is entered, the user is allowed to enter BASIC commands. (PARAM 9 is also cleared to 0 so you'll have to reset it to 1 to enable the pass- word protection again. Among the above parameters, K-Rem2 replaces the hi-res graphics commands useless for running a BBS with some useful commands for controlling variables. The added commands are UPPER, UPLOW, RESTORE xxxx, CHAT and SCAN$. UPPER - will allow you to quickly convert any string to uppercase only. It's used for comparing passwords and usernames where you don't want case to make a difference. Eg., A$="Lowercase" UPPER A$ PRINT A$ LOWERCASE UPLOW - will convert strings to an upper/lowercase combination used mostly for capitalizing user names. Eg., A$="JOHN G. DOE" UPLOW A$ PRINT A$ John G. Doe RESTORE xxxx - is a rewrite of the RESTORE command to allow RESTOREing to a specific line number. The RESTORE token is added to the RENUM command, so line numbers are changed properly if you use the RESTORE. One problem though, you can use plain RESTORE on a line by itself, but you must use RESTORE 0:... on a multicommand line or you'll get an error. (a bug I can't figure out yet, but not very serious). CHAT - is a built in chat mode with an 80 column word wrap. While in chat, you can use the following keys to perform certain functions: ALT- F2 - Exit chat, return to calling point ALT-SHIFT-F1 - Turn I/O toggle off, BREAK to BASIC ALT-SHIFT-F2 - Turn I/O toggle on There is a special form of chat which is called with CHAT 1, and is a full duplex terminal emulator used in the "Term.BBS" program. The only hot key here is ALT-F2 to exit from chat and return to the calling point. 11 SCAN$ - is similar to an INKEY$ loop but it waits for a certain period of time for a character. If that period of time goes by with no input, a RUN 740 is executed at which point the BASIC program takes control and prints a "No input for 'such-and-such' time" and logs the person off. SCAN$ also keeps it's eye on the logoff time, and if the person's time on the BBS runs out, a RUN 730 is executed at which point the BASIC program takes control and prints a "Time exceeded" type of message. SCAN$'s syntax is as follows: V$=SCAN$(1500),1 where, V$ =any string variable to hold the character. 1500=length of time in 1/60's to wait for a char ,1 =a flag to convert that char to uppercase (use ,0 to leave the character as it comes) One last feature of K-Rem2 is its ability to filter out any characters you don't want to come in across the modem. This filter table is pointed to by they two bytes at $E86A and $E86B and can contain up to 6 characters. If you need to filter out more characters, you can place a filter table anywhere in memory and change the above pointer to point to your table. Currently, the table filters out only a CHR$(10) and a CHR$(12) which both play havoc with messages in the message base. Eg., F=PEEK(&HE86A)*256+PEEK(&HE86B) 'Point to table POKE F ,08 'Filter BS POKE F+1,13 'Filter CR POKE F+2,32 'Filter Space POKE F+3,65 'Filter "A" POKE F+4,255 'EOF marker-must be present RAMDRIVE.BIN This program installs two ramdrives into a 512K CoCo 3. It will NOT work with any custom DOSes as most custom DOSes use up the space required for all the allocation tables of the two extra ramdrives. The ramdrives are installed as drives 4 and 5 and are accessible exactly like regular floppies. MBASE.BIN This program is used in conjunction with K-REM2.BIN and provides some message entering and editing features to ease the burden of writing a message editor. There are three subroutines in this routine for (1) entering, (2) editing and (3) displaying messages. Before any of the above functions can be done, one must DIM variables for the 12 message base. Messages are 1024 characters long which can't fit inside 1 variable, so I split them into 8 variables of 128 characters each. The catch is the variables must be consecutive in memory and so the DIM command is used. "MBASE.BIN" is only loaded when needed and before loaded, it must have some memory CLEARed for it. How much memory you want to clear is up to you, but you must clear XXXX,&H78FF e.g., for all following examples: DIM M$(7),E$(1) CLEAR 2000,&H78FF LOADM "Mbase" The machine language subroutine to enter text is pointed to by the first 2 bytes of "Mbase.BIN". Create a USR function to point to the editor as follows: DEF USR2=PEEK(&H7900)*256+PEEK(&H7901) All you have to do to start the entering of the message is pass the variable pointer of the DIMmed strings to the machine language routine. e.g., Z=USR2(VARPTR(M$(0)) The message editor will automatically make all the strings 128 bytes long, and then fill them with CHR$(0)'s. Then, you or the remote caller will be able to type in a message of up to 1024 characters. To finish the message, two carriage returns in a row are pressed and control is returned to the calling point from BASIC. To continue entering in a message that was exited from (via two carriage returns) just EXEC PEEK(&H7906)*256+PEEK(&H7907) and the message can be continued. The message editor has an automatic word wrap that is set to 80 columns. This word wrap can be changed however by POKEing &H790A,width-1. The machine language subroutine pointed to by the second two bytes of "Mbase.BIN" allow for viewing of the message. All this does is get one byte at a time from the modem and display it on the screen and send it to the modem. Between each byte it looks for either an "A" or "P" being pressed and if it receives it, the message will either be aborted or paused. e.g., DEF USR3=PEEK(&H7902)*256+PEEK(&H7903) Z=USR3(VARPTR(M$(0)) 13 The last subroutine provided by "Mbase.BIN" is the ability to replace all occurances of one string with another. This is known as a global search and replace. e.g., DEF USR5=PEEK(&H7904)*256+PEEK(&H7905) E$(0)="one":E$(1)="two" Z=USR5(VARPTR(E$(0)) In the above example, all occurances of the string "one" will be found and replaced with "two" in the message. To find out just how many occurances were changed, you can PRINT PEEK(&H7908)*256+PEEK(&H7909). XMODEM.BIN The last subroutine that is loaded only when needed is "XModem.BIN". This is used to do Xmodem send, Xmodem receive, Ymodem send, and Ymodem receive of files to disk. It will also do ASCII sends of files which is useful for printing text information or sending ANSI pictures. To load "XModem.BIN" you first must CLEAR some space for it, and then set a few variables to point to the various transfer subroutines. It looks something like this in "Files.BBS": CLEAR &HFA0,&H6CFF:LOADM "XModem":AD=&H6D00 XR=PEEK(AD+0)*256+PEEK(AD+1) XM=PEEK(AD+2)*256+PEEK(AD+3) YR=PEEK(AD+4)*256+PEEK(AD+5) YM=PEEK(AD+6)*256+PEEK(AD+7) XA=PEEK(AD+8)*256+PEEK(AD+9) XE=AD+10 To do an Xmodem or Ymodem receive, you first OPEN"O" a file to receive the transmission, and then EXEC XR or EXEC YR depending on whether to do an Xmodem Receive or a Ymodem Receive. To do an Xmodem, Ymodem or ASCII send, you first OPEN"I" the file you want to transmit, and then EXEC XM, EXEC YM, or EXEC XA depending on whether to do an Xmodem Send, a Ymodem Send, or an ASCII send. The variable XE will let you know how successful the transmission was. If there were no errors during transmission, then PEEK(XE) will equal 0. If there were any errors, PEEK(XE) will contain some other value. The "XModem.BIN" file must be used with the "ANSI.BIN" file in order to keep the transfer window on the screen properly. 14 DIGITS BASIC programs --------------------- Now that you have a better understanding of the ML routines, I'll try to explain some of the BASIC routines used by DIGITS. I restricted the major GOSUBs to between lines 0 and 1500 which also include some code for OPENing the various files and setting system variables. The common GOSUBs include reading the clock, getting a character from the modem and displaying menus. I'll explain each in order of appearance: LINES 0 - 299 These just CLEAR appropriate space for the program in memory, LOADM any ML routines used by the program (i.e, XModem.BIN or Mbase.BIN), set the ON ERR GOTO line, OPEN the user files used by the program and set up the ANSI color arrays and a few other system variables. LINES 300-399 This is the log-off routine to close the files, set the log-off status (Time-up, No Input for 5 mins, etc.) and then RUN the "Logoff.BBS" file to say goodbye to the user. LINES 400-499 These lines are free for any subroutine specific to any program you may wish to add. LINES 500-599 These lines are a GOSUB which return the current date and time in the string UDATE$. The format is as follows: "29/01/87 at 22:03:45" The length of UD$ is always 20 characters, and is in the form "DD/MM/YY at HH:MM:SS". LINES 600-699 These lines are used to read the current time into HR$. The length is always 8 characters and the format is "HH:MM:SS". Another variable returned from this GOSUB is HR, and it contains the number of minutes the user online has left before his time expires. This value can be used in a "(T-xx)" addition to the Main Menu prompt. 15 LINES 700-749 These lines are a GOSUB to read a character from the modem into AN$ and convert it to uppercase. It does a timed input which means if the user doesn't press a key within 5 minutes, the system will log him out (through a GOTO 300). The character from the modem (or keyboard) is stored in AN$ (a length of one byte) and it's ASCII value is stored in AN (using AN=ASC(AN$)). LINES 750-799 These lines will take the string in AN$ and convert it to all uppercase. LINES 800-899 These lines convert the string in AN$ to a value. In doing so, it removes the possibility of an ?OV ERROR by filtering out any exponential strings (i.e. "1E99") and very long strings of numbers (i.e, "99999999999999999999999999999999999999"). The VAL of the string is returned in the variable AN. LINES 900-949 These are reserved for the ON ERR GOTO subroutine. One of the first lines of the program will ON ERR GOTO 900 so control will be transfered to these lines. On the chance of an error, each program will POKE it's ERLIN and ERNO into memory as well as it's individual program number. Then, "MainMenu.BBS" is run to allow the user to stay on the BBS for any other purposes. If the error occured in "MainMenu" then the person is forced to logoff. During any error, when the "Logoff.BBS" is run, it checks for error status, and if an error did occur, it colors the border of your screen red just so you know something has gone wrong. At your own convenience, you can take a look to see what program the error occured, and start debugging. LINES 950-999 These are reserved for a ML routine which scans the carrier status (bit 5 of the STATUS register on the RS232 pak) and performs a RUN 950 should the person disconnect. This RUN action can be disabled by using the DCD toggle poke (&HFB0F). LINES 1000-1099 After the files have been OPENed and FIELDed, control is given to 1000 which reads in the user's account and other pertinent info and then performs a GOTO 1500 to execute the program in memory. 16 LINES 1100-1199 These read in the DATA at the current DATA pointer for all the menu information. A common menu data statement will look like this: DATA YYour Information,Your Info,0 Lines 1100-1199 read this data statement (and any following up to a data statement reading END) and stores the menu information into the arrays MENU$(), REPLY$(), LEVEL() and the string CHOICE$. In the above example, MENU$() would contain "YYour Information", REPLY$() would contain "Your Info" and LEVEL() would contain 0. CHOICE$ would have a "Y" added to the end of it. MENU$() contains all information about the choices that is printed in the menu (when the person selects [?] as a choice). REPLY$() contains all the strings that are printed at the menu when the person presses their selection. LEVEL() contains the level of the choices and makes sure that a choice can be made available to the user online CHOICE$ contains all possible choices the user online can make. It is printed at the menu when the person presses [/]. LINES 1200-1299 These read in the various computer types data. It is only necessary in the Main Menu (for the Your Information section) and the Logon (for creating new accounts). LINES 1300-1339 These lines print out the menu of choices (contained in MENU$()) and centers a header at the top of the menu (contained in the string PLACE$). LINES 1340-1399 These lines print out the menu prompt, containing the time, menu name (PLACE$) and user name (NAME$). Then it waits for a keypress and makes sure the key pressed is a choice available to the user. If it is, it prints the selection (contained in REPLY$()) and returns to the calling point of the GOSUB for an ON CHOICE GOSUB routine. LINES 1400-1499 These are some more lines available to the user for a subroutine common to the program. In "MainMenu.BBS" I have filled these lines with a "Press any key" prompt and a "[P]ause or [A]bort" prompt. 17 LINES 1500- These lines can be used for any BASIC programming. ** NOTE ** The above lines are not by any means manditory. If you want to tack on a seperate BASIC game or utility to the BBS you might want to use some of those subroutines. The only routines that can be considered manditory are lines 700-799 and lines 950-999 to which control is given on predefined ML routines. Lines 730 and 740 are RUN via ML should the SCAN$ function be used and LINE 950 is run should the DCD toggle (&HFB0F) be on and should the person disconnect. 18 BBS Errors ---------- Should you turn on your monitor and see the border has turned red, you are being told that an error has occured. To find the error, all you have to do is a few PEEKS. They are as follows: PRINT PEEK(&HFDDE)*256+PEEK(&HFDDF) will return the ERLIN PRINT PEEK(&HFDDF) will return the ERNO PRINT PEEK(&HFDE7) will return the program number The program numbers are as follows: PEEK Program ---- ------------ 1 Boards .BBS 2 -- 3 Files .BBS 4 Jot .BBS 5 -- 6 Logon .BBS 7 MainMenu.BBS 8 Mbase .BBS 9 SysopMsg.BBS Just LOAD in the program corresponding to the value in PEEK(&HFDE7) and look for the cause of the error using the ERLIN and ERNO values. When you fix the problem (or even if you can't), you can change the border back to black by the following POKES: POKE &HFDE7,0 'clear error flag POKE &HE047,0 'black border 19 Forseen Problems ---------------- I'm not one with good foresight, but these are just some of the problems I can think of which may cause you problems. 1. You won't get the modem to answer I'm not familiar with every modem so you'll have to refer to your modem user's manual for information on getting your modem to answer an incoming call. You might have to include a modem initialization string in one of the "*" programs to set some parameters in your modem registers each time you boot the BBS. 2. You won't get DIGITS to recognize a connection In this case, the problem would be with either the modem or the RS232 pak. Bit 5 of the Status Register in the RS232 pak changes with the status of the carrier line. When no carrier is present, bit 5 should be at logical 1 and when carrier is present, bit 5 should be at logical 0. Chances are your modem has it's CD status set to "forced high" or something similar which keeps bit 5 of the Status Register constantly at logical 1. You want your modem to accept the CD line as active in order for the BBS to respond to a connection. If you cannot get this to work at all, you might want to change line 1120 of the "Logon.BBS" to look for some input from the modem like "CONNECT" or "CONNECT 1200" and rewrite the first part of the logon routine to correspond accordingly. 3. The modem echoes back characters to the BBS making things go crazy. This problem would have direct correlation to the problem above as the RS232 pak only accecpts characters from the modem IF the CD becomes active. If setting CD to normal on your modem doesn't help, you may have to send an echo-off command (like ATE0 for Hayes compatables). 4. The BBS always thinks it has a carrier and repeatedly cycles through the logon. This could be one of two problems. Either your modem is shut off (which does strange things to the CD status input) or the CD status has been forced high (same problem as above). 5. Users are having problems logging in under 7 bits. This happens on my BBS too, even when I set the RS232 pak to 7E1. The problem could be with the user's terminal, so make a strong suggestion they stick to 8N1. 20 6. The DIGITS software will not disconnect a user. DIGITS currently tries to disconnect a user by dropping the DTR line. What this does is causes the handshaking between the computer and the modem to be lost and most modem's will respond to this by hanging up the phone. If your modem does not respond to DTR this way, it could be one of two reasons: First, it could be due to the fact that your modem just doesn't drop the line when DTR is dropped. If this is the case you will have to find some other means of disconnecting the modem, or just hope everyone will be honest enough to disconnect when they log-off or are forced to log-off (ran out of time, etc.) Second, it could be due to the fact that your modem is not set to respond properly to DTR. There may be some command you have to send your modem or some DIP switch you have to toggle in order to get your modem to react normally to TR. 7. Your BBS keeps coming up with ?NE errors. While writing DIGITS, I was trying to keep the drives selectable incase one of my drives ever broke down and I had to change to a different drive for a short while in order to keep the system up. However, there's a good chance that I slipped and did a DRIVE 4 command instead of DRIVE PEEK(&HFDF3) or something similar. This will only cause problems should you not be running your system out of ramdrive 4 and the userfiles and message base out of drive 0. 8. Your BBS keeps coming up with ?IE errors. This would most likely be due to the length of the file and the length the BBS thinks the file should be differ. Chances are the *.BBS program has some system variables set wrong. (i.e, "# of users" set to 150 when you created only 100 user accounts using SETUP.BAS) One other problem that could be causing ?IE errors are continual crashes on the file allocation tables. For the longest time I was getting errors like this that I chalked up to bad drives, but after the first purchaser of the BBS started getting the same errors, I spent a good week or so tracking the problem down to the track tables for double sided drives. Although I have no cure yet, I do have a fix which has been applied in the ML routines. If you still have this problem, contact me with as much information about it as possible so I can make some more changes to the software. 21 FINALE ------ I hope I've explained things so that you can understand them. The BASIC routines shouldn't be to hard a concept to grasp. The ML routines are better explained in the source code so you might have better luck understanding things by reading the source codes. There are two miscellaneous commands that I should mention. The first is your control over disconnecting a user that's online. You can press SHFT-BRK (ESC) when a user is at a menu and the BBS will logoff the user saying "Sorry, your time is up". The second command is built into the remote ("K-Rem2.BIN") and can be entered at any place a keypress is required. Pressing ALT-C (capital C) from the keyboard will send the string "Sysop requests chat" to the modem, pause for one second, and then erase the string with a series of CHR$(8)'s. I'm pretty sure I've explained everything that needs explaining. If I've forgotten anything, I'll send you manual addendums to add to the back of your manual. Also, should there be any major additions or changes to the DIGITS code, you will recieve a disk in the mail with the changed programs and any addendums to the manual. If the change is a small one (i.e, the alteration of one or two lines) then I'll just send you a letter explaining the changes (and/or an LLISTing of the lines.) The last thing I'd like to say is feel free to make changes to the code. One of the things I really hate is "cookie cutter" BBSes (like the hundred thousand or so OPUSes). Since you're going to be running this thing, I give you my blessing to make as many hacks as you feel necessary to create the image of your perfect BBS. *********************************************************** One thing I ask is at sometime during the login, you have a message stating my name and the fact that you're using DIGITS software. *********************************************************** Please contact me at either (403) 242-3515 (the original DIGITS BBS) or (403) 242-3485 (my voice line). Ken 22 Please contact me at either (403) 242-3515 (the original DIGITS BBS) or (403) 242-3485 (my voice line). Ken                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  B Move cursor down C Move cursor right D Move cursor left E Erase screen H Home cursor I Reverse LF with scroll J Erase from cursor to end of screen K Erase from cursor to end of line Yrc Move cursor to row (r-32), column (c-32) Z Identify /Z Response to Identify b Erase from cursor to start of screen j Save cursor position k Restore cursor position l Erase line o Erase from cursor to start of line p Light background q Dark background x2 Key click off x5 Cursor invisible y2 Key click on y5 Cursor visible < Use VT-100 escape sequences 27 The following is a list of the supported VT-52 functions and the keys they are assigned to when Terminal Type is set to VT52 and the VT Keypad is on (ALT-Q): Ultimaterm keys DEC VT-52 FUNCTION TRANSMITTED CODES (hex) ----------------------------------------------------------------- Control-I ......... Horizontal Tab ........................... 09 Shift Left Arrow .. Character Delete ......................... 7F Shift @ ........... Home Cursor ............................ 1B48 Up Arrow .......... Cursor Up .............................. 1B41 Down Arrow ........ Cursor Down ............................ 1B42 Right Arrow ....... Cursor Right ........................... 1B43 Left Arrow ........ Cursor Left ............................ 1B44 CLEAR ............. Clear Screen ....................... 1B481B4A Shift ENTER ....... Erase end of line ...................... 1B4B ALT 0 ............. Keypad Application mode 0 ............ 1B3F70 ALT 1 ............. Keypad Application mode 1 ............ 1B3F71 ALT 2 ............. Keypad Application mode 2 ............ 1B3F72 ALT 3 ............. Keypad Application mode 3 ............ 1B3F73 ALT 4 ............. Keypad Application mode 4 ............ 1B3F74 ALT 5 ............. Keypad Application mode 5 ............ 1B3F75 ALT 6 ............. Keypad Application mode 6 ............ 1B3F76 ALT 7 ............. Keypad Application mode 7 ............ 1B3F77 ALT 8 ............. Keypad Application mode 8 ............ 1B3F78 ALT 9 ............. Keypad Application mode 9 ............ 1B3F79 ALT - (dash) ...... Keypad Application mode - (dash) ..... 1B3F6D ALT , (comma) ..... Keypad Application mode , (comma) .... 1B3F6C ALT . (period) .... Keypad Application mode . (period) ... 1B3F6E ALT ENTER ......... Keypad Application mode ENTER ........ 1B3F4D ALT F1 ............ Program Function 1 (PF1) ............... 1B50 ALT F2 ............ Program Function 2 (PF2) ............... 1B51 ALT F3 ............ Program Function 3 (PF3) ............... 1B52 ALT F4 ............ Program Function 4 (PF4) ............... 1B52 28 DEC VT-100 Control Codes The following is a list of the supported VT-100 control codes that are received or transmitted when Terminal Type is set to VT100: 7 Store cursor location and attributes 8 Get cursor location and attributes D Index (same as linefeed) E New line (go to first column of next line) M Reverse linefeed Z Identify (not recommended.. see ESC [c) < Sets terminal for ANSI escape sequences > Sets auxiliary keypad to numeric = Sets auxiliary keypad to escape sequences [xA Move cursor up x lines [xB Move cursor down x lines [xC Move cursor right x lines [xD Move cursor left x lines [r;cH Move cursor to row r, column c [0J Erase from cursor to end of screen [1J Erase from cursor to start of screen [2J Erase entire screen [0K Erase from cursor to end of line [1K Erase from cursor to start of line [2K Erase entire line [0c Identify [?1;0c Response to Identify [r;cf Move cursor to row r, column c [?1h Cursor keys generate application control functions [?2h Use VT-52 escape sequences [?5h White screen background [>4h Home and Clear on FF [>14h Half duplex [?1l Cursor keys generate ANSI cursor control sequences [?5l Black screen background [>4l LF on FF [>14l Full duplex [m Default attributes (white on black, no attributes) [0m Default attributes (white on black, no attributes) [4m Turn underline attribute on [7m Inverse letters [5n Device Status Report [0n Term OK (echoed back for DSR) [6n Cursor Position Report [r;cR Cursor is at row r, column c (echoed back for CPR) [t;br Set top and bottom margins (for scroll) [h;m;st Set time to h:m:s [0v Visible cursor [1v Invisible cursor [2v Cursor is underline [3v Cursor is block 29 The following is a list of the supported VT-100 functions and the keys they are assigned to when Terminal Type is set to VT100 and the VT Keypad is on (ALT-Q): Ultimaterm keys DEC VT-100 FUNCTION TRANSMITTED CODES (hex) ----------------------------------------------------------------- Control-I ......... Horizontal Tab ........................... 09 Shift Left Arrow .. Character Delete ......................... 7F Shift @ ........... Home Cursor .......................... 1B5B48 Up Arrow .......... Cursor Up ............................ 1B5B41 Down Arrow ........ Cursor Down .......................... 1B5B42 Right Arrow ....... Cursor Right ......................... 1B5B43 Left Arrow ........ Cursor Left .......................... 1B5B44 CLEAR ............. Clear Screen ................. 1B5B481B5B324A Shift ENTER ....... Erase end of line .................... 1B5B4B ALT 0 ............. Keypad Application mode 0 ............ 1B4F70 ALT 1 ............. Keypad Application mode 1 ............ 1B4F71 ALT 2 ............. Keypad Application mode 2 ............ 1B4F72 ALT 3 ............. Keypad Application mode 3 ............ 1B4F73 ALT 4 ............. Keypad Application mode 4 ............ 1B4F74 ALT 5 ............. Keypad Application mode 5 ............ 1B4F75 ALT 6 ............. Keypad Application mode 6 ............ 1B4F76 ALT 7 ............. Keypad Application mode 7 ............ 1B4F77 ALT 8 ............. Keypad Application mode 8 ............ 1B4F78 ALT 9 ............. Keypad Application mode 9 ............ 1B4F79 ALT - (dash) ...... Keypad Application mode - (dash) ..... 1B4F6D ALT , (comma) ..... Keypad Application mode , (comma) .... 1B4F6C ALT . (period) .... Keypad Application mode . (period) ... 1B4F6E ALT ENTER ......... Keypad Application mode ENTER ........ 1B4F4D ALT F1 ............ Program Function 1 (PF1) ............. 1B4F50 ALT F2 ............ Program Function 2 (PF2) ............. 1B4F51 ALT F3 ............ Program Function 3 (PF3) ............. 1B4F52 ALT F4 ............ Program Function 4 (PF4) ............. 1B4F52 30 ANSI-BBS Control Codes The following is a list of the supported ANSI-BBS control codes that are received or transmitted when Terminal Type is set to ANSI: [xA Move cursor up x lines [xB Move cursor down x lines [xC Move cursor right x lines [xD Move cursor left x lines [r;cH Move cursor to row r, column c [0J Erase from cursor to end of screen [1J Erase from cursor to start of screen [2J Erase entire screen [0K Erase from cursor to end of line [1K Erase from cursor to start of line [2K Erase entire line [xL Inserts x blank lines at cursor line [xM Deletes x lines including cursor line [x@ Inserts x blank characters at cursor [xP Deletes x characters including cursor character [r;cf Same as [r;cH (not recommended) [6n Cursor Position Report [r;cR Cursor is at row r, column c (echoed back for CPR) [s Save cursor position [u Restore cursor position [m Default attributes (white on black) [4m Set underline attribute [5m Set flashing attribute [7m Invert colors [3xm Set foreground color to 'x' [4xm Set background color to 'x' For foreground and background colors, when 'x' is '0', color selected is black when 'x' is '1', color selected is red when 'x' is '2', color selected is green when 'x' is '3', color selected is yellow when 'x' is '4', color selected is blue when 'x' is '5', color selected is magenta when 'x' is '6', color selected is cyan when 'x' is '7', color selected is white NOTE: In a default save, the current attribute is saved, so you can select a color display you like and save it for each time you use Ultimaterm. 31 Vidtex Control Codes These are taken from the manual to "Greg-E-Term" with only three differences to GETERM.. Ultimaterm responds with "ULTIMATERM 4.0" for the Interrogate command.. Ultimaterm will always reset to it's default palettes and not those according to Extended Color Basic.. and Ultimaterm will not allow it's screen to be altered from the 80x28 display it is at. It returns a NAK for the screen mode command. The following is a list of supported Vidtex control codes that are received or transmitted when Terminal Type is set to Vidtex: A Move cursor up B Move cursor down C Move cursor right D Move cursor left H Home cursor I Interrogate: Ultimaterm responds "ULTIMATERM 4.0" J Clear to end of screen K Clear to end of line Yrc Move cursor to row (r-32), column (c-32) j Clear screen, home cursor Ax Set attribute to 'x' Bx Set border color to 'x' C Returns $FF for CoCo 3 D Forces Ultimaterm to 8n1 I Interrogate: Ultimaterm responds with $07 for CoCo III 80x24 screen Ppc Set palette 'p' to color 'c' Rx Set palettes to default; ignores x Sx Ignores this command, returns NAK ($15) 32 x24 screen Ppc Set palette 'p' to color 'c' Rx Set palettes to default; ignores x Sx Ignores this command, returns NAK ($15)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  ~& т 80&у 0,0:у 8,63:Ю 1&JЗ:З," Send to printer?":З&ZЗ,," ";&ЗPR$│ Т:ЕPR$│"Y"з7:ДЕPR$│"N"зЗ"N":З:Бе 20&ПБе5&ЪЗ"Y":З&╞З:З," Printer baud rate?":З&ь З,"<1> 300 baud","<2> 600 baud"' З,"<3> 1200 baud","<4> 2400 baud"'8 З,"<5> 4800 baud","<6> 9600 baud"'> З'R A$│ Т:ЕA$│""з13'hЕA$┤"1"▒A$▓"6"з13'vЗд36);A$;'нA$│ Р("300 600 1200240048009600",( Й(A$)м1)н4л1,4)'╩A│ Б((55930о Й(A$))м4.5)'уТ 149,(Aо256) ░ &HFF'ЎТ 150,A ░ &HFF(Щ"I",#1,"SYSOP.MAN"(Ю(%Е  М(1) з 28(5╗Й #1,TEXT$(@ЗTEXT$(XЕPR$│"Y"зЗ#м2,TEXT$(bБе 22(i:Г(}Ъ:З:З"Finished"("300 600 1200240048009600",( Й(A$)м1)н4л1,4)'╩A│ Б((55930о Й(A$))м4.5)'уТ 149,(Aо256) ░ &HFF'ЎТ 150,A ░ &HFF(Щ"I"