home *** CD-ROM | disk | FTP | other *** search
/ Programmer 7500 / MAX_PROGRAMMERS.iso / PASCAL / PROT018S.ZIP / PROTENG.DOC < prev    next >
Encoding:
Text File  |  1993-02-03  |  20.8 KB  |  483 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.     Copyright  1993 Mark Dignam and Mick Howland - Omen  Computer  Services 
  7.              Perth Omen Bulletin Board System - 3:690/660@fidonet
  8.  
  9.  
  10.  
  11.                      The Protocol Engine for Turbo Pascal.
  12.  
  13.  
  14.        The EASY way to get your Turbo Pascal programs to transfer files!
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.                        T A B L E   O F   C O N T E N T S
  22.  
  23.  
  24.          Disclaimer . . . . . . . . . . . . . . . . . . . . . .  1.0
  25.           License Details . . . . . . . . . . . . . . . . . . .  1.1
  26.  
  27.          What is a Protocol Engine? . . . . . . . . . . . . . .  2.0
  28.           Objectives  . . . . . . . . . . . . . . . . . . . . .  2.1
  29.           Features  . . . . . . . . . . . . . . . . . . . . . .  2.2
  30.  
  31.          Contents of This Archive . . . . . . . . . . . . . . .  3.0
  32.  
  33.          Programming Details  . . . . . . . . . . . . . . . . .  4.0
  34.           Sending Files . . . . . . . . . . . . . . . . . . . .  4.1
  35.           Receiving Files . . . . . . . . . . . . . . . . . . .  4.2
  36.           External Hooks  . . . . . . . . . . . . . . . . . . .  4.3
  37.  
  38.          Dump of the Protocol Engine's Header . . . . . . . . .  5.0
  39.  
  40.          Release Details  . . . . . . . . . . . . . . . . . . .  6.0
  41.          
  42.          Idiosyncrasies . . . . . . . . . . . . . . . . . . . .  7.0
  43.  
  44.          Version History  . . . . . . . . . . . . . . . . . . .  8.0
  45.  
  46.          Contacting the Authors . . . . . . . . . . . . . . . .  9.0
  47.  
  48.  
  49.     1.0) DISCLAIMER
  50.  
  51.     This  software is provided without any guarantee, either  expressed  or 
  52.     implied.   All responsibilities for its use rest with the user  of  the 
  53.     software and not the author. 
  54.  
  55.     1.1) LICENSE AGREEMENT.
  56.  
  57.     The Protocol Engine is not in the Public Domain. The Protocol Engine is 
  58.     also not free.
  59.  
  60.     Non-registered users are granted a limited, 30 day license to determine 
  61.     whether  or  not the program meets their needs.  Continued use  of  the 
  62.     Protocol  Engine  beyond  the 30-day evaluation  time  period  requires 
  63.     registration  of  the  program.  Use of non-registered  copies  of  the 
  64.     Protocol  Engine  beyond  the original evaluation  period  is  strictly 
  65.     prohibited.
  66.  
  67.     The Protocol Engine may be copied and distributed to others, subject to 
  68.     the above restrictions and the following:
  69.  
  70.          Only the non-registered version may be copied and distributed 
  71.          to  others.  This contains only the pre-compiled  units,  the 
  72.          support source code files and the documentation.  These   are 
  73.          the  ONLY  files that may be copied freely. The  full  source 
  74.          code  for  the Protocol Engine MUST not  distributed  at  any 
  75.          time.
  76.  
  77.          The  Protocol  Engine  must be  copied  in  unmodified  form, 
  78.          including the file containing this license information.
  79.  
  80.          Complete documentation and support files must be included.
  81.  
  82.          No  copying fee of any type may be assessed other than  basic 
  83.          charges for the cost of the copying medium.
  84.  
  85.     Sysops  (bulletin board SYStem OPerators) may make the Protocol  Engine 
  86.     available  for  downloading  by  their  users  as  long  as  all  above 
  87.     conditions are met.
  88.  
  89.     Commercial Distributors of Public Domain, ShareWare, or  User-Supported 
  90.     software  may also distribute The Protocol Engine subject to the  above 
  91.     conditions.
  92.  
  93.     All parts of it, including the source code, the compiled TPU's and  the 
  94.     documents  will  remain copyright.  Any executable  programs  that  are 
  95.     created or compiled using either sections or all of The Protocol Engine 
  96.     are  for you to do with as you wish.  I do not wish a  royalty  payment 
  97.     for any of your executables, but a note to the effect that the Protocol 
  98.     Engine was used in a product would be appreciated.
  99.  
  100.     Please refer to the enclosed LICENSE.FRM for more information.
  101.  
  102.  
  103.     The following names are trademarks and/or registered names:
  104.  
  105.     Turbo Pascal                                  Borland International.
  106.  
  107.     Thanks for the code and/or designs:
  108.  
  109.     Micheal Quinlan                               Async4 Pascal Unit
  110.     Mark G. Mendel                                Crc16 Tables and UpdCrc
  111.     Stephen Satchell - Satchell Evaluations       Crc32 Design
  112.     Chuck Forsberg   - Omen Technology            The Ymodem and 
  113.                                                   Zmodem Protocols
  114.     Gary S. Brown                                 Crc32 tables
  115.     System Enhancement Assocaties                 The Sealink Protocol
  116.     Ward Christensen                              The Xmodem (original!) 
  117.                                                   Protocol
  118.      
  119.  
  120.  
  121.                              ABOUT PROTOCOL ENGINE
  122.  
  123.  
  124.     2.0) What is a Protocol Engine?
  125.  
  126.     It  is  a set of software routines that take all the hard work  out  of 
  127.     writing  communication software.  In this one easy-to-use Turbo  Pascal 
  128.     (versions  5,  5.5,  6,  7 and Borland Pascal 1.0)  Unit  are  ALL  the 
  129.     procedures  and functions required to transfer files from one  computer 
  130.     to  another. Various methods of error checking are available, that  are 
  131.     fully  compatible  with  the standard protocols  used  by  conventional 
  132.     terminal programs.
  133.  
  134.  
  135.     2.1) Objectives.
  136.  
  137.     Protocol Engine has been to designed to fufill two major objectives:
  138.  
  139.     a)  It  is very easy to use  for even the novice programmer.  This  was 
  140.     achieved  by  using  a small linked array of strings  to  transfer  the 
  141.     filenames  between  the main program and the unit and  then  calling  a 
  142.     simple Boolean function for each different method.
  143.  
  144.     b)  It has a low DataSegment overhead , while retaining large  Transmit 
  145.     and Receive buffers. It is suitable for Binkley/FrontDoor transfers and 
  146.     high  speed modem links. The current DataSegment use is less  than  5k,  
  147.     while still having up to 15k disk buffering.
  148.  
  149.  
  150.     2.2) Features.
  151.  
  152.     The  Protocol  Engine has support for Xmodem, Xmodem  with  1k  Blocks, 
  153.     Ymodem Batch, YmodemG Batch, Zmodem (both Crc16 and Crc32), Sealink and 
  154.     Yapp (a packet radio protocol).
  155.  
  156.     When  using  Zmodem method of transferring files, the  Protocol  Engine 
  157.     fully  supports crash recovery in both send and receive modes.  In  all 
  158.     batch modes, there is the option to overwrite or create a new file when 
  159.     receiving.
  160.  
  161.     Since  Protocol  Engine requires an asynchronous unit  to  handle  high 
  162.     speed  communications, a Comm unit is included with full  source  code. 
  163.     This unit is a modified version of the Public Domain ASYNC4. It handles 
  164.     both Fossil and Non_Fossil environments with ease at speeds upto  38400 
  165.     baud.
  166.  
  167.     The Protocol Engine also has "external hooks" defined to allow the  end 
  168.     programmer  to link in their own code into the Protocol  Engine.  These 
  169.     hooks will be called when certain events happen, as the Protocol Engine 
  170.     is  being executed. This allows the end user to further  customize  the 
  171.     look of the Engine, and insert more features into their own software.
  172.  
  173.     3.0) Contents of this Archive.
  174.  
  175.     ANSI_DRV.PAS   Source Code for a Ansi Screen Unit
  176.     PROTCOMM.PAS   A Half Decent Comms Unit.
  177.  
  178.     The  first two Files are support source code for the  Protocol  Engine. 
  179.     Users  are  free  to use these files as they wish. The  Ansi  unit  was 
  180.     written for another project. It may or may not have bugs - it works for 
  181.     me!  The  Comms unit is a very modified version of ASYNC4  with  Fossil 
  182.     Support and internal 16650 support.
  183.  
  184.     TERM.EXE   A quick Terminal program written using the Protocol Engine.
  185.     TERM.PAS   The source code for the above program.
  186.  
  187.     This demo program shows the use of the Protocol Engine. It has  all  of 
  188.     the  transfer  protocols in it, along with Ansi and  Doorway  emulation 
  189.     modes.
  190.  
  191.     The  next  three files are the Turbo Pascal units. The numbers  in  the 
  192.     extension  field are for the relevant version of Turbo Pascal. To  use: 
  193.     copy the version that relates to your compiler to Proteng.tpu!
  194.  
  195.     PROTENG.50S     Protocol Engine for Turbo Pascal 5.0
  196.     PROTENG.55S     Protocol Engine for Turbo Pascal 5.5
  197.     PROTENG.60S     Protocol Engine for Turbo Pascal 6.0
  198.     PROTENG.70S     Protocol Engine for Turbo Pascal 7.0 and 
  199.                              Borland Pascal 1.0
  200.  
  201.     PROTENG.DOC     This Document!
  202.     LICENSE.FRM     License Form - for registration.
  203.     PROTMAP.DOC     State Table of all the protocols.
  204.  
  205.     4.0) Programming Details.
  206.  
  207.     4.1) Sending Files.
  208.  
  209.     To  send a list of files, you must set up the transfer by first  giving 
  210.     the Protocol Engine the list of names to send. Simply call the function 
  211.     AddNameToList with the FULL path and filename included. If the function 
  212.     returns TRUE, the call was successful, and the name has been added onto 
  213.     the  heap, ready to send. If the function returns FALSE,  the  function 
  214.     couldn't allocate the memory to hold the full path. Since this list  is 
  215.     stored  in a linked array of strings the error usually only  occurs  if 
  216.     you run out of heap space.
  217.  
  218.     The only way out is to send the files that are stacked on the heap, and 
  219.     then send the remaining files, in a second transfer. 
  220.  
  221.     The  next  step  is to actually transfer the files.  Define  a  boolean 
  222.     variable  and  then  call the Protocol Engine, with  the  name  of  the 
  223.     protocol you wish to use. Eg:
  224.  
  225.     Goodtransfer := ZmodemTx;
  226.  
  227.     The  returned  value  will indicate COMPLETE success  or  failure.  The 
  228.     global  variable NumberOfFiles, will contain the total number of  files 
  229.     that  have been sent. If the transfer got aborted at some point midway 
  230.     through  the set, the Boolean will return as FALSE,  and  NumberOfFiles 
  231.     will indicate which file(s) were not successfully sent.
  232.  
  233.     4.2) Receiving files.
  234.  
  235.     Receiving  files is just as easy. First you set up the global  variable 
  236.     UploadPath.  This  MUST  contain the full path of where  you  wish  the 
  237.     received files to be saved. If you select a transfer mode that  doesn't 
  238.     send  the  filename (such as Xmodem or Xmodem1K) this  global  variable 
  239.     must hold the FULL filename, including path.
  240.  
  241.     You can disable or enable overwriting of existing files, by setting the 
  242.     global  variable  OverWrite. This also enables download  recovery  when 
  243.     using Zmodem.
  244.  
  245.     Then  it  is simply a matter of calling the required  protocol  with  a 
  246.     boolean variable to hold the success flag. Eg:
  247.  
  248.     GoodRx := ZmodemRx;
  249.  
  250.     When the function returns to you, the global NumberOfFiles will contain 
  251.     the  total  number of files that have been received  successfully.  The 
  252.     filenames  are  recovered  by  calling  the  GetNameFromList  procedure 
  253.     repeatly,  saving the names into your own array, until it returns  back 
  254.     that the name list is clear.
  255.  
  256.     4.3) The External Hooks.
  257.  
  258.     The  external  hooks have been provided to allow the programmer  a  bit 
  259.     more control of the file transfer.  There are three hooks provided:
  260.  
  261.     a)  StartOfFile. This will be called at the start of each file.  If  in 
  262.     transmit mode, or in a batch receive mode that supports file length, it 
  263.     will also contain the total bytes within the file.
  264.  
  265.     b) EveryBlock. This will be called, after every logical block has  been 
  266.     sent.  It  will  pass  the  current  byte  count  of  the  file   being 
  267.     transferred.
  268.  
  269.     c) EndOfFile. This will called at the end of each transfer, along  with 
  270.     the filename, and success of the transfer.
  271.  
  272.     To use the external hooks, you must define a procedure exactly the same 
  273.     as the ones in the header. ie:
  274.  
  275.     StartOfFile: _StartFile;            {Called at start of EVERY file}
  276.  
  277.     Then you need to write your procedure with the FAR option set ie:
  278.  
  279.     {$F+}
  280.     Procedure DummyStartOfFile(F : Str64; Fs : Longint);
  281.  
  282.     begin
  283.           { insert your code here!}
  284.           { and it will called at the start of EACH file transfer}
  285.     end;
  286.     {$F-}
  287.  
  288.     As  the last step - you need to set StartOfFile to your procedure  like 
  289.     this:
  290.  
  291.      StartOfFile := DummyStartofFile;
  292.  
  293.  
  294.     5.0) Dump of the Protocol Engine Header
  295.  
  296. {                                                                         }
  297. {  Copyright 1993 Mark Dignam - Omen Computer Services - Perth Omen BBS.  }
  298. {  This program ,including the source code MAY not be modified, changed   }
  299. {  or altered in any way without written permission of the author.        }
  300. {                                                                         }
  301. { Protocol Engine Main Module                                             }
  302.  
  303. Unit ProtEng;
  304.  
  305. INTERFACE
  306.  
  307. uses crt,dos,protcomm;
  308.  
  309. { This unit MUST use its own serial driver. It has very efficient i/o buffering}
  310. { but it will use a fossil driver, if one is found at run time.               }
  311.  
  312. Type
  313.    Str64    = String[64];             {A type which is used everywhere within }
  314.                                       {ProtEng for the passing of filenames   }
  315.  
  316.   _StartFile  = Procedure(Fname : str64; FSize : Longint);
  317.   _EveryBlock = Procedure(CurrentOffset : Longint);
  318.   _EndFile    = Procedure(Fname : Str64; GoodTransfer : Boolean);
  319.  
  320. { External Procedure Hooks. This are the prototypes for the calls that will be}
  321. { made by the Protocol Engine at these times                                  }
  322.  
  323. Const
  324.    MaxZBlockSize : Word = 1024;
  325.    MaxRetrys     : Byte = 10;
  326.    Version       = 'v0.18a';
  327.  
  328. { MaxZblockSize is the biggest Zmodem block to send. Most mailers can accept  }
  329. { 8k blocks, however Terminal programs usually only handle 1k blocks          }
  330.  
  331. { MaxRetrys is the number of errors in any one transfer that will force a     }
  332. { error abort                                                                 }
  333.  
  334. Var
  335.     OverWrite       : Boolean;      {Can overwrite on Rx                     }
  336.     StartOfFile     : _StartFile;   {Called at start of EVERY file           }
  337.     EveryBlock      : _EveryBlock;  {Called before every block transferred   }
  338.     EndOfFile       : _EndFile;     {Called after every file, good or bad    }
  339.     NumberOfFiles   : Byte;         {How many files got rxed/txed            }
  340.     UploadPath      : Str64;        {Where to put the files. In Batch mode   }
  341.                                     {this must be set to the upload directory}
  342.                                     {for a single file mode, such as Xmodem  }
  343.                                     {this string contains the FULL filename  }
  344.     WindowType      : Byte;         {This byte controls the type of display  }
  345.                                     {during a file transfer. It can be one of}
  346.                                     {three values    0  = No Display         }
  347.                                     {                1  = Plain Line_of_text }
  348.                                     {                2  = Window display     }
  349.  
  350. Function Xmodemrx       : Boolean;
  351. Function XmodemTX       : Boolean;
  352. Function Xmodem1kTX     : Boolean;
  353. Function Xmodem1kRx     : Boolean;
  354. Function YmodemTX       : Boolean;
  355. Function YmodemGTX      : Boolean;
  356. Function YappRX         : Boolean;
  357. Function YappTx         : Boolean;
  358. Function YmodemRx       : Boolean;
  359. Function YmodemGRX      : Boolean;
  360. Function SealinkTx      : Boolean;
  361. Function SealinkRx      : Boolean;
  362. Function ZmodemTX       : Boolean;
  363. Function ZmodemRX       : Boolean;
  364.  
  365. Function AddNametoList(Var Fname : Str64): Boolean;
  366.  
  367. { Adds a Filename to the linked list. Will return false if not enough memory  }
  368. { to store the name                                                           }
  369.  
  370. Procedure GetNameFromList(Var Fname : Str64; var MoreFiles : Boolean);
  371.  
  372. { Retrieves and removes the first name from the linked list. Also returns     }
  373. { back if there any more names in the linked list. Fname will be empty if     }
  374. { no name found. It also returns any memory freed back to the heap            }
  375.  
  376. Procedure ClearNameList;
  377.  
  378. { Clears the linked list and returns memory to the heap                       }
  379.  
  380.  
  381.     6.0) Release Details.
  382.  
  383.     The  most  current  version  of the  Protocol  Engine  will  always  be 
  384.     available  from the authors BBS, the Perth Omen (3:690/660.0) which  is 
  385.     online  24hours/days  at all speeds upto v32, +61-9-244-2111. It  is  a 
  386.     FREE  download to all, and can be picked up by first time  callers.  It 
  387.     can  also be FileRequested at any time by using the magic  filename  of 
  388.     PROTENG.
  389.  
  390.     The Protocol Engine is available in three versions:
  391.  
  392.     a) the compiled TPU's with sample terminal program.  This includes  the 
  393.     source  for the terminal program, the communications unit and the  Ansi 
  394.     unit.  There is NO source supplied for the TPU's. It will also have  an 
  395.     annoying  copyright  message  hard coded into the TPU's.  This  is  the 
  396.     shareware demonstration version that will allowed on BBS's.
  397.  
  398.     b)  As above, but without the annoying message. This will  cost  $20.00 
  399.     Australian  for registration (plus $5 postage if needed) and will be  a 
  400.     full legal copy with BBS support.
  401.  
  402.     c)  The FULL source code. This version has over 150k of  Pascal  source 
  403.     for  the entire Protocol engine with NO royalties attached.  This  will 
  404.     cost $100.00 Australian (plus $5 postage where needed) and BBS  support 
  405.     will be given through the Perth Omen BBS.
  406.  
  407.  
  408.     7.0) Idiosyncrasies.
  409.  
  410.     a)  The  Protocol Engine fails to acknowledge  filenames  and/or  paths 
  411.     which are sent to it for transfer and don't exist. The user must ensure 
  412.     that  the  upload and download paths exist. 
  413.  
  414.     If Receiving: The upload directory MUST have a trailing "\" if in batch 
  415.     mode,  or the complete name and path if in single file mode.   However, 
  416.     if a file is uploaded with a pathname in the filename header - the path 
  417.     in the header is stripped - and your path is put in its place.
  418.  
  419.     If  Sending: The filenames must be complete names with full  paths.  If 
  420.     the file doesn't exist, Protocol Engine will skip it but leave a  error 
  421.     in  the global variable IoResult. This will catch you out in  the  end. 
  422.     Turbo Pascal never forgets the error, and when you DO get some sort  of 
  423.     error, Turbo will display the OLDEST one!
  424.  
  425.     b) Due to the fact that a program such as the Protocol Engine  requires 
  426.     a  tight  interface  to  the serial ports,  a  communications  unit  is 
  427.     included.  This  unit  MUST be used for the  Protocol  Engine  to  work 
  428.     correctly,  without making major changes to the source of the  Protocol 
  429.     Engine.   You  may  substitute  your own comms unit  in  place  of  the 
  430.     supplied ProtComm unit, but it is at your risk. If you do so, you  MUST 
  431.     create substitute procedures and functions for EVERY routine  contained 
  432.     within ProtComm. 
  433.     
  434.  
  435.     8.0) History Of the Protocol Engine.
  436.  
  437.  
  438.  
  439.      V0.00          The Idea is Born!
  440.  
  441.      v0.12          The first beta version is released in Perth.
  442.                     Looks good so far!
  443.                     No Sealink yet
  444.                     Need to modify packet
  445.  
  446.      v0.13          Started to put in Sealink TX!@ AGH!
  447.                     Numberoffiles now reflects how many successful files
  448.                     Fixed Zmodem send with TX buffers
  449.  
  450.      v0.14          First Real Beta release.
  451.                     Fixed TINY bug in Zmodem Start - Mailers refused to
  452.                     auto_download.
  453.  
  454.      v0.15          Added hooks for StartFile,EndFile and Everyblock.
  455.                     Added linked list code for Filename passing.
  456.                     Fixed Bug (not really my bug!) with transfers into Front
  457.                     Door, because FD can't handle ZDLE Escaped $7f,$ff  (as
  458.                     per Zmodem specs! Tsk Tsk Joho!)
  459.                     Added WindowType Flag.
  460.  
  461.      v0.16          Minor cosmetic bug fixes. Fixed MAJOR bug in comm unit
  462.                     for 16650 support!
  463.  
  464.      v0.17          Re_Wrote XModem code, allowing Sealink to be put in.
  465.                     Ended up being tighter and easier to debug!
  466.                     Added Dv Time Giveaway. Added CPS in window (waste of CPU!)
  467.  
  468.      v0.18          Finally Finished! First Decent Release... I Think!
  469.                     Fixed annoying buglets in Timing at end of files, when
  470.                     using high speeds modems + big fossil buffers.
  471.  
  472.  
  473.     9.0) Contacting the Authors.
  474.  
  475.     For  any  further  details or the latest version, the  authors  may  be 
  476.     contacted at the Perth Omen BBS (3:690/660.0@fidonet) on +61-9-244-2111 
  477.     (multiline)  all  speeds upto v32, or by voice on  +61-9-244-1954  (any 
  478.     time between 0300GMT and 1600GMT).
  479.  
  480.     Mark Dignam.
  481.     Mick Howland.
  482.  
  483.