home *** CD-ROM | disk | FTP | other *** search
/ World of Shareware - Software Farm 2 / wosw_2.zip / wosw_2 / PASCAL / ZIP2OBJ.ZIP / ZIP2OBJ.DOC < prev    next >
Text File  |  1991-11-12  |  7KB  |  171 lines
  1.         ZIP2OBJ.DOC  --  The Turbo Pascal ZIPfile Data Objitizer
  2.  
  3.                         By Wilbert van Leijen
  4.  
  5. Introduction
  6. ────────────
  7.  
  8. ZIP2OBJ is a program that extracts a file from a ZIPped archive and
  9. converts it to a .OBJ file that you can link to a Turbo Pascal (TP) program,
  10. version 6.0 or later.
  11. XZIP.PAS is the TP 6.0 unit that takes care of exploding the compressed data.
  12.  
  13. The ZIP2OBJ.EXE program and the Turbo Pascal XZIP.PAS unit are distributed
  14. as Shareware.  If you use them, you are kindly asked to register this
  15. product.  The fee for becoming a Registered User of ZIP2OBJ/XZIP is $10.--
  16. or ƒ20.-- (that's twenty Dutch guilders).  Just send a cheque or money order
  17. to the author.  My address is mentioned at the bottom of this document.
  18.  
  19. Upon registration, you will become a disk with:
  20. -  the source code of ZIP2OBJ
  21. -  3 different customised TP 6.0 Runtime libraries (SYSTEM.TPU):
  22.    one 'Regular Version': 100% compatible with Borland's, but with many
  23.    code enhancements and improved 'smart linking';
  24.    one 'Regular 286 Version', with 286 code throughout, aborts automatically
  25.    when an attempt is made to run a program on an XT-class system; and
  26.    one 'STUB Version', designed especially for crafting ultra compact
  27.    utilities and TSR programs.
  28.  
  29. The STUB version of SYSTEM.TPU was used to compile ZIP2OBJ.  STUB is a
  30. limited version of the runtime library in the following respects:
  31. it does not support overlays and virtual methods; it doesn't automatically
  32. open/close the text files Input and Output (they are pre-declared, however);
  33. it doesn't take over any interrupts; and it passes control to DOS to do the
  34. allocation and deallocation of data structures on the heap.  STUB will be
  35. accompanied with guidelines for developers.  As a rule, if you're not
  36. deeply into object oriented programming, the majority of your TP programs
  37. will benefit from STUB.  Example: the minimum .EXE size of a program created
  38. with STUB ('begin end.') is only 224 bytes.
  39.  
  40. Using ZIP2OBJ
  41. ─────────────
  42.  
  43. ZIP2OBJ's command line is akin to BINOBJ, a utility shipped with every
  44. version of Turbo Pascal since 4.0.  BINOBJ expects you to specify an input
  45. file, an output file and an exported identifier.  ZIP2OBJ wants you to tell
  46. it:
  47. -  an input file: this must be a .ZIP archive, created with PKZIP, version
  48.    1.01 or later;
  49. -  an entry in the .ZIP archive: this is the file that will be converted
  50.    to an .OBJ file;
  51. -  an exported identifier or 'public name': this is the symbol that must
  52.    be specified in order to link the .OBJ file to your TP program.
  53.  
  54. Unlike BINOBJ, the ZIP2OBJ utility will declare not one but two public
  55. names.  And unlike BINOBJ too, these two public names are callable by your
  56. program, i.e. you don't have to pass a pointer to it to access your data.
  57.  
  58. There are some restrictions to the kind and the size of the entry in the
  59. .ZIP archive.
  60. In order for ZIP2OBJ to succeed, the following conditions must be met:
  61. -  the file to be converted must be IMPLODED.
  62. -  the original (uncompressed) size of the file must not exceed 65520 bytes,
  63.    since that's the maximum size of a structure that can be allocated in TP.
  64.  
  65. Notes:
  66. -  PKZIP version 1.1 has a command line switch (-ei), forcing a file to
  67.    be imploded.
  68. -  If the file is too big, try breaking it up in multiple files and compress
  69.    them separately.
  70.  
  71. Sample usage:
  72.  
  73. Suppose you have BOGEY.ZIP, with BOGEY.BIN as an entry in this archive.
  74. (This is what we will do in the demo).  BOGEY.BIN is the raw bitmap of
  75. a VGA mode 13h (320 by 200 with, in this case: 32 shades of gray) picture
  76. of Humphrey Bogart - for those of you unfamiliar with phrases like 'Play
  77. it again, Sam' or 'Wiseguy': a Hollywood actor from the '40s and '50s.
  78.  
  79. To compress BOGEY.BIN, run PKZIP:
  80.   PKZIP BOGEY BOGEY.BIN
  81.  
  82. Next, to convert BOGEY.BIN to an TP linkable .OBJ file, run ZIP2OBJ:
  83.   ZIP2OBJ BOGEY BOGEY.BIN Bogey
  84.  
  85. ZIP2OBJ will lift BOGEY.BIN from BOGEY.ZIP, and write out BOGEY.OBJ.
  86. BOGEY.OBJ has not only compressed data in it.  It also has 32 bytes of
  87. loader code in front:
  88.  
  89.    Function BogeySize : Word; Far; External;
  90.    Procedure ExplodeBogey(Var buffer); Far; External;
  91.  
  92. Note that the names of routines exported by ZIP2OBJ are always of the
  93. format <public_name>SIZE and EXPLODE<public_name>.  And do not forget
  94. to attach the 'Far' pseudo-type to the declaration - or alternatively,
  95. to enable the Force FAR calls flag with {$F+} - in your TP application
  96. or your program will crash.
  97.  
  98. In this case, BogeySize returns the size of the raw, uncompressed bitmap:
  99. 65520 bytes.  This information is useful if you want to know beforehand
  100. the exact amount of heap space to be reserved for the full Bogey (by a
  101. call to GetMem).  For a straight dump of the picture to the VGA display
  102. however, calling BogeySize is not needed: the VGA memory is already there,
  103. and unaccessible by TP's heap manager anyway.
  104.  
  105. Using XZIP
  106. ──────────
  107.  
  108. ExplodeBogey calls a Far routine by the name of Explode.  This routine is
  109. exported by unit XZIP and it takes care of the actual explosion of the
  110. compressed information.  XZIP is entirely written in TP's Built-In Assembler
  111. (BASM), and is highly optimised: using no more than 935 bytes of code space,
  112. 10 kByte of stack space and 3 kByte of global data.
  113.  
  114. The deal is here that you must include 'uses XZip' under the program header
  115. of your TP application.
  116.  
  117. Do not call Explode by your application -- unless you know exactly what
  118. you're doing.  Explode will be called by the loader code of any .OBJ file
  119. created by ZIP2OBJ.
  120.  
  121. Running the demo
  122. ────────────────
  123.  
  124. In order to compile and run the demo, you must have the following:
  125. -  Turbo Pascal, version 6.0.
  126. -  PKZIP (tm), version 1.01 or later
  127. -  A VGA display.  (Any VGA display will do.)
  128.  
  129. Step #1.
  130. -  Run program GetBogey
  131.    This will write the file BOGEY.BIN to the current directory.
  132.  
  133. Step #2.
  134. -  Create a .ZIP archive, and store BOGEY.BIN in it:
  135.  
  136.    ZIP BOGEY BOGEY.BIN
  137.  
  138. Step #3.
  139. -  Run ZIP2OBJ to convert BOGEY.BIN to an .OBJ file:
  140.  
  141.    ZIP2OBJ BOGEY BOGEY.BIN BOGEY
  142.  
  143.    This will write the file BOGEY.OBJ to the current directory.
  144. -  BOGEY.OBJ is a valid .OBJ file that you can link to a TP program.
  145. -  BOGEY.OBJ declares the following routines public from TP's
  146.    point of view:
  147.  
  148.    Function BogeySize : Word; Far; External;
  149.    Procedure ExplodeBogey(Var buffer); Far; External;
  150.  
  151. Step #4.
  152. -  Compile and run program BOGEY.PAS.
  153.  
  154. Trade Marks
  155. ───────────
  156.  
  157. PKZIP and PKUNZIP are Copyrighted by Phil Katz.
  158. Turbo Pascal is Copyrighted by Borland International.
  159. ZIP2OBJ and XZIP are Copyright 1991 by Wilbert van Leijen,
  160. Amsterdam, The Netherlands.
  161.  
  162. Author
  163. ──────
  164.  
  165. Wilbert van Leijen
  166. Marathonweg 72-2
  167. NL-1076 TM Amsterdam
  168. The Netherlands
  169.  
  170. Wilbert van.Leijen at Fidonet 2:500/12.10956
  171.