jmodem_c.doc

JMODEM executes best from a batch file as an external pro- tocol for any of the communications pro

                                  J M O D E M
                         *  The Microsoft C Version  *
                               November 28, 1991
                               Richard B. Johnson
                              405 Broughton Drive
                          Beverly Massachusetts 01915
                               BBS [phone]

          Introduction.

          JMODEM was first introduced about two years ago. It has en-
          joyed a steady increase in popularity around the world. It
          has even been explained in some detail in John Dvorak's book
          on PC communications; Dvorak's Guide to PC Telecommunica-
          tions, 1990, Osborne-McGraw-Hill, 2600 Tenth Street,
          Berkeley, CA.

          JMODEM was first written in assembly language. Since this
          language is hard to read and use, it has been difficult for
          communications program developers to incorporate it into
          their programs directly. Instead it must be executed as an
          external protocol. Now JMODEM has been written in the C
          Language. C has become the de-facto standard for portable
          code development even though there isn't presently any code
          that is truly portable across many different machines. The
          writing of JMODEM in C will make it easier for software de-
          velopers throughout the world to use this very useful pro-
          tocol.

          You can use this new version of JMODEM just as the older
          versions written in assembly. It has a new color sign-on
          screen and status-block windows that overlap. Although the
          new JMODEM.EXE code is larger than the assembly-language
          version, JMODEM.COM, the program still executes very fast
          because much effort has been taken to streamline the C code.
          JMODEM.COM required 64 k of RAM (one segment) to execute
          properly. JMODEM.EXE requires 79 k to allow the screens to
          be written properly, and 66 k of free RAM to execute without
          aborting although the previous screen content will be lost.
          Like all versions of JMODEM, this version is 100% compatible
          with all previous version including Beta version 1.00. From
          it's inception, the essential structure of JMODEM has never
          been changed.

          How to install JMODEM.

          JMODEM executes best from a batch file as an external pro-
          tocol for any of the communications programs that have ex-
          ternal-protocol capability. A typical communications program
          is TELIX.







                                     - 1 -

                                               JMODEM, the C Version



          Here is a batch file used with TELIX for uploads:

          @ECHO OFF
          Rem * JMODEM TELIX Upload batch file.
          C:\TELIX\JMODEM S1 %3
          Rem           | ||  |_________ file name (passed by TELIX)
          Rem           | ||____________ COM port (1 - 4)
          Rem           | |_____________ Send
          Rem           |_______________ Path and name of JMODEM


          This is a batch file used with TELIX for downloads:

          @ECHO OFF
          Rem * JMODEM TELIX Download batch file.
          C:\TELIX\JMODEM R1 %3
          Rem           | ||  |_________ file name (passed by TELIX)
          Rem           | ||____________ COM port (1 - 4)
          Rem           | |_____________ Receive
          Rem           |_______________ Path and name of JMODEM


          This is a batch file used for PCPLUS (PROCOMM) uploads:

          @ECHO OFF
          Rem * JMODEM PCPLUS Upload batch file.
          C:\TELIX\JMODEM S1 %1
          Rem           | ||  |_________ file name (passed by PCPLUS)
          Rem           | ||____________ COM port (1 - 4)
          Rem           | |_____________ Send
          Rem           |_______________ Path and name of JMODEM


          This is a batch file for PCPLUS (PROCOMM) ownloads:

          @ECHO OFF
          Rem * JMODEM PCPLUS Download batch file.
          C:\TELIX\JMODEM R1 %1
          Rem           | ||  |_________ file name (passed by PCPLUS)
          Rem           | ||____________ COM port (1 - 4)
          Rem           | |_____________ Receive
          Rem           |_______________ Path and name of JMODEM












                                     - 2 -

                                               JMODEM, the C Version


          If I wished to receive in the "batch" mode, I could make a
          file like this. Notice that some communications programs do
          not allow multiple file names. Note that the comments "!"
          are NOT ALLOWED in a DOS batch file.

                        :DO_LOOP                   ! Return here
                        IF "%3" == "" GOTO DONE    ! More parameters?
                        C:\TELIX\JMODEM R1 %3      ! Execute JMODEM
                        IF ERRORLEVEL 1 GOTO DONE  ! Abort on error
                        SHIFT                      ! %4 becomes %3
                        GOTO DO_LOOP               ! Continue
                        :DONE                      ! Exit batch file

          If you do not know what "%" parameters are used to pass the
          file name, all you have to do is make a "dummy" batch file
          that contains the following:

                        @ECHO OFF
                        ECHO %1
                        ECHO %2
                        ECHO %3
                        ECHO %4
                        ECHO %5
                        PAUSE

          When this is executed, you will see something like this:

                1200
                1
                FILENAME.TYP
                ECHO is off
                ECHO is off
                Strike a key when ready . . .

          The first line contains "1200" which is the baud rate. This
          means that the %1 parameter contains the baud rate.

          The second line contains "1" which is the communications
          adapter port being used. This means that the port is being
          passed as the %2 parameter.

          The third line contains "FILENAME.TYP" which is the file
          name. This means that the file name is being passed as the
          %3 parameter.

          The fourth and fifth lines contain nothing to echo so DOS
          replies the current state of the echo function which is
          "off".

          PCPLUS handles the file name passing a little bit different.
          If I execute the same "dummy" batch file from the PCPLUS
          directory, the response is:



                                     - 3 -

                                               JMODEM, the C Version



                FILENAME.TYP
                ECHO is off
                ECHO is off
                ECHO is off
                ECHO is off
                Strike a key when ready . . .

          This shows us that PCPLUS passes the file name as the first
          parameter and there are no other parameters. However, If I
          put more parameters on the command line within PCPLUS, they
          will get sent to the batch file. The response is:

                FILENAME.001
                FILENAME.002
                FILENAME.003
                FILENAME.
                ECHO is off
                Strike a key when ready . . .

          Therefore PCPLUS allows up to four file names to be passed
          providing there's room on the command line.

          Notice that these two communications programs check the
          default directory for the external protocol batch file
          FIRST! Therefore you must make certain that there are no
          other similarly-named batch files in the current directory
          or within the current path. Failure to do so will cause the
          improper execution of the wrong batch file. Lets say that
          the path was "C:\DOS;C:\TOOLS;C:\PCPLUS;C:\TELIX;C:\QMODEM".
          If you named all your JMODEM external protocol batch files
          with the same name, and you were attempting to use an ex-
          ternal file transfer protocol from QMODEM, the batch file
          designed to operate with PCPLUS would be the first one
          "found" and executed since the search-path will search the
          \PCPLUS directory before the \QMODEM directory. You prevent
          the execution of the incorrect batch file by calling them
          slightly different names.

          When setting up external protocols, remember to configure
          the communications program so that it prompts you for the
          file names. Unlike some protocols, JMODEM does not transfer
          the file name. You can use any file name that you wish. You
          must pass the file name to JMODEM since it must know the
          name of the file being transmitted or received. There are no
          defaults.

          Version V3.09 adds support for absolute port addresses and
          IRQ numbers. This allows one to use multiple boards that use
          strange ports and interrupt levels. This also allows one to
          thoroughly screw up his system by writing to the wrong ports




                                     - 4 -

                                               JMODEM, the C Version


          by accident. JMODEM now accepts:

                JMODEM R(3F8:4) filename.typ

                ... for an input string as well as the generic port
          number. In this case, "3F8" is the hexadecimal port address
          and "4" is the IRQ number. The delimiters are required. Be
          very careful when using this new feature. Writes to incor-
          rect port addresses can destroy the contents of hard disks,
          etc. JMODEM has no way of "knowing" if you give it the wrong
          address to use. The complete input specification for the new
          feature is:

                JMODEM R(2F8:3) filename.typ
                       |   | |  |____________ filename
                       |   | |_______________ IRQ to use
                       |   |_________________ hex port address
                       |_____________________ Receive.

                JMODEM S(2F8:3) filename.typ
                       |   | |  |____________ filename
                       |   | |_______________ IRQ to use
                       |   |_________________ hex port address
                       |_____________________ Send.

          There must be no spaces between the "X(YYY:Z)" syntax. This
          means that if your batch file gets its parameters from an
          environment variable, it must be parsed like this:

                JMODEM S(%PORT%:%IRQ%) %3

          In this case, the two environment variables would have been
          declared using the DOS "SET" command like:

          C:\> SET PORT=3F8
          C:\> SET IRQ=4

          There must be no spaces between the "=" and the varable.

















                                     - 5 -

                                               JMODEM, the C Version


                            Setting up a BBS System
                        External File-Transfer Protocol.


          If you are running a WILDCAT! bulletin board, the external
          protocol files can be set up like this:

                        (JUP.BAT)
                        CD D:\WILDCAT\PROTOCOL
                        IF EXIST TRANSFER.BAD DEL TRANSFER.BAD
                        JMODEM R1 %3
                        IF ERRORLEVEL 1 GOTO END