home *** CD-ROM | disk | FTP | other *** search
/ Boston 2 / boston-2.iso / DOS / PROGRAM / BASIC / POWBASIC / LIBRARY4 / SPOOLK.ZIP / SPOOLKIT.DOC < prev    next >
Text File  |  1990-11-23  |  12KB  |  267 lines
  1.  
  2.             ┌──────────────────────────┐
  3.            ┌┼──────────────────────────┼┐
  4.            ││        SPOOLKIT.PBU       ││
  5.            ││        23 Nov, 1990       ││
  6.            ││                   ││
  7.            ││    Nathan C. Durland III  ││
  8.            ││                   ││
  9.            └┼──────────────────────────┼┘
  10.             └──────────────────────────┘
  11.  
  12. BACKGROUND:
  13. Ever since version 2, PC-DOS and MS-DOS have contained an external 
  14. program called PRINT.  When first invoked, the PRINT program would 
  15. establish which port the printer was attached to, and then would leave 
  16. a piece of itself behind.  I'll call the small portion "the resident". 
  17. The resident would then busy itself with stealing little pieces of 
  18. processor time, when nothing else was going on, and send the contents 
  19. of what ever file you wished to the printer.  Now you could be twice 
  20. as productive, since you could work and print at the same time.
  21.  
  22. I have written several programs for other people that generated a lot 
  23. of printed output.  I hated working hard to make the program run fast 
  24. and efficiently, only to wait for the printer.  I had though about 
  25. creating print files, then using a command similar to the BASIC 
  26. "SHELL" statement to print the files.  But this is inelegant, and it 
  27. didn't give me the control I needed over what was spooled, what 
  28. wasn't, what was done so I could overwrite the file, etc.
  29.  
  30. Finally, starting with version 3.x of DOS, the interface to the
  31. resident was published.  So, yours truly went to work and created some 
  32. BASIC subroutines that provide an interface to the PRINT resident.
  33.  
  34. The biggest advantage these routines offer is that they relieve the
  35. programmer (you) of the burden of trapping printer errors (off-line,
  36. out of paper, no power, what ever).  The resident takes care of all
  37. that.  If all your print output is directed to files that are to be
  38. spooled, you can then LINK your PowerBasic programs without the
  39. printer library, and get smaller .EXE files.
  40.  
  41.  
  42. REQUIREMENTS:
  43.     These routines require that you have PowerBasic 2.10, with the
  44. PowerPack.  If someone asks, I can modify them to work with PB 2.00.
  45. Although the interface to the PRINT resident wasn't published until
  46. version 3.x, a couple of DOS gurus I've talked to don't see why there
  47. should be any problems using these routines with version 2.1.  I can't
  48. say, since I don't have access to a machine that is running anything
  49. less than V3.2.
  50.  
  51.  
  52.  
  53.  
  54. COMMENTS:
  55. The comment header from each routine is included below, and each 
  56. routine is pretty self-explanatory.  However, a couple of cautions are 
  57. in order:
  58.  
  59. 1.  Before you use any of these routines, make sure you have the PRINT 
  60. resident portion loaded.  It is a bad practice to use the SHELL 
  61. statement from a basic program to load the resident.  Why?  Because 
  62. PRINT is a terminate-and-stay-resident (TSR) program.  TSRs, by their 
  63. nature, will "lock" any program that is loaded before them into 
  64. memory.  So, when your BASIC program ends, whatever memory it uses 
  65. will be unavailable to the next program you run.
  66.  
  67. 2.  If you call the ListSpooledFiles routine, make sure that f$() (or
  68. what ever you choose to call the array for the returned file names)
  69. is DIM'd large enough to hold all the entries.  The PRINT command uses
  70. the /Q:xx switch to determine the maximum number of queue entries. 
  71. This number can't be larger than 32, and is 10 by default.  The SUB
  72. assumes that the first element is number 1.
  73.  
  74. 3.  The SpoolInstalled% function will return a boolean (True/False)
  75. value, based on whether the PRINT resident is detected.  All the
  76. other SUBs in SPOOLKIT return a status code.  If the SUB executed
  77. OK, then the status code will be 0.  Otherwise, it will be set to
  78. the error code that was retured by the interrupt call.    No other
  79. error checking is done by the subs. These are the possible error
  80. codes:
  81.  
  82.     0 = Call executed OK.  No errors
  83.     1 = Function invalid.  Most likely when a routine is called and
  84.         resident is not installed
  85.     2 = File not found
  86.     3 = Path not found
  87.     4 = Too many open files (increase the FILES= in CONFIG.SYS)
  88.     5 = Access denied.    You can't read the file, or the queue is on hold.
  89.     8 = The print queue is full.
  90.     9 = Spooler busy.  Wait, then try again.
  91.    12 = Name to long.  File specifications must 64 bytes or less.
  92.    15 = Drive invalid.
  93.  
  94. I also used the following return codes in the SubmitSpoolFile routine
  95.  
  96.    *16 = Spooler (resident) not installed
  97.     17 = Called with blank file specification
  98.     18 = No file met specification
  99.  
  100.  * SubmitSpoolFile is the only one of these routines that will check for the
  101.    presence of the resident.  This is to save time, since the routine may have
  102.    to process a long list of files before it actually tries to communicate
  103.    with the resident.
  104.  
  105. 4.  And finally, if you are writing a program using these routines, it
  106. will not run correctly within the PowerBasic IDE.  I have gotten in 
  107. touch with the folks at Spectra Publishing via CompuServe, and they are
  108. looking into it.  You can compile to an .EXE file and run it with out
  109. any problems.  SPKDEMO.EXE and .BAS are included so you can get a look
  110. at the routines in action.
  111.  
  112.  
  113. I hope you find these routines useful.  The .ZIP file you extracted 
  114. this documentation from has a short demo of the functions of the 
  115. SPOOLKIT routines.  The zip file should contain these files:
  116.  
  117.     SPOOLKIT.DOC    -  What you're reading now
  118.     SPOOLKIT.PBU    -  PowerBasic unit file
  119.     SPOOLKIT.INC    -  Include file that contains required DECLAREs
  120.     SPKDEMO.BAS
  121.     SPKDEMO.EXE     -  Demo program
  122.  
  123. Source code is available upon request.  Use of this software is free 
  124. for both personal and commercial use, and the software is supplied 
  125. without warranty, implied or otherwise.  However, the author is not 
  126. adverse to accepting a small ($5.00) donation if you would like to send
  127. one (This would encourage him to write more routines, or improve on
  128. some of these!).  Send any donations to:
  129.  
  130.               Nathan C. Durland III
  131.               400 Margaret St, Apt #7
  132.               Plattsburgh, NY   12901
  133.  
  134. I can also be reached at CompuServ, user ID 76467,3355  or on PC-LINK, 
  135. screen name ShadowFax1.
  136.  
  137.  
  138.  
  139.  
  140. Major routines in the SPOOLKIT are:
  141.  
  142.  
  143.  
  144. FUNCTION SpoolInstalled% LOCAL PUBLIC
  145. ' ------------------------------------------------------------------
  146. '  Detects if resident portion of DOS PRINT is installed
  147. '  No mechanism is provided here to detect that PRINT is not loaded
  148. '  but can be.  This would encourage loading of PRINT.COM from a
  149. '  SHELL statement, which would lock all the memory used by the
  150. '  calling program.
  151. '
  152. '  This function differs from the rest of the Spoolkit routines in
  153. '  that it returns a TRUE/FALSE value instead of the error code.
  154. ' ------------------------------------------------------------------
  155.  
  156. SUB SubmitSpoolFile(f$,FCount%,Stat%) LOCAL PUBLIC
  157. ' ------------------------------------------------------------------
  158. '  This routine will dispatch file(s) to the DOS PRINT spooler.
  159. '  Notice that this is the only SUB that checks for the presence of
  160. '  the PRINT resident.  It does this to save time, since there is some
  161. '  work to be done before any spooling actually takes place.  Wild
  162. '  card file specifications are not allowed by the interrupt call, but
  163. '  are acceptable to this routine.  This sub will take a wild card spec
  164. '  and dispatch all matching files one at a time to the PRINT resident.
  165. '  Dispatching stops, however, if an error occurs while submitting a file.
  166. '
  167. '  CALLING PARAMETERS:
  168. '
  169. '  INPUT:
  170. '     f$      = File Specification to be submitted (wildcards OK)
  171. '     Stat%   = Not Used
  172. '     FCount% = Not Used
  173. '
  174. '  OUTPUT:
  175. '     f$      = Not Used
  176. '     Stat%   = Error code from call.  0 Means everything is OK
  177. '     FCount% = Number of successfully files spooled.  This is valid
  178. '               even if the routine takes an error.
  179. '
  180. ' ------------------------------------------------------------------
  181.  
  182.  
  183.  
  184. '
  185. SUB RemoveFromSpool(f$,Stat%) LOCAL PUBLIC
  186. ' ---------------------------------------------------------------------------
  187. '  Removes file(s) from the spool queue.  Pass the full path and file name
  188. '  of the entry to be removed.  Wildcards are allowed for this function.
  189. '  However, a drive and directory are required.  If a drive/dir is not
  190. '  part of f$, the current default will be added.  So, if your current
  191. '  directory is C:\PB\DOC, and you call RemoveFromSpool with f$ = XYZ.DOC,
  192. '  the file "C:\PB\DOC\XYZ.DOC" can be remove from the queue, but
  193. '  C:\MYDOC\XYZ.DOC will not be removed.
  194. '
  195. '  Intresting technical note: Any wildard file specifications are
  196. '  converted to ????????.??? format (F*.BAT becomes F???????.???).  This is
  197. '  because the interrupt will occasionaly return corrupt information if a
  198. '  '*' is in the file name; even though the DOS technical reference says it
  199. '  is legal.  The ????????.??? format has worked flawlessly for me.
  200. '
  201. '  PB Calling sequence:
  202. '     Passed IN:     f$ = Name of file(s) to cancel
  203. '     Passed OUT:    Stat% = Status code from call.  0 is OK
  204. ' ---------------------------------------------------------------------------
  205.  
  206.  
  207. SUB CancelAllSpool(Stat%) LOCAL PUBLIC
  208. ' ------------------------------------------------------------------
  209. '  Removes all entries from the DOS PRINT spool queue.  Use with
  210. '  appropriate caution
  211. '
  212. '  PB Calling sequence:
  213. '     Passed IN:     NONE
  214. '     Passed OUT:    Stat% = Status code from call.  0 is OK
  215. ' ------------------------------------------------------------------
  216.  
  217. SUB HoldSpool(QueuedFiles$,Stat%) LOCAL PUBLIC
  218. ' ------------------------------------------------------------------
  219. '  Puts a hold on the DOS PRINT spool queue, and returns the list
  220. '  of files currently in the queue in a single string variable.
  221. '  Each file name in the variable is separated by an ASCII zero
  222. '  (CHR$(0)).  The original list fof files returned by the DOS
  223. '  service is a structure of 64-byte entries.  The file name in
  224. '  each entry is terminated with a single ASCII 0, and the rest of
  225. '  the structure contains leftover junk.  HoldSpool strips out the
  226. '  unneeded bytes.
  227. '
  228. '  PB Calling sequence:
  229. '     Passed IN:     NONE
  230. '     Passed OUT:    Stat% = Status code from call.  0 is OK
  231. '                    QueuedFiles$ = string containing names of files
  232. '                                   in print queue, separated by
  233. '                                   CHR$(0)
  234. '
  235. ' ---------------------------------------------------------------------
  236.  
  237.  
  238.  
  239.  
  240. SUB StartSpool(Stat%) LOCAL PUBLIC
  241. ' ------------------------------------------------------------------
  242. '  Removes a hold on the DOS PRINT spool queue.
  243. '
  244. '  PB Calling sequence:
  245. '     Passed IN:     NONE
  246. '     Passed OUT:    Stat% = Status code from call.  0 is OK
  247. ' ------------------------------------------------------------------
  248.  
  249. SUB ListSpooledFiles(f$(),FCount%,Stat%) LOCAL PUBLIC
  250. ' ---------------------------------------------------------------------------
  251. '  This routine will determine what files are queued to print, and will
  252. '  return their names in an array.
  253. '
  254. '  A safe number to dimension f$() to is 32, this is the maximum number of
  255. '  files that can ever be queued to PRINT, at least in DOS versions 3 and 4
  256. '
  257. '  PB Calling Sequence:
  258. '     Passed in:    Nothing.  f$() must be DIM'd, preferably to 32.
  259. '                   No bounds checking is done by this SUB
  260. '     Passed out:   f$() contains the names of the files queued.
  261. '
  262. '                   FCount% is the number of files.  A partial list may
  263. '                   have been created if there was an error
  264. '
  265. '                   Stat% is the Status. 0 means all is OK
  266. ' ---------------------------------------------------------------------------
  267.