home *** CD-ROM | disk | FTP | other *** search
/ Programmer 7500 / MAX_PROGRAMMERS.iso / INFO / TURBOPAS / ARGLIB.ZIP / ARGLIB.DOC next >
Encoding:
Text File  |  1985-12-28  |  6.6 KB  |  177 lines
  1.  
  2.                                                                 PAGE 1
  3.  
  4.  
  5.  
  6.            ArgLib - A Portable Pascal File Argument Library
  7.  
  8.                             15 March 1985
  9.  
  10.                            Willett Kempton
  11.  
  12.  
  13.  
  14.  
  15. What ArgLib Does
  16. ----------------
  17.  
  18.      Arglib provides a portable means of reading file arguments from
  19. the operating system command line into a Pascal program.  It also
  20. allows assignment of a name to a file variable and detection of empty
  21. files.  ArgLib became necessary because almost every company's version
  22. of Pascal has implemented these functions in a different way.  By
  23. calling ArgLib, rather than writing system-specific code in each
  24. program, software can be more easily moved across compilers, operating
  25. systems and computers.
  26.  
  27. ArgLib is currently available for:
  28.  
  29.   1. Turbo Pascal, CP/M-80, CP/M-86, MS-DOS
  30.   2. Pascal/MT+, Pascal/MT+86
  31.   3. Berkeley UNIX Pascal, pi, pc
  32.  
  33. Specifics on these implementations follow:
  34.  
  35.      1.  ArgLib.pas: Turbo pascal.  Tested with Turbo v 1 and v 2, on
  36.          CP/M-80, CP/M-86, and MS-DOS on a DEC Rainbow.  Requires a
  37.          minor modification (marked in the code) to switch among these
  38.          operating systems.  Also, a bug in 8-bit Turbo (v1, v2)
  39.          truncates any command line arguments past 31 characters.
  40.  
  41.      2.  ArgLibMT.pas: Pascal/MT+86 and Pascal/MT+.  Tested with MT+86
  42.          V 3.1.  Note that in the MT+ version, "argcount" must be
  43.          called prior to "argv".  This is the typical calling sequence
  44.          anyway, but is REQUIRED under MT+ systems.
  45.  
  46.      3.  ArgLibUX.pas: Berkeley UNIX Pascal.  Tested on Pascal version
  47.          3.0, using both the pi interpreter and the pc compiler on a
  48.          VAX 11/750 running BSD 4.1.
  49.  
  50.  
  51.  
  52. Procedures avaliable
  53. --------------------
  54.  
  55.      argcount: Argument count.  Function returning an integer count of
  56. how many file arguments were given on the command line.
  57.  
  58.      argv(count,name): Argument Value.  Procedure setting the variable
  59. "name" to argument number "count" from the command line.
  60.  
  61. ArgLib  -- Portable file argument library                       PAGE 2
  62.  
  63.  
  64.  
  65.      resetOK(file,name): Assign, reset, and check.  Assign the file
  66. variable "file" to read from the external file or device named "name".
  67. If the external file is nonexistant or empty, return false.  Otherwise
  68. return true.
  69.  
  70.      For example, suppose that the user calls program "cp" with two
  71. files:
  72.  
  73.     A>CP FILEA FILEB
  74.  
  75.      argcount     --> returns the value  2
  76.      argv(1,name) --> sets "name" to 'FILEA           '
  77.      argv(2,name) --> sets "name" to 'FILEB           '
  78.      resetOK(f,name) --> resets f for reading from "name";
  79.                          if nonempty, return TRUE
  80.  
  81.      Note that under UNIX, argv(0,name) would set "name" to 'CP', but
  82. in the micro version it sets "name" to blank.
  83.  
  84.      Most pascal systems will require ArgLib to be included after the
  85. last variable of the main program and before the first procedure.
  86. After the include, the following symbols are available.
  87.  
  88. Symbols available to calling program
  89.  
  90.  const
  91.    MaxArgStrLen = 16; (* max chars per argument; VARIES WITH OS! *)
  92.  type
  93.    ArgStrType = packed array [1..MaxArgStrLen] of char;
  94.  
  95.  procedure argv(argn : integer; var name : ArgStrType);
  96.  
  97.  function argcount : integer;
  98.  
  99.  function resetOK (var f: text; name: ArgStrType) : boolean;
  100.  
  101.      Design tradeoffs were as follows.  Execution speed was sacrificed
  102. for compact code, since these routines will typically only be called
  103. once.  Standard Pascal (ISO standard) was used whenever possible (no
  104. 'string', etc.).  (Berkeley UNIX Pascal provides no string type.)
  105.  
  106.  
  107. Testing ArgLib
  108. --------------
  109.  
  110.      A test program is provided with ArgLib.  It is called ArgTest.pas
  111. and it includes ArgLib into its source.  The following is a session
  112. using argtest on CP/M:
  113.  
  114.  
  115. F>dir
  116. F: SMALL       : EMPTY       : ARGTEST.CMD
  117.  
  118. F>type empty
  119.  
  120. ArgLib  -- Portable file argument library                       PAGE 3
  121.  
  122.  
  123.  
  124. F>type small
  125. this is a small file
  126.  
  127. F>type nothing
  128. NO FILE
  129. F>argtest empty small nothing
  130. file arguments=3
  131.  0=               empty
  132.  1= EMPTY         empty
  133.  2= SMALL         exists
  134.  3= NOTHING       empty
  135.  
  136. F>
  137.  
  138. Note that both the empty and the nonexistant files are detected.
  139.  
  140.  
  141. Hints for Portable Code
  142. -----------------------
  143.  
  144.      Some of the programs you write will only be used a few times, or
  145. by their nature, will only be used on one system.  These need not be
  146. portable.  Other programs will retain their value over a period of
  147. years.  During those years, you are likely to use different computers,
  148. and almost certain to use several different compilers.  To preserve
  149. your software-writing investment, you want to be able to transfer your
  150. programs without having to re-write them for each system.  Programs
  151. which allow easy transfer are considered "portable".
  152.  
  153.      For those programs which you want to be portable, do not use the
  154. compiler manufacturer's manual to guide your writing.  Use a manual on
  155. "Standard Pascal", which is a subset of most commercial Pascals.  The
  156. Standard is defined by ISO, the International Standards Organization,
  157. and by ANSI, the American member of ISO.  The defining ISO document
  158. (ISO dp7185, December 1980) is precise but difficult to read.  Two
  159. readable descriptions of Standard Pascal are available.  One is
  160. "Standard Pascal, User Reference Manual", by Doug Cooper, (1983, W.
  161. W.  Norton & Company).  The other is the THIRD edition of "Pascal User
  162. Manual and Report", by Jensen and Wirth (1984, Springer Verlag).
  163. Either is preferable to the second edition of Jensen & Wirth (1974),
  164. which is less readable and partially inconsistent with the final ISO
  165. standard.
  166.  
  167.      Sometimes, system dependent features will be necessary, for
  168. example in getting file names from the operating system command line.
  169. When they are needed, they can be localized in a few routines which
  170. can be called in a standard way.  Then to change all your software for
  171. a new system, you need only change a few routines.  ArgLib is an
  172. example of this strategy.
  173. p$CJ=J1a48q4!PORTABLE FILE ARGUMENTS CPM-80 CPM-86 MS-DOS TURBO PASCALMT+ BSD UNIXThese routines allow Pascal programs to get arguments (e.g. files,
  174. options) from the command liene.  Works in all Turbo systems, with
  175. a one -line change (marked in comments).  Versions are also available
  176. for Pascal/MT+ and BSD UNIX pascal (request upload).
  177.