jmodem_c.doc

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

                        COPY %3 %4
                        :END
                        DEL %3

                        (JDOWN.BAT)
                        CD D:\WILDCAT\PROTOCOL
                        IF EXIST TRANSFER.BAD DEL TRANSFER.BAD
                        JMODEM S1 %3
                        IF ERRORLEVEL 1 GOTO BAD
                        GOTO END
                        :BAD
                        COPY ALL.OK TRANSFER.BAD
                        :END

          There are many variations available. Since WILDCAT! supports
          batch-mode downloading, you could set up the batch file like
          this:

                        (JDOWN.BAT)
                        CD D:\WILDCAT\PROTOCOL
                        IF EXIST TRANSFER.BAD DEL TRANSFER.BAD
                        :DO_LOOP
                        IF "%3" == "" GOTO END
                        JMODEM S1 %3
                        IF ERRORLEVEL 1 GOTO BAD
                        SHIFT
                        GOTO DO_LOOP
                        :BAD
                        COPY ALL.OK TRANSFER.BAD
                        :END

          WILDCAT! checks the \PROTOCOL directory to see if the file
          TRANSFER.BAD has been created. If it exists, it announces
          that the file transfer has failed. It also announces "Error
          with external protocol .. ". It does this when, in fact,
          WILDCAT!  has made an error itself. In many cases WILDCAT!
          will "find" the file TRANSFER.BAD when it DOES NOT EXIST! In
          spite of this bug, WILDCAT! is one of the most reliable BBS
          systems supporting external protocols.




                                     - 6 -

                                               JMODEM, the C Version



          When setting up batch files remember that there is also a
          bug in all DOS versions. The "IF ERRORLEVEL " statement does
          NOT test the actual value of ERRORLEVEL! Instead it checks
          to see if the returned value is EQUAL or GREATER than the
          tested value. If you were to put the statement:

                        IF ERRORLEVEL 0 GOTO GOOD

          .... in a batch file, the execution would ALWAYS branch to
          label "GOOD" regardless of the actual ERRORLEVEL returned!

          JMODEM does not require any information about handshaking.
          It will look at the modem port and figure out for itself
          what to do.

          In the event that the modem carrier is lost, JMODEM will
          abort. Since JMODEM only checks the modem port occasionally,
          it may take several seconds to abort when the carrier is
          lost. It is impossible for a user to get at the DOS level
          through JMODEM. Do NOT use the CTTY command in the external
          protocol batch files. JMODEM returns ERRORLEVEL 1 if there
          was any error in transmission or reception. It returns
          ERRORLEVEL 0 (no error) otherwise. It does not delete files
          that have been partially received although it properly clos-
          es them. The system operator can arrange the batch files to
          delete them if required.

          When JMODEM attempts to create a file that already exists it
          can't ask the user if the old one should be deleted since
          the user is probably not in a terminal program at the time.
          Therefore, JMODEM renames the other file to <filename.OLD>
          and creates the new file. In the event that <filaname.OLD>
          exists, it is deleted before the rename operation occurs.

          If you don't know what parameters are being sent to external
          protocols, you can make a dummy batch file to check them
          using the DOS's echo command just as explained in the user
          interface previous to this "BBS" section. You can't see the
          parameters being echoed from a remote terminal. You must be
          present at the BBS board terminal to test those parameters
          unless you modify the dummy command file like this:

                        @ECHO OFF
                        ECHO %1>COM1
                        ECHO %2>COM1
                        ECHO %3>COM1
                        ECHO %4>COM1
                        ECHO %5>COM1

          If you find that your system passes the file name as %3,
          your "upload" (receive) batch file would contain this:



                                     - 7 -

                                               JMODEM, the C Version



                        JMODEM R1 %3

          Your "download" (send) batch file would contain this:

                        JMODEM S1 %3

          In these examples, it is assumed that you are using
          communications adapter port "1".

          You can chop this text out with an editor and create your
          batch files quickly and correctly. PCPLUS passes the file-
          name as the %1 parameter and TELIX uses the %3 parameter.
          JMODEM does not need to know anything else about your system
          to operate. It does not even need to know the baud-rate or
          other communications parameters. All it needs to know about
          is the file name and the communications adapter port to use.

          JMODEM doesn't care if you are using a 19,200 baud modem
          with the DTE locked at high-speed or a 300 baud modem on a
          lamp-cord. It is very smart about communications and handles
          lost carriers (hangup) and flow-control in a very simple way
          which will be explained in detail later.

          If you only want to try JMODEM without having to install it,
          you need only to activate the JMODEM protocol on a BBS sys-
          tem, then "shell to DOS" and execute it manually from the
          DOS prompt. You will be pleasantly surprised at how rapidly
          it can transfer a file and how well it executes over net-
          works.

          How JMODEM works.

          JMODEM uses variable-length records called blocks. These
          blocks start with 512 data-bytes and increase in length to a
          maximum of 8192 bytes per block. There is a 6-byte overhead
          associated with each block so the percentage of overhead
          starts at a fairly high 0.1 percent and decreases to a very
          low 0.07 percent as the transmission progresses. The block
          length will increase in 512-byte increments as long as there
          are no errors requiring retransmission. Should an error
          occur, the block-size is cut in half. This continues until
          the block-size is as short as 64 bytes.

          The blocks may actually be of any length but never exceed
          the maximum allowed. An attempt is made to reduce the amount
          of data that needs to be transmitted by compressing each
          block before transmission. Since much data is already com-
          pressed, being from ".ZIP" files and such, it is possible
          that "compression" may actually cause an increase in block-
          length. JMODEM will send a compressed block only if it is
          shorter than the non-compressed block.



                                     - 8 -

                                               JMODEM, the C Version



          Since it takes time to compress and expand data, only the
          simplest and quickest compression method is used. It is very
          effective with ".EXE" files that contain large blocks of
          binary nulls and most text files but it is not very effec-
          tive with highly compressed archive files. The compression
          method is called "run-length-limited" or more explicitly
          "how many of what kind". Basically, the block is searched
          for groups if similar characters. If many similar characters
          are found, compression consists of sending a sentinel byte
          of hexadecimal BB, followed by a two-byte amount, and this
          followed by the byte to be repeated.

          In the following example we have a string of spaces (20
          hex).

          Before compression:
                               ( 18 bytes )
            20 20 20 20 20 20 20 20 20 20 20 34 37 87 EF FF 3A 23


          After compression:
                               ( 11 bytes )
            BB 0B 00 20 34 37 87 EF FF 3A 23

          The blocks could actually get longer because the sentinel
          byte could be present in the data:

          Before compression:
                               ( 9 bytes )
            BB 00 BB AF EF BB 00 AE EF


          After compression:
                               ( 16 bytes )
            BB 01 00 BB 00 BB 01 00 BB AF BB 01 00 BB AE EF

          As soon as the encoded length exceeds the data block length,
          compression is abandoned and the non-compressed block is
          sent. JMODEM sends a byte that tells the receiver if the
          data is compressed or not. This same byte tells the receiver
          when the end-of-file has occurred so JMODEM is able to
          preserve exact file-length.

                               The JMODEM block.










                                     - 9 -

                                               JMODEM, the C Version



          The JMODEM block looks like this:

           |< --------- First byte sent / received
          20 00 01 01 .. .. .. .. .. AE 01
           |  |  |  |        |        |  |___ CRC (high byte)
           |  |  |  |        |        |______ CRC (low byte)
           |  |  |  |        |_______________ data bytes
           |  |  |  |________________________ type of block
           |  |  |___________________________ block number
           |  |______________________________ block length (high byte)
           |_________________________________ block length (low byte)


          The Block length:

          The block length is a WORD (16 bits). This allows the blocks
          to be 65,535 bytes long although in practice the length is
          not allowed to exceed 8192 bytes (plus overhead). The block-
          length is the length of the entire JMODEM block, not just
          the data-bytes.

          The Block number:

          The block number is a BYTE. It starts at 1 and becomes zero
          again after block 255. It is used to make certain that all
          receiption errors are detected.

          The Block type:

          This BYTE is bit-mapped to tell the receiver what kind of
          block has been sent. Presently there are three kinds of
          blocks:

                00000000B       Hex 00  ( Normal data )
                00000001B       Hex 01  ( Compressed data )
                00000010B       Hex 02  ( End of file )

          The CRC:

          The CRC is a WORD (16 bits). It is not a "standard" type of
          CRC because, unless done with hardware, a standard 16-bit
          polynomial would take several seconds to calculate for a
          long block. Instead it uses a rapid rotate and sum algorithm
          that is probably just as effective as the more "standard"
          polynomials.

          The CRC is generated using this polynomial:

          X =  X + X^(2(n-mod 7)).......  Where n = t(n-1)
                                         And t = string length




                                     - 10 -

                                               JMODEM, the C Version



          It has the advantage of simplicity in assembly-language
          programming and will detect errors with a probability of
          about  one undetected error in 2^132 (which is a very large
          number). It does not correct errors so its not important to
          use some "standard" function to generate the CRC.

          The C code shows how easy it is to create and check this
          kind of CRC.