VMODEM Technical Reference Manual Copyright (c) 1994 by Raymond L. Gwinn 12469 Cavalier Drive Woodbridge, Virginia 22192 All Rights Reserved December 8, 1994 CompuServe: 71154,575 InterNet: p00321@psilink.com Voice: 1-703-494-4673 FAX: 1-703-494-0595 BBS: 1-703-494-0098 or 199.248.240.2 INTRODUCTION The Virtual Modem is a concept that the author believes will change the way serial data communications is done and thought of. It is going to bring the Internet alive more then ever before. Perhaps it will not be this implementation of a Virtual Modem, but the concept will remain and be used for a long time. The concept of the Virtual Modem was born from the desire to make the SIO support BBS available via Internet. In only a few minutes, I was convinced the Virtual Modem was a solution of a multitude of problems that Internet access poses. The Virtual Modem removes most of the complexities and mysteries of the Internet by allowing common, well understood, programs to be used to access the Internet highway. Users can use programs like PmComm and TE/2 to download files from a BBS (across the Internet) using common protocols like ZMODEM. The dialing directories of terminal programs can contain Internet addresses instead of phone numbers for easy access to remote sites. BBS SysOps can simply declare one or more of their BBS's communications ports as a Virtual Modem and users can then "dial" in over the Internet and no BBS software changes should be necessary. Is your BBS ready for 20 million new users that can access it without making a long distance call? This Virtual Modem implementation also included a Telnet server allowing most anyone on Telnet to access your system. Users transferring large volumes of data across phone lines (like FidoNet echomail) can now use the Internet highway instead. Again, software changes should be minimal, if any at all. Remote users of databases that needs frequent updating, like Lotus Notes, can use the Virtual Modem and Internet to keep their systems current. ii TABLE OF CONTENTS WHAT IS VMODEM . . . . . . . . . . . . . . . . . . . . . . . 1 DISTRIBUTION, ORDERING AND SUPPORT . . . . . . . . . . . . . 2 Distribution and Ordering . . . . . . . . . . . . . . . 2 SIO Distribution and Support BBS . . . . . . . . . 2 Support . . . . . . . . . . . . . . . . . . . . . . . . 2 GETTING IT GOING . . . . . . . . . . . . . . . . . . . . . . 5 TCP/IP Required . . . . . . . . . . . . . . . . . . . . 5 TCP/IP Sockets . . . . . . . . . . . . . . . . . . 5 The default port number . . . . . . . . . . . . . . 5 The SIO.SYS command line . . . . . . . . . . . . . . . . . . 5 THE VIRTUAL MODEM . . . . . . . . . . . . . . . . . . . . . . 7 AT Commands Supported . . . . . . . . . . . . . . . . . 7 S Registers Supported . . . . . . . . . . . . . . . . . 8 Result Codes . . . . . . . . . . . . . . . . . . . . . . 8 NO CARRIER . . . . . . . . . . . . . . . . . . . . 8 NO DIALTONE . . . . . . . . . . . . . . . . . . . . 8 . . . . . . . . . . . . . . . . . . . . . . . . . 8 BUSY . . . . . . . . . . . . . . . . . . . . . . . 8 CONNECT 57600/ARQ/VMP . . . . . . . . . . . . . . . 8 RING . . . . . . . . . . . . . . . . . . . . . . . 8 RINGING . . . . . . . . . . . . . . . . . . . . . . 8 Caveats . . . . . . . . . . . . . . . . . . . . . . . . 9 Dialing Examples . . . . . . . . . . . . . . . . . . . . 9 Telnet . . . . . . . . . . . . . . . . . . . . . . . . . . 11 IBM's Telnet Client . . . . . . . . . . . . . . . . . 11 THE VIRTUAL MODEM PROTOCOL . . . . . . . . . . . . . . . . 12 Development and Debugging Tools . . . . . . . . . . . . . . 13 The Poor Man's Line Monitor (PMLM.EXE) . . . . . . . . 13 VIEWPMLM.EXE . . . . . . . . . . . . . . . . . . . . . 14 SIO's Utility (SU.EXE) . . . . . . . . . . . . . . . . 14 IRQs that currently free for use . . . . . . . . 14 Appendix A, Hardware Port and IRQ Assignments . . . . . . . 15 Addresses and IRQs for COM1 and COM2 . . . . . . . . . 15 Defacto standard for COM3 and COM4 . . . . . . . . . . 15 Addresses and IRQ for COM3 through COM8 on the PS/2 . 15 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 1 WHAT IS VMODEM VMODEM is a software implementation of a modem, referred to as a Virtual Modem. Basically, it attempts to fake out other software (like terminal programs) into believing they are accessing a real modem. Normal (real) modems provide an interface that allows terminal programs to pass digital information across telephone lines. VMODEM does the same thing from the application (terminal) program's point of view. However, the other side of VMODEM is not a phone line, but a digital network like Internet. Thus, VMODEM allows the hoards of communications programs to pass information across Internet instead of using phone lines. In addition to acting as a Telnet server, VMODEM uses a newly designed protocol for communications networks, called the Virtual Modem Protocol (VMP). At this time, no other programs have implemented VMP, thus VMODEM is required on both ends of the connection to use the VMP. However, VMODEM.EXE will accept inbound Telnet connections from any system, meaning a BBS under vmodem can be accessed by just about anyone with an Internet connection. Future implementations of VMODEM may access networks other than Internet and use TCP/IP implementations other than IBM's. The current implementation of VMODEM works only on Internet, using the Internet Access Kit (IAK) that is included with OS/2 V3 and IBM's TCP/IP (for OS/2) version 2.0, with the August 1994 CSD applied. VMODEM also includes a Telnet server. See the section on Telnet for additional information. A single invocation of VMODEM can service all of the Internet ports defined in the SIO command line. 2 DISTRIBUTION, ORDERING AND SUPPORT Distribution and Ordering VMODEM is a part of a larger package collectively known as SIO. The entire package collectively known as SIO is ShareWare. It is not free software or freeware. See LICENSE.TXT and ORDER.TXT for additional information. The ShareWare version of SIO is distributed electronically. One may check their favorite electronic hangout for the latest version of SIO. The latest copy of the ShareWare version is always posted for downloading from the BBS at 1-703-494-0098 or 199.248.240.2. ShareWare versions of SIO can also be downloaded from the CompuServe Forum OS2BVEN, library 4. Registered versions of SIO are distributed by US Mail and electronically from the SIO Distribution and Support BBS. Users desiring to register electronically, may call the BBS and register on line (1-703-494-0098 or 199.248.240.2) and immediately download their registered version of SIO. Use the ORDER command at the main BBS prompt. Registrations/Orders can also be placed by phone, mail, FAX, and email. See the front cover of this manual for the phone numbers and addresses. Also see ORDER.TXT for and order form that may be used. Support Only product support is provided, user support for VMODEM is NOT provided. That is, help with application program configuration, modem init strings etc, is not provided. Product information such as bug reports, suggestions, and information about incompatibilities are welcome. They should be sent to one of the following addresses. Email CompuServe 71154,575 Internet p00321@psilink.com FAX 1-703-494-0595 BBS 1-703-494-0098 or 199.248.240.2 3 QUICK START This beta is intended to iron out problems in the Virtual Modem Protocol (VMP) and the virtual modem implementation prior to release. I am interested in bug reports and welcome suggestions about VMODEM such as "the ATDT command does not work" or "the virtual modes responds too fast" or "ring indicator is not working". If some of your applications do not work, it is probably due to the timing difference between the virtual modem and real modems. These type of problems are NOT bugs in VMODEM, but in the application itself and should be reported to the support department for the application program. Thus, messages saying that application XYZ does not work are probably of no value and may be ignored. The Good Stuff Starts Here: If you do not have TCP/IP up and running on your system, forget it, there is no quick start. If TCP/IP is running on your system then read on. Users of the IBM Internet Access Kit (IAK) and IBM's SLIP be sure to add MODE COMn DTR=ON somewhere before you attempt to dial in. First, you must define one or more Virtual Modem ports in the SIO.SYS command line and reboot. Defining a Virtual Modem port simply requires that you use the word "Internet" instead of the I/O port address in the SIO command line. Do not forget to assign the DOS reflection stuff if you will use the port from DOS sessions. An SIO command line example using COM2 as a Virtual Modem is: DEVICE=SIO (COM1,3F8,4) (COM2,INTERNET:2F8,NONE:3) The ":2F8" and the ":3" in the command line tells SIO to reflect data to DOS sessions on virtual I/O port 2F8 and virtual IRQ3. The "NONE" in the command line indicates that no real IRQ is used. After you have made the SIO command line changes, and rebooted, you must first activate TCP/IP. Users of the IBM Internet Access Kit must initiate a connection attempt before VMODEM will start. After TCP/IP is activated, type VMODEM at any OS/2 prompt. The VMODEM display attempts to simulate a modem display. An activity log will start at the bottom of the display and scroll up to the bottom of the simulated LED display. If you wish, you can use "START /min VMODEM" to invoke VMODEM in your TCP/IP start up scripts. Hit Control C if you wish to terminate VMODEM, but you must leave it running if you want Virtual Modem support. 4 Once VMODEM is started, any access to COM2 (in this example) will go out over the Internet. Bring up your favorite terminal program, configured for COM2, and type "AT?" for a list of supported AT commands. To dial out, type ATDT inetaddr.com, of course you must use a real Internet address. As of this writing, there are several BBSs available for incoming calls using VMODEM. Their Internet addresses are: 199.248.240.2 SIO Support in Virginia 199.100.191.2 Bob Juge in Houston Texas 199.67.41.2 PCBOARD, Clark Development 198.68.17.57 Paul Breedlove, Multinet 199.3.36.205 Steve Schmidt in Chicago Illinois 198.96.20.209 Steven Bonisteel in Canada 194.70.36.10 Jon Morby in England 198.17.249.111 Pete Link in USA 199.165.149.4 Pete Person in Washington State 5 GETTING IT GOING TCP/IP Required The current (first) implementation of VMODEM and works only with the Internet Access Kit (IAK) that is included with OS/2 V3 and IBM's TCP/IP V2.0 with the August 1994 CSD applied. Contact IBM for information about obtaining their TCP/IP and the CSD update. Prior to executing VMODEM, you should have TCP/IP installed and operational on your system. The author is far from an Internet or TCP/IP expert (more like a novice) so you are on your own in getting TCP/IP up on your system. Users of the IBM Internet Access Kit (IAK) and IBM's SLIP be sure to add MODE COMn DTR=ON somewhere before you attempt to dial in. The Virtual Modem Protocol (VMP) that is implemented by VMODEM uses TCP/IP Sockets. The default port number used by VMODEM is 3141 (the first 4 digits of pi, unrounded). However, this default port number can be overridden by using the SERVICES file in the TCP/IP ETC directory. If the user defines a "Well Known Port" called "vmodem" (lower case) in the SERVICES file, then that port will be used instead of 3141. The port number 3141 has been assigned to the Virtual Modem Protocal (VMP) by the Internet Assigned Numbers Authority (IANA). The name associated with port 3141 is "vmodem" (without the quotes). The SIO.SYS command line If you do not already know what SIO.SYS is, you should start with the SIO Users Manual which should be a part of the same package that contained this manual. The changes to the SIO command line to define a Virtual Modem Port(s) is simple. All one does is to replace the I/O port number with the word "Internet" (without the quote marks). I/O port number are usually hexadecimal numbers like 3F8 (for COM1) and it is this number that is replaced with the word "Internet". A command line example for a Virtual Modem on COM2 that will only be accessed by native OS/2 programs is as follows: DEVICE=SIO.SYS (COM1) (COM2,INTERNET,NONE) The "NONE" in the above simply states that no IRQ is being used. 6 If one wishes to access the Virtual Modem from DOS and/or Windows sessions, the command line is a little more complicated. You must inform SIO where to present the information to the DOS/Windows session. That is, you must tell SIO (really VSIO) the virtual I/O port number and the virtual IRQ that the DOS/Windows application uses to access the port. Continuing to use COM2 as the example should be changed to: DEVICE=SIO.SYS (COM1) (COM2,INTERNET:2F8,NONE:3) This command line will present a standard COM2 to the DOS and or Windows session(s). 7 THE VIRTUAL MODEM Starting the Virtual Modem is about as simple as it can be. Simply type VMODEM or DETACH VMODEM at any OS/2 prompt, there are no command line parameters. VMODEM then just sits there and displays some minimal activity reports. If you do not wish to observe the VMODEM screen, use the command line DETACH VMODEM and execution will be completely in the background. Once started, and with the above mentioned additions to the SIO command line, application programs should see a relatively simple modem that implements a very basic set of AT commands. Most of the AT commands of a real modem simply do not apply in the environment that the Virtual Modem is being used in. For example, flow control is automatic (done by TCP/IP) so the virtual modem needs no flow control commands. Remember, the Virtual Modem has no memory, so any needed modem init string needs to be presented each time an application program is executed. AT Commands Supported ? Display a list of supported AT commands. DT Dial the following internet address. En Command mode local echo. E0 disables echoing, E1 enables echoing. Fn Local echo after connection. F0 enables (half duplex), and F1 disables. This command is currently disabled. Hn On/Off hook control. H0 or H alone to hang up, H1 go off hook. Sr=n Set S register r to n. The supported set of S registers is given below. Sr=? Display the current value (setting) of S register r. S? Display supported S register information. Z Virtual modem reset. &Cn Carrier detect operation, &C0 always on, &C1 normal. &Sn DSR operation, &S0 always on, &S1 normal. &V View virtual modem settings. 8 S Registers Supported S0 Zero disables automatic answer, non-zero enables automatic answer. S7 Number of seconds to wait for carrier (connection) when dialing. S19 Set inactivity timer (automatic disconnect) in minutes (0 disables). This S register is currently ignored by VMODEM. S38 Duration in seconds before disconnect when DTR drops. This S register is currently ignored by VMODEM. Result Codes NO CARRIER. This result is returned when a dialing timeout occurs or when an established connection terminates. The timeout interval is specified by S register 7. NO DIALTONE. This result code means that VMODEM could not obtain address information from the name server (or HOSTS file), or that the given Internet address is invalid. This result code is also returned if TCP/IP is not responding. BUSY. This result means that a connection to the vmodem port was established at the remote site. However, no available communications ports (COM1, COM2 etc) were available to assign the connection to. CONNECT 57600/ARQ/VMP. This result means the dialing and session establishment occurred without problems and is ready for user data flow. The given bit rate of 57600 is given only to satisfy the application program. The actual data rate is not know to VMODEM. RING. This result means that an incoming connection has been made with a remote system and that the local VMODEM is sending a ring indication to the assigned communications port (COM1 etc). RINGING. This result means that an outgoing connection has been made with a remote system and that the remote VMODEM is sending a ring indication to the communications port. 9 Caveats The command mode escape sequence, usually +++, is not implemented by the Virtual Modem. Once the Virtual Modem enters data mode, the only way to return to command mode is to drop DTR. This is why the DTR override AT command is not supported. Implementation of the escape (+++) feature would have a severe impact on processor overhead and Virtual Modem throughput. Numeric result codes are not currently implemented, they may be at a future time. Some application programs (like ProComm) translate letters into numbers. I have not found a way to use ProComm's dialing directory to pass alphebetic strings like those used in Internet addresses. Other applications (like TE/2) will pass alphabetic strings when they are enclosed in double quotes. Thus, an Internet address can be entered into TE/2's dialing directories in the form "vmbbs.xyz.com". The trailing quote is not really necessary as a trailing carriage return will also terminate the address. Dialing Examples Vmodem will translate any "*" (asterisk) in the dialing string to a "." (dot). Some terminal programs refuse to pass the dot, but should pass the asterisk because it is a valid dialing digit. The following are a few dialing examples to numeric type internet internet addresses. ATDT199.100.191.2 Bob Juge in Houston Texas ATDT 199.67.41.2 PCBOARD, Clark Development ATDT 199*3*36*205 Steve Schmidt in Chicago Illinois atdt198.96.20.209 Steven Bonisteel in Canada ATDT194*70*36*10 Jon Morby in England 10 The following are a few dialing examples to non-existent internet addresses using host hames. At least I believe they do not exist. ATDT vmbbs.gwinn.com ATDTvmbbs.internet.com ATDP "BBS.INTERNET.COM" ATDT VMBBS.INTERNET.COM ATDT vmbbs.internet.com 1234 In the above example, the user is specifying a port override. Normally VMODEM will attempt a connect on port 3141 (the official port for vmodem). In this case, the dialer is telling VMODEM to use port 1234 instead of 3141. 11 Telnet VMODEM implements a Telent server meaning that inbound Telent connections are accepted. The "well know name" for the Telnet server is VMOTelnet. The default port is the standard Telnet port, 23. The port used by the Telnet server can be changed by adding a line to the SERVICES file in your ETC and assigning VMOTelent to another port. This can also be done to disable the Telnet server part of VMODEM. IBM's Telnet Client IBM's Telnet seems to be a little finicky, but I did get it to connect and work with a VMODEM host. I executed IBM's Telnet with the following command line: telnet -t ANSI -c NONE In addition, after Telent loads I had to enter the following: toggle crlf BE SURE TO ENTER THE ABOVE COMMAND AFTER EXECUTING IBM'S TELENT. Things are really screwy if you do not. 12 THE VIRTUAL MODEM PROTOCOL The Virtual Modem Protocol (VMP) for Internet and other networks was designed with simplicity and performance in mind. Existing Internet protocols like TELNET were looked at, but found inhibiting, or downright unusable for the Virtual Modem implementation. The VMP is a bit over designed for the current implementation but is done so to allow for future expansion. I hope I have not re-invented the wheel, but at least we are off and running. The following specification is an attempt the define the VMP so that developers on platforms other that OS/2 will consider implementing the VMP. More to come when the protocol firms up. 13 Development and Debugging Tools The Poor Man's Line Monitor (PMLM.EXE) PMLM is basically of interest to developers of comm applications and those providing technical support for those applications. This SIO utility is released largely (in self defense) in the hope that some users can diagnose their own problems. PMLM's feature of saving trace information to disk will only work with registered and beta versions of SIO. PMLM provides basic line monitoring for OS/2, DOS and Windows comm programs. All characters sent or received by application programs are displayed in the upper portion of the screen. Receive characters are displayed as "white on blue" and transmitted characters are displayed "yellow on violet". Line signals, such as CTS are displayed as "dim white on red" when turned off and "bright white on red" when turned on. In addition, a signals transition to OFF is displayed in lower case and a signals transition to ON is displayed in upper case. Status information is displayed in the lower part of the screen. A bright white display means the signal is on, a dim white indicates that the signal is off. In addition, when bright, Rxoff and Txoff indicate the SIO has sent (Txoff) or received (Rxoff) an Xoff, and an Xon is pending. When a DOS or Windows session uses a comm port, an additional line of signal status appears. This status line shows the state of the virtual UART's signals. Only the signals which MAY be different from the real UART's signals are shown. "Rx Chars" and "Tx Chars" reflects the number of characters in SIO's receive and transmit buffers respectively. The last line on the screen shows the keys (from the keyboard) that PMLM will recognize. The bright character shows the key to hit for the associated function. The font keys will not work in a windowed OS/2 session. PMLM's command line requires one parameter, the comm port number, and optionally accepts an additional parameter giving a save trace file name. For example, PMLM 1 COM1INFO.TEC will monitor COM1 and save ALL of the communications traffic in the file COM1INFO.TRC. The trace files created by PMLM contain exactly the same information that is displayed by PMLM, video attributes and all. 14 VIEWPMLM.EXE may be used to view trace files created by PMLM. VIEWPMLM.EXE requires one parameter, the trace file name. The user can use the keys UP, DOWN, PAGEUP, PAGEDOWN, HOME, and END to navigate the saved trace file. Registered SIO users may send VIEWPMLM.EXE (along with saved trace files) to anyone for technical support purposes. VIEWPMLM can be used in native DOS, in DOS sessions under OS/2, and in OS/2 sessions. This means that even those developers and support people need not have OS/2 to view the captured communications data created by PMLM. SIO's Utility (SU.EXE) This utility program has several useful commands. You can obtain a list of the available commands by typing SU at any command line prompt without any parameters. One very useful command is SU IRQS. This command will show IRQs that currently free for use. Commands are provided allowing user control (missing from MODE) are available. Status commands provide a wealth of diagnostic information. 15 Appendix A, Hardware Port and IRQ Assignments I have obtained the following information from various sources. Accuracy is not guaranteed. In fact, nothing in this document is guaranteed. Addresses and IRQs for COM1 and COM2 COM1 uses 03F8h and IRQ4 COM2 uses 02F8h and IRQ3 Defacto standard for COM3 and COM4 for PC, XT and AT COM3 uses 03E8h and IRQ4 COM4 uses 02E8h and IRQ3 Addresses and IRQ for COM3 through COM8 on the PS/2 COM3 uses 3220h and IRQ3 COM4 uses 3228h and IRQ3 COM5 uses 4220h and IRQ3 COM6 uses 4228h and IRQ3 COM7 uses 5220h and IRQ3 COM8 uses 5228h and IRQ3 All PCs (known to the author) prior to the PS/2 and EISA only use 10 bits to address hardware I/0 ports. Systems prior to the PS/2 and EISA can not address the standard PS/2 addresses for COM3 through COM8. If an AT or below attempts to address COM3 through COM8 using the PS/2 addresses, only the low 10 bits of the address are used. That is, the high 6 bits of the address will be ignored by the hardware. This means that any reference to COM3 through COM8 will actually address ports 220h through 22Fh on older PCs. One should avoid expansion boards that use ports 220h through 22Fh unless the expansion board is a serial I/O board. SIO will (attempt to) determine the hardware architecture (ISA/EISA and PS/2) that it is being executed on and use the appropriate hardware port addresses for COM1 thru COM4 as defaults. 16 Index Addresses and IRQ for COM3 through COM8 on the PS/2 . . . . . 15 Addresses and IRQs for COM1 and COM2 . . . . . . . . . . . . 15 Appendix A, Hardware Notes . . . . . . . . . . . . . . . . . 15 AT Commands Supported . . . . . . . . . . . . . . . . . . . . . 7 BBS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 Caveats . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Defacto standard for COM3 and COM4 . . . . . . . . . . . . . 15 Default port number . . . . . . . . . . . . . . . . . . . . . . 5 Development and Debugging Tools . . . . . . . . . . . . . . . 13 Dialing Examples . . . . . . . . . . . . . . . . . . . . . . . 9 Distribution . . . . . . . . . . . . . . . . . . . . . . . . . 2 GETTING IT GOING . . . . . . . . . . . . . . . . . . . . . . . 5 IBM's Telnet Client . . . . . . . . . . . . . . . . . . . . . 11 Ordering . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 PMLM.EXE . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Result Codes . . . . . . . . . . . . . . . . . . . . . . . . . 8 S Registers Supported . . . . . . . . . . . . . . . . . . . . . 8 SIO's Utility (SU.EXE) . . . . . . . . . . . . . . . . . . . 14 Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 TCP/IP Required . . . . . . . . . . . . . . . . . . . . . . . . 5 TCP/IP Sockets . . . . . . . . . . . . . . . . . . . . . . . . 5 Telnet . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 The SIO.SYS command line . . . . . . . . . . . . . . . . . . . 5 THE VIRTUAL MODEM . . . . . . . . . . . . . . . . . . . . . . . 7 VIEWPMLM.EXE . . . . . . . . . . . . . . . . . . . . . . . . 14 VIRTUAL MODEM PROTOCOL . . . . . . . . . . . . . . . . . . . 12 WHAT IS VMODEM . . . . . . . . . . . . . . . . . . . . . . . . 1