home *** CD-ROM | disk | FTP | other *** search
/ DP Tool Club 14 / CD_ASCQ_14_0694.iso / maj / 4151 / zmsrc.doc < prev    next >
Text File  |  1994-03-22  |  9KB  |  163 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.                            ZMODEM SOURCE CODE DOCUMENTATION
  7.  
  8.           Introduction
  9.  
  10.                The Zmodem source code that makes up TXZM originated as a
  11.           project to add all the common protocols to the MCOMM Async
  12.           Library.  Due to other responsibilities, I have had to put the
  13.           project on hold but have completed enough of it to be useful. 
  14.           The code is 100% functional and very efficient.  The
  15.           documentation leaves a lot to be desired -- this is it.  The
  16.           present code is fairly easy to use in spite of the impression you
  17.           may get when you look at the TXZM.C source file.  The following
  18.           documentation in conjunction with the source code will enable you
  19.           to use the code as long as you know something about what you are
  20.           doing.  
  21.  
  22.           Restrictions
  23.  
  24.                The code and libraries for the SERIAL and VIDEO functions in
  25.           the registered version of MCOMM may not be distributed in whole
  26.           or in part.  This includes all the COMM_?.LIB libraries and all
  27.           source code that pertains to the serial I/O or video functions. 
  28.           End user programs developed using those libraries, however, may
  29.           be distributed and are completely royalty free.
  30.  
  31.                The ZMODEM code that makes up TXZM and is part of the
  32.           registered version of MCOMM (zmdos.c, zfunc.asm, batch.c, and
  33.           xyzgen.c) also MAY NOT be distributed, nor any libraries
  34.           distributed that were created with those source codes other than
  35.           the small model library that is in the shareware version of
  36.           MCOMM.  You may use the code in any non-competing software
  37.           product without royalty.  You may use any of the non-ZMODEM
  38.           specific functions (ZMODEM specific functions are those contained
  39.           in zmdos.c and zfunc.asm) that are part of the TXZM demo without
  40.           royalty for any end user programs developed.  You MAY NOT
  41.           distribute ANY of the TXZM demo other than as provided in the
  42.           shareware versions and then only with all accompanying files that
  43.           make up the shareware product.  Specifically prohibited is use of
  44.           this ZMODEM source code, in whole or in part, to enhance a
  45.           competitor's communications library (this includes DOOR libraries
  46.           and communication libraries developed for other languages or
  47.           operating systems).  As long as you stick with end user
  48.           applications that are not specifically and primarily a protocol
  49.           driver, you are not required to pay any royalties.  Fully
  50.           developed terminal programs such as Procomm, Telix, Crosstalk,
  51.           etc. are not primarily protocol drivers and therefore are NOT
  52.           considered competing products.  Neither are BBS systems, mail
  53.           doors (not mail door libraries), or similar products considered
  54.           competing products with TXZM.
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.           Disclaimer
  62.  
  63.                In regard to the MCOMM Async Library, the ZMODEM code that
  64.           makes up TXZM is provided as a demo -- not as a integral part of
  65.           the product.  If you can use it, it is there.  If you can't, I
  66.           will attempt to answer any reasonable questions but due to the
  67.           complexity of the code, the lack of precise documentation I have
  68.           been able to develop, and the wide range of skill levels of
  69.           programmers, I cannot provide unlimited support.  This limited
  70.           documentation and the TXZM source code is all you get.  It is up
  71.           to you to figure out what to do with it.  This does not apply to
  72.           the serial library itself -- only the zmodem code.  
  73.  
  74.           How it Works 
  75.  
  76.                TXZM.C is a shell for the real zmodem driver code.  This
  77.           module does nothing more than provide a means of generating the
  78.           list of file names to be transferred and handling messages from
  79.           the low level zmodem code.  It's complex appearance is due to the
  80.           added functions not normally considered part of zmodem itself
  81.           such as the ability to create and recurs subdirectories, the
  82.           terminal mode, shell to DOS, DesqView and DoorWay support, etc. 
  83.           Another factor in its apparent complexity is the elaborate (at
  84.           least more elaborate than usual) means of displaying file
  85.           transfer status combined with an attempt to keep from linking in
  86.           the floating point system for calculations that really could use
  87.           floating point math.  
  88.  
  89.                This implementation of zmodem requires you set some initial
  90.           flags and variables such as current baud rate, what to do in the
  91.           event of a file name collision when receiving, etc., and then
  92.           call either ZSendFile or ZRecvFile.  From then on the low level
  93.           code takes over.  Your application then must handle (or ignore)
  94.           messages generated by the low level code.  This messages are
  95.           directed to a function you must have in your program called ZMsg. 
  96.           Messages are generated at the end of every file and block, when
  97.           errors occur, when zmodem headers are sent or received, when a
  98.           name clash occurs, when the code is setting waiting for
  99.           characters or the transmit buffer to empty, etc.  The low level
  100.           code itself puts NOTHING on the screen.  That is the function of
  101.           ZMsg.  ZMsg also can do special handling in the event of name
  102.           collisions and during initialization of a file transfer.  When
  103.           ZMsg is called a number of global variables are available and are
  104.           used to determine status and display messages.  For specifics,
  105.           refer to TXZM.C and ZMDOS.H.  (Functions in TXZM.C except 'main'
  106.           appear in alphabetic order).
  107.  
  108.                The low level zmodem code was developed using Chuck
  109.           Forsberg's Zmodem documentation and by referring to his public
  110.           domain zmodem source code for Unix.  It is not a simple "port" of
  111.           his code, however.  I used the documentation and the source to
  112.           extract the logic of what was going on and completely rewrote
  113.           most of it.  This version has no goto's, is very streamlined and
  114.           straight forward, uses tables, block I/O, and a little assembler
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.           to speed things up, and has several enhancements.  There are both
  122.           ASM and C versions of three of the key functions.  Both the ASM
  123.           and C versions are identical functionally.  They are the function
  124.           to receive a block (ZRecvPacket), the function to send a block
  125.           (ZTxBlock), and the function to receive a character with zmodem
  126.           processing (ZRxChar).  To use the C version, define NO_ASM on the
  127.           command line when compiling ZMDOS.C (this requires you have the
  128.           source which comes with the registered version of MCOMM).  If you
  129.           are a C programmer and want to see what the ASM is doing, you can
  130.           look at the C version in ZMDOS.C.  The C version of the code is
  131.           only capable of running at around 80000 baud on an 8 MHz 286
  132.           whereas the assembler version will run at 110000 baud.  The
  133.           assembler version is what is in the MCOMM shareware demo.
  134.  
  135.                The TXZM demo will compile with MSC, Borland or Turbo C, and
  136.           Zortech C.  The 3 assemblerized functions will assemble with
  137.           either MASM or TASM.  All code can be generated for any memory
  138.           model, except the ASM will not work with a Borland C or TC HUGE
  139.           model program.  They do funny stuff with the DS register in their
  140.           HUGE model and I didn't want to work around it.  To compile the
  141.           shareware demo:
  142.  
  143.                Borland or Turbo C
  144.  
  145.                     tcc
  146.                     bcc txzm.c xyzgen.c zcmplr.c zmlib_s.lib comm_s.lib
  147.  
  148.                Microsoft C or Quick C
  149.  
  150.                     qcl
  151.                     cl txzm.c xyzgen.c zcmplr.c /link zmlib_s comm_s
  152.  
  153.                Zortech C
  154.  
  155.                     ztc -b txzm.c xyzgen.c zcmplr.c zmlib_s.lib comm_s.lib
  156.  
  157.                If you use either Borland's or Zortech's compilers be sure
  158.           and run the conversion batch file documented elsewhere in the
  159.           MCOMM async package to convert the comm_s.lib to work with your
  160.           compiler.  As distributed, before conversion, comm_s.lib is for
  161.           MSC or QC.
  162.  
  163.