jmodem_c.doc

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

                                     - 11 -

                                               JMODEM, the C Version


                           The JMODEM Communications
                                Hardware Control

          When JMODEM is first loaded for execution it checks the
          state of the modem-control leads. If there is no modem
          carrier detected, it assumes that you have connected two PCs
          together without a modem and will not bother to check for a
          dropped carrier during execution.

          Since JMODEM must exercise flow-control so it can be used
          with high-speed modems with fixed baud rates, it also as-
          sumes that at the time at which it is first executed, the
          modem will be requesting data because there will have been
          very little I/O over the previous few seconds. JMODEM stores
          the state of RTS/CTS and DTR/DSR and uses this as a refer-
          ence. When transmitting data, should JMODEM find that the
          state of these modem-control leads has changed, it waits
          until the modem-control leads have reverted back to the
          initial state before sending any more data. This allows ANY
          modem to exercise flow-control with JMODEM, even those that
          use "pin 4" instead of "pin 20". When JMODEM is waiting, it
          checks to verify that the modem carrier has not been drop-
          ped. If the carrier is dropped, or if the user aborts,
          JMODEM will exit, setting a DOS ERRORLEVEL code.

          You can abort JMODEM at any time by hitting Ctrl-Break or
          Ctrl-C. It will take several seconds for JMODEM to abort
          because it does not continually check these keys. Unlike
          previous versions, JMODEM erases the files from aborted
          downloads. Also, JMODEM will abort if it is unable to rename
          a file in the following example.

          Suppose you wish to download a file called VIRUS.EXE. Sup-
          pose also that VIRUS.EXE already exists. Instead of over-
          writing your previous version of VIRUS.EXE, JMODEM has al-
          ways been nice and renamed it to VIRUS.OLD before creating a
          new file. With previous versions of JMODEM, if VIRUS.OLD
          already existed, JMODEM would have deleted it before renam-
          ing the present file to ".OLD". This no longer is done.
          JMODEM never deletes ANYTHING anymore except it's own abort-
          ed download. This should reduce the number of threats I have
          received!













                                     - 12 -

                                               JMODEM, the C Version


                               The C programmer's
                                Guide to JMODEM

          Included within this package should be the following files:
          JMODEM         This is a Microsoft MAKE file for JMODEM.EXE.
          JMODEMTC       Borland's Turbo C MAKE file for JMODEM.EXE.
          JMODEM    EXE  The executable file
          JMODEMTC  RSP  Link response file for Borland's Turbo C
          JMODEM_A  C    Contains the _main() routine entry point.
          JMODEM_B  C    Parses input strings.
          JMODEM_C  C    All of the file I/O is in this file.
          JMODEM_D  C    Data compression/expansion, CRC calculation
          JMODEM_E  C    Communications I/O interrupt service, etc.
          JMODEM_F  C    Screen I/O (windows, etc)
          JMODEM_G  ASM  Interrupt service routines (after V2.00)
          JMODEM    H    Contains JMODEM globals and data structures.
          SCREEN    H    Screen definitions, prototypes, structures
          UART      H    Definitions for the 8250 UART
          TEST      C    This tests compression /expansion, disk I/O.
          TEST           This is the Microsoft MAKE file for TEST.EXE
          TESTTC         Borland's Turbo C MAKE file for TEST.EXE
          SHOW      C    Source for verifying execution in a DOS shell
          SHOW           Microsoft MAKE file for SHOW.EXE
          SHOWTC         Borland's Turbo C MAKE file for SHOW.EXE
          SHOW      EXE  Executes JMODEM from a DOS shell.
          TEST      C    Tests JMODEM data-compression and file I/O.
          TEST           Microsoft MAKE file for TEST.EXE
          TESTTC         Borland's Turbo C MAKE file for TEST.EXE
          TEST      EXE  Executable to test file I/O and compression

          If you have MicroSoft 'C' version 5.0 or later, and if your
          environment and paths are properly set up, you should be
          able to type:

                MAKE JMODEM
                ... and a brand new version of JMODEM will be created.

          If you use Borland's Turbo C, you can use the "TC" make
          files to do the same.

          Brad Smith from Jacksonville North Carolina created the MAKE
          files for Turbo C and modified the source-code to accommo-
          date the different libraries used in Turbo C. His revisions
          will be present in all subsequent versions of JMODEM to
          assure compatibility with Borland's Turbo C.

          Brad is a Turbo C guru and runs a BBS system in
          Jacksonville.

                Brad Smith
                141 Riggs Street
                Jacksonville, North Carolina 28540
                BBS [phone] 12/24/9600+ 24 hrs


                                     - 13 -

                                               JMODEM, the C Version



          With this release, there seems to be a Null-Pointer
          assignment error when using Borland's Small Model in TCC
          Version 1.5. This is a compiler bug, or more specifically a
          bug in the C0.ASM code provided with the compiler that you
          can fix.

          If you are a Turbo C programmer, don't use the small model
          when creating JMODEM.EXE unless you repair the C0.ASM file
          and create a new C0S.OBJ file using the MAKE-C0.BAT file
          that is provided with the compiler.

          To fix the null-pointer problem in Turbo-C find the
          following code-fragment in \LIB\C0.ASM provided with your
          compiler:

          IFNDEF        __HUGE__

          ;     Reset un-initialized datas

                        xor     ax, ax
                        mov     es, cs:DGROUP@@
                        mov     di, offset DGROUP: bdata@
                        mov     cx, offset DGROUP: edata@
                        sub     cx, di
                rep     stosb
          ENDIF

          Add the following code:

                push    ds
                mov     ax,DGROUP
                mov     ds,ax
                mov     word ptr ds:[0],0
                pop     ds


          Now find this next code-fragment:

                        xor     ax, ax
                        mov     si, ax
                        mov     cx, lgth_CopyRight
                        cld
          ComputeChecksum label near
                        add     al, [si]
                        adc     ah, 0
                        inc     si
                        loop    ComputeChecksum
                        sub     ax, CheckSum
                        jz      ExitToDOS
                        mov     cx, lgth_NullCheck




                                     - 14 -

                                               JMODEM, the C Version


                        mov     dx, offset DGROUP: NullCheck
                        call    ErrorDisplay

          Modify the code so it looks like this:

          ;             xor     ax, ax
          ;             mov     si, ax
          ;             mov     cx, lgth_CopyRight
          ;             cld
          ;ComputeChecksum label        near
          ;             add     al, [si]
          ;             adc     ah, 0
          ;             inc     si
          ;             loop    ComputeChecksum
          ;             sub     ax, CheckSum

                push    ds
                mov     ax,DGROUP
                mov     ds,ax
                cmp     word ptr ds:[0],0
                pop     ds

                        jz      ExitToDOS
                        mov     cx, lgth_NullCheck
                        mov     dx, offset DGROUP: NullCheck
                        call    ErrorDisplay


          After to have done this, execute MAKE-C0.BAT for the small
          model library from the DOS prompt:

          F:\TURBOC\LIB> MAKE-C0 SMALL

          This will create a new small-model startup object file.

          Just as in the MASM language files, the source code is
          strongly-typed. All function prototypes are declared and no
          defaults are used. You can compile at warning-level 4, the
          most stringent level available with Microsoft compilers, and
          you will get no warning errors at all. The default warning
          level with Borland's compiler is even more stringent. You
          will get a single warning error when compiling TEST.C as the
          compiler discovers that dummy parameter "one" in the dummy
          screen routine isn't used at all. It has been my experience
          that if you get any warnings (in real code), they MUST be
          fixed or they will bite you later on.

          Example:
                        *memory++ = foo;
                ... will bump the memory pointer after you put foo
                into memory. Suppose you get to the end of the block




                                     - 15 -

                                               JMODEM, the C Version


                and wish to index backwards.

                Do you use ...
                        --*memory = foo;
                ...?

                You do NOT!! You must use:

                        *(--memory) = foo;

          Little things like this (this is a BIG, BIG bug), could
          cause code to work <sometimes> and keep you awake nights.
          JMODEM has been carefully written to prevent bugs like this.
          It is impossible to be sure that there are no bugs in even
          simple code so be careful if you modify the source.

          You may modify JMODEM for your own use, but  P L E A S E  do
          NOT distribute the modified version on BBS systems because I
          do not wish to support 222,500 versions of JMODEM! If you
          find a bug, or wish to improve or add something that will
          increase the value of JMODEM without making it incompatible
          with previous versions, please upload your improvements to
          my BBS system and I may include the revisions (with your
          name attached) in an upcoming version. Note that there are 6
          "type" bits available in the JMODEM control-byte that could
          be used to tell the receiver that another file is coming,
          etc., (for batch). Things like this could be added without
          destroying compatibility with previous versions.

          MicroSoft C seems to have several bugs one of which affects
          files that are very long (over 256k). My first attempts to
          use C files under MicroSoft for JMODEM used the stream-I/O
          (FILE *) type of files. This resulted in corruption of long
          files. Therefore I implemented the UNIX/DOS type of file-I/O
          that uses handles rather than file-control blocks. These
          work rather well.

          Starting with Version V3.06, The JMODEM distribution file
          will no longer contain the old JMODEM.ASM source. This is to
          reduce the download time. The C version is now mature enough
          so that there is little or no difference between the per-
          formance of JMODEM.COM, the assembly version, and