UNLEASHING THE 1030 MODEM
Secrets of its built-in device handler
by Russ Wetmore
How to access the powerful commands of the little-known device handler software built into the popular Atari 1030 modem. Learn how to use these commands in your own telecommunications programs. Includes two short BASIC programs to get you online. These programs work on all Atari computers of any memory size, with disk or cassette.
This article will tell you some things you probably didn't know about the inexpensive and widely-used Atari 1030 Modem.
If you own a 1030, you may be already aware that you don't need to use the built-in ModemLink telecommunications software – which cannot transfer program or text files.
Antic readers are likely to know there are several programs available that enable the 1030 to upload and download files. From the Antic Arcade Catalog you can purchase TSCOPE (PD024) and Chameleon (AP113). Or you can use the HomeTerm program on HomePak ($49.95, Batteries Included), of which I happen to be the author.
There are other public domain programs for the 1030, but these require a special program called a "device handler" which must be loaded before the terminal program can operate. A device handler is a machine language program that tells your computer how to talk to its peripheral devices. Disk drives use a D: handler, printers use a P: handler.
BUILT-IN HANDLER
Contrary to popular belief, you don't need a separate handler. The 1030 contains a built-in device handler that you can easily access. It's called T: handler and it even supports tone dialing – which the various public domain handlers do not! In this article I'll show you how to access the 1030 T: handler with your computer and use it when you write your own terminal (telecommunications) programs. I also provide a very simple program to show how some of the commands are used in BASIC.
MEET MR. T:
Most other modems use a device handler labelled R:, but the device handler inside the 1030 is named T:. After it is installed, you can access it through normal device commands – OPEN, CLOSE, INPUT, PRINT, GET, PUT and STATUS.
Unlike many other device drivers, the T: handler in the 1030 is not relocatable. The program will always load at memory location $1F00. It would overwrite part of BASlC's memory (causing a crash) if you initialize BASIC before loading the handler.
For this reason, you must use an AUTORUN.SYS program on a set-up disk to arrange your computer's memory pointers before BASIC is initialized. That's where MAKEAUTO.BAS comes in.
Type in Listing 1, check it with TYPO II and SAVE a copy. Make sure that you don't already have an AUTORUN.SYS on the disk you SAVE this listing to – unless you don't mind that MAKEAUTO.BAS will delete it.
After you create the new AUTORUN.SYS file, you'll boot (start up) the disk it's on to load the handler from the 1030. You must do this before you run any terminal programs from BASIC.
TERMIN(AL)ATOR
Listing 2, MINI1030.BAS, is a short 21-line terminal program that is just smart enough to log you onto a bulletin board. This program is simply a learning tool that provides an example of using T handler commands in BASIC.
Type in Listing 2, checking it with TYPO II. The program defaults to tone dialing, so you must delete line 18 if you need to use pulse dialing. SAVE the corrected listing.
Place in your drive the disk containing the special AUTORUN.SYS file you created earlier from Listing 1, and turn on your computer. If you own an older Atari 400 or 800 model, turn it on with the BASIC cartridge plugged in.
RUN Listing 2 and then type in the phone number you wish to dial and press [RETURN]. After your modem has detected an open connection, the screen will turn from black to dark blue and you'll be online.
USING T: HANDLER
Aside from the normal CIO (Central Input/Output) device commands, the 1030 T: handler supports 20 additional control commands which are listed in Figure 1. Unlike most handlers, special commands aren't sent by issuing an XIO statement. In fact, if you try it you'll get an Error 146 "Function Not Implemented."
T: handler special commands are sent to the modem as strings of characters, commonly called an "escape sequence." This method is not unlike the way printer control codes are transmitted, but the 1030 is the only modem I know of that works this way.
All command strings have at least two elements. The first is the [ESC] key (ASCII 27). The second is an ASCII letter from A to Z. Some commands require additional keys.
Some of you might be wondering how the modem can tell the difference between command strings and actual data. A non-zero byte in the handler variable CMCMD (memory location 7) alerts the handler to be on the lookout for escape sequences. If CMCMD is zero, then command strings are passed as normal character data.
Therefore, the handler only begins processing an escape sequence if it is NOT already processing a command, if CMCMD is not zero, and if the output data byte received is [ESC].
Once a command sequence has started, it will be completed no matter what CMCMD contains. Before the handler executes the command, it finishes sending whatever is left in its output buffer. While the command is being executed, the modem is still collecting input, so you don't lose any characters.
An example command is Set Parity, which is command [C]. To set this command from BASIC, you'd type something like:
- PRINT #MODEM; CHR$(27); "C"; CHR$(PARITY)
In the above example, PARITY is a command parameter telling the handler what to do with input and output parity. This is similar to an OPEN call where a parameter of 4 means Read and 8 means Write. An example of a command without any parameters is On-Hook, which is the command [M]. This command hangs up the phone:
- PRINT #MODEM; CHR$(27); "M";
The 1030 demands total control of the serial bus in order for it to keep up with the constant bit stream going in and out over the phone line. This means when the modem is active, you can't use any serial devices such as disk drives and printers.
SUSPEND & RESUME
To temporarily put the 1030 "on hold" so that you can use other serial devices, you must send it a Suspend command. (See Figure 1). While the modem is suspended, it does not receive any characters. For that reason, before your software issues the Suspend command it should first stop the sender from continuing.
How this is done depends on the system. Normally you send an XOFF character ($11 hexadecimal, or 17 decimal), then wait for the sender to stop transmitting data. Now you may issue the Suspend command. You send a Resume command once you're ready for the modem to continue. Afterwards an XON ($13 hex, or 19 decimal) goes out to signal the sender to continue.
It is important to note that CLOSEing the modem hangs up the phone. You should only CLOSE the modem device at the very end of your program. Also the handler does not accept any escape sequence commands while it is Suspended, except for Resume or CLOSE.
MODEM STATUS
There are two ways of obtaining modem's present status – the normal CIO STATUS command, or an [F] escape sequence. They both function identically.
When executed, either method returns four bytes into DVSTAT to DVSTAT+3 (memory locations $2EA to $2ED hexadecimal, or 746 to 749 decimal). The meaning of these status bytes is illustrated in Figure 2. You can use a status to determine handler errors. Or you can use it to find out the current condition of the modem – whether a carrier is present, whether the phone is on or off the hook, whether the modem is in tone or pulse dialing mode, etc.
BUFFERS
The input buffer is 256 bytes long. You can determine how many characters are waiting to be input by monitoring the device variable INCNT (memory location $400 hex, or 1024 decimal). In effect, you can tell if any bytes are waiting to be input if INCNT is not zero. If the buffer becomes completely filled, an error flag is set that you can monitor with a STATUS command. New characters will then be thrown away until you empty part of the buffer.
The output buffer is 64 bytes long. The number of characters waiting to be sent is kept in the handler variable OUTCNT (memory location $401 hex, or 1025 decimal). If you try to send data to the modem when the output buffer is full, the handler will loop until characters have been sent and the buffer again has room for your data.
ERRORS
There are two types of errors that you'll encounter while using the 1030 T: handler. During standard device commands such as OPEN and PRINT, CIO will signal errors by way of the normal CIO error return. Those errors not directly related to the CIO subsystem – such as loss of carrier, parity errors, etc. – are signaled by setting appropriate bits in the status table at DVSTAT. See Figure 3 for a complete listing of T: specific CIO error codes, and Figure 2 for status table error flags.
This is the first Antic article from the well-known and highly respected programmer of Preppie and Homepak. Russ is currently using the GEM system to develop ST software.
Figure 1
T:handler Special Commands
Set Translation: ESC A p1 p2
Two bytes follow the ESC A sequence. The first (p1) specifies the translation options, the second (p2) is the "will-not-translate" character. This is the character that replaces any non-ASCII characters that are received.
The translation byte is interpreted as follows:
Diagram A
Bit 7: Ignored.
Bit 6: Append line feed. This bit, when 1, specifies that a LF (ASCII 10) shall be sent after a CR (ASCII 13). This mode only works in the "light" or "heavy" translation modes (see Bits 4-5). The LF is sent whether the CR came from an ATASCII graphics character 13 or from a translated ATASCII EOL (155) (RETURN key value). Default is 1 (on).
Bits 4-5: These bits set the translation mode.
10 or 11 mean that no translation is to be done on either input or output data.
When 00, "light" translation is done. During input, CR's (ASCII 13) are translated to ATASCII EOL's (155). During output, EOL's are changed into CR's. Either direction, bit 7 is cleared (except for EOL's on input).
When 01, "heavy" translation is done. CR's and EOL's are handled as in the 00 mode. During input, all bytes that don't have an ASCII equivalent are changed into the "will-not-translate" character described above (i.e., all values below 32 and above 124). During output, any such non-ASCII codes are suppressed and not sent.
Bits 0-3: Ignored.
Set Parity: ESC C p1
One byte follows the ESC C sequence. This command sets what type of parity checking, if any, is done on both input and output data. Parity checking/setting is always done before an input byte is translated (see above) and done after translation of a byte to be output. The parity parameter byte is interpreted as follows:
Diagram B
Bits 4-7: Ignored.
Bits 2-3: These bits specify parity checking on input data.
00 means that no parity checking is done. The input byte is passed unchanged.
0l means that odd parity checking is done. In odd parity, the high bit of the incoming byte is set if there are an odd number of bits set in the remaining 7 low order bits. After the check, bit 7 is stripped off (set to 0).
10 means that even parity checking is done. Even parity is just like odd, except that the high bit is set if there are an even number of bits in the remaining 7 low order bits. The bit 7 is stripped off.
11 means no parity checking is done, but bit 7 is stripped off anyway.
Bits 0-1: These bits specify parity checking on output data.
00 means that no parity checking is done. The output byte is passed unchanged.
01 means to set odd parity. In other words, bit 7 of the output byte is set if there is an odd number of bits in the remaining 7 low order bits.
10 means to set even parity. Bit 7 is set if there is an even number of bits in the remaining 7 low order bits.
11 means to always set bit 7.
End of Commands: ESC E
This command is basically a shortcut for setting CMCMD (handler variable at memory location 7) to 0 after all handler commands are finished being sent (see text). After this command, no more ESC sequences will be recognized until CMCMD is set to non-zero again.
Status: ESC F
This command duplicates the normal CIO STATUS call. Four status bytes are returned to DVSTAT to DVSTAT+3 (memory locations 746 to 749). See Figure 2 for information on what these bytes contain.
Send Break Signal: ESC H
Some mainframe systems require you to send a special type of signal, called a BREAK. This is accomplished by holding the outgoing bit stream high for 500 ms. This command is handled a little differently from the others in the command list. Once you have sent the command, control is immediately returned to the program, but the BREAK signal continues being sent until it is finished.
Any data in the output buffer (and any new output characters sent to the handler) are buffered until the BREAK is finished. If another command is issued before the BREAK has terminated, the handler waits for the BREAK to finish, then outputs the contents of the output buffer before executing it.
Set Originate Mode: ESC I
Set Answer Mode: ESC J
For asynchronous (full duplex, two-way simultaneous) communications, one side must be set to "originate" mode, the other to "answer" mode. Generally, the caller is set to originate mode, and the "callee" is set to answer mode For communicating with a BBS and services like CompuServe, you should be in originate mode – for talking with another computer owner directly, one or the other of you should be set to originate. Originate mode is the default mode.
Set Pulse Dialing: ESC N
Set Tone Dialing: ESC 0
Dial Phone: ESC K p1 p2 ... px
These commands handle dialing mode and actual dialing out through the modem. The default is for pulse dialing.
Any number of ASCII numbers can follow the ESC K sequence. It isn't required for you to send the entire phone number sequence at once – you can send them one at a time if you want to do something special like output the numbers to the screen one by one as you send them.
The handler assumes that each number that is sent might be the last, and starts a 30 second timeout period to monitor the presence of a carrier signal. If no carrier signal is detected after 30 seconds (and if no more dial commands are sent), then the modem places the phone "on-hook" (hangs up the phone), which can be detected by doing a STATUS call to the handler.
For delays, send a comma instead of a number in the ESC K sequence string. This pauses the dialing for 3 seconds per comma.
An example: You want to dial 555-1212 from a CENTREX type office system, which requires that you dial a 9, wait 3 seconds, then dial the rest of the number. The ESC K command string in BASIC for this would be:
PRINT #MODEM; CHR$(27); "K"; "9,555-1212"
Take Phone Off-hook: ESC L (pickup phone)
Put Phone On-hook: ESC M (hang up phone)
The above two commands pick up and hang up the phonc When the phone goes off-hook, a 30 second timeout period is begun for detecting the presence of a carrier signal. If none is detected, the phone is hung up. Putting the phone on-hook can be used to prematurely terminate a dialing sequence, to terminate waiting for a carrier, or just to disconnect the modem from the phone line.
Start 30-second timeout: ESC P
This is the command for manually initiating the 30 second timeout period described above in the dialing and off-hook commands described above. Note that the mentioned commands do this automatically for you – you don't need to execute this command yourself in most normal circumstances.
Reset Modem: ESC Q
This command reinitializes the modem to its default conditions.
Set Analog Loopback Test: ESC W
ClearAnalog Loopback Test: ESC X
These two commands control "analog loopback testing." In English terms, this turns on an endless loop between your computer and the modem. Any characters sent to the modem are echoed back to you as if you were online and receiving characters. Used primarily to test that all characters are being received and sent unaltered by the modem.
Resume Modem: ESC Y
Suspend Modem: ESC Z
See text for subleties of "Resume" and "Suspend." Because the 1030 requires total control over the serial bus during operation, you cannot use other serial devices such as printers and disk drives. You must suspend the modem first, then resume when you are ready to return online.
Figure 2
Meaning of Returned Status Bytes in DVSTAT
When a CIO STATUS call is made, or the ESC F sequence is sent to the modem, the handler returns four bytes to DVSTAT to DVSTAT+ 3 (memory locations 746 to 749). Only the bytes at DVSTAT and DVSTAT+1 have significance:
DVSTAT – Hardware Errors:
Bit 7: Framing error encountered on received data. Because serial data is nothing but a series of 1's and 0's, some protocols have been established to help the modem tell where each byte of data begins in the bit stream. This error means that somewhere along the line, the modem was wrong in detecting what it thought was the beginning or end of a bit stream representing a byte.
Bit 6: Byte-level overrun encountered. This happens when the modem detects a character to be received before the latest character has been fetched by the handler. This command is not likely to happen unless your program has extensive interupt driven subroutines which prevent the modem interupts from being serviced often enough.
Bit 5: Parity error encountered on incoming data.
Bit 4: Wraparound error. The input buffer has completely filled and old data is being overwritten. The input buffer is considered "circular" – that is, the pointer into the buffer is reset to the start of the buffer when it reaches the end. You aren't fetching characters from the handler fast enough, basically.
Bit 3: Always 0.
Bit 2: Always 0.
Bit 1: Always 0.
Bit 0: Illegal command given to handler. This is the handler's version of a CIO 146 error. You gave the handler an improper escape sequence command. It only applies to the most recent command – it is reset upon acceptance by the handler of a valid one.
DVSTAT+1 – Current Modern status:
Bit 7: Carrier detected. It's a 1 when a carrier is present.
Bit 6: Always 0.
Bit 5: Analog loopback test status. Is a 1 when test is active.
Bit 4: Originate/Answer flag. Is a 1 when in answer mode.
Bit 3: Always 0.
Bit 2: Dialing mode flag. Is a 1 when in tone dialing mode.
Bit 1: Always 0.
Bit 0: Hook status. Is a 1 when phone is off-hook (modem is online).
FIGURE 3
CIO Error Number Meanings
These are the CIO errors most commonly encountered with the T:handler.
128: You pressed the BREAK key.
129: You tried to open an IOCB, and it was already open.
131: IOCB was opened as read only, and you tried to write to it.
132: You gave the handler an invalid command.
133: IOCB isn't open, and you tried to do I/O with it.
134: The IOCB you passed doesn't make sense (too high a number).
135: IOCB was opened as write only, and you tried to read from it.
136: End of file error. During input or output, it means that the carrier was lost.
138: Device timeout. The modem isn't responding. It usually means that the handler hasn't been loaded or has been accidentally overwritten, or the SIO cable is defective or pulled loose.
146: You tried to execute an XIO command other than normal CIO functions. This handler works strictly through ESC sequences, unlike most other handlers.
UNLEASING THE 1030 MODEM
Don't type the TYPO II Codes!MF 10 REM MAKEAUTO.BAS QO 20 REM BY RUSS WETMORE, FOR STAR SYSTEMS SOFTWARE, INC. BN 30 REM ANTIC PUBLISHING GA 40 ? "[ESC] [SHIFT] [CLEAR] Press [REVERSE VIDEO] START [REVERSE VIDEO] to create":? "AUTORUN.SYS file." GW 50 IF PEEK(53279)<>6 THEN 50 CG 60 GRAPHICS 2+16:? #6:? #6;" CREATING":? #6;"AUTORUN.SYS FILE" XF 70 DATA 255,255,0,6,30,6,162,9,189,21 YK 80 DATA 6,157,0,3,202,16,247,32,89,228 RK 90 DATA 48,4,24,32,12,29,96,88,1,60 OA 100 DATA 64,0,29,2,0,48,11,224,2,225 AZ 110 DATA 2,0,6 OB 120 CLOSE #1: OPEN #1,8,0,"D:AUTORUN.SYS" MK 130 TRAP 160 KX 140 READ A:? #1;CHR$(A); NI 150 GOTO 140 IJ 160 CLOSE #1:ENDDownload AUTO1030.SYS DownloadNote: [ESC] [SHIFT] [CLEAR] – Press and release the [ESC] key, then press and
hold the [SHIFT] key while pressing the [CLEAR] key. [REVERSE VIDEO] – Turn on inverse video
by pressing the [Reverse Video] Mode key. Pressing it again returns to normal video mode.
(the AUTORUN.SYS file generated by the above program)
FS 1 REM MINI-1030 DB 2 REM BY RUSS WETMORE, FOR STAR SYSTEMS SOFTWARE, INC. UD 3 REM ANTIC PUBLISHING UP 4 GOSUB 13 HR 5 IF PEEK(1024)=0 THEN 7 QL 6 GET #5,I: IF I>31 THEN ? CHR$(I); JX 7 IF PEEK(764)<255 THEN GET #4,I:PUT #5,I QR 8 STATUS #5,I:IF PEEK(747)>127 THEN 5 VS 9 GOTO 10 TX 10 ? :? CHR$(253);"MODEM DISCONNECTED!":FOR I=1 TO 1000:NEXT I:I=USR(58484) YE 11 ? "ERROR-";PEEK(195):GOTO 10 JS 12 ? "1030 HANDLER HAS NOT BEEN LOADED!":GOTO 10 QJ 13 DIM E$(1),F$(20):GRAPHICS 0:W=710:POKE 709,14:POKE W,0:E$=CHR$(27):? ,"MINI1030":TRAP 12 IC 14 CLOSE #4:CLOSE #5:OPEN #4,4,0,"K:":OPEN #5,12,0,"T:":TRAP 11 RD 15 ? :? "PHONE # ";:INPUT F$:IF F$="" THEN 15 JR 16 POKE 7,1 OI 17 ? #5;E$;"N":REM IF PULSE HE 18 ? #5;E$;"O":REM IF TONE IE 19 ? CHR$(28);"DIALING..";F$:? #5;E$;"K";F$ NU 20 STATUS #5,I:IF PEEK(747)<128 THEN 20 AE 21 POKE W,144:? CHR$(125):? "CONNECTED!":? :POKE 7,1:? #5;E$;"Y":POKE 7,0:RETURNDownload MINI1030.BAS Download