home *** CD-ROM | disk | FTP | other *** search
/ ftp.update.uu.se / ftp.update.uu.se.2014.03.zip / ftp.update.uu.se / pub / rainbow / msdos / decus / RB131 / jobsdump.doc < prev    next >
Text File  |  1995-06-04  |  22KB  |  470 lines
  1. ***********************************************************************
  2. *                                                                     *
  3. *                         JOBSDUMP V4.2/4.0                           *
  4. *                                                                     *
  5. *                   A GRAPHICS SCREEN-DUMP PROGRAM                    *
  6. *                  FOR THE DEC RAINBOW 100 PC FAMILY                  *
  7. *                                                                     *
  8. *             Copyright (C) 1985,6,7,8,9 James A. O'Brien             *
  9. *                                                                     *
  10. *                         1166 Hope St., #6                           *
  11. *                         Stamford, CT 06907                          *
  12. *                               U.S.A.                                *
  13. *                                                                     *
  14. *                    Tel: +1 203 322 7222 (Evenings)                  *
  15. *                                                                     *
  16. ***********************************************************************
  17.  
  18.  
  19.  
  20.         This software may be copied and the copies distributed without
  21. restriction for PRIVATE INDIVIDUAL use.  Copyright is retained by the
  22. author, and the source code will not be distributed.  If you find the
  23. software useful (i.e. you use it!), a $25 donation to the author at the
  24. above address is requested for those users who are private individuals.
  25. In other words, this software is not public domain - it is SHAREWARE.
  26.  
  27.         Commercial site licenses may be obtained by contacting the author
  28. at the above address.  NOTE that this software is NOT FREE FOR USE IN A
  29. COMMERCIAL ESTABLISHMENT, no matter how humble.
  30.  
  31.  
  32.  
  33. Hardware Requirements:  (a) DEC Rainbow with Rainbow Graphics Option (RGO)
  34.                             and 192k of random access memory (at least 256k
  35.                             in order to run from within GW-BASIC).  CP/M 
  36.                             version only requires 128k.  [Has been tested
  37.                             with Suitable Solutions Turbow-286 board]
  38.                             
  39.  
  40.                         (b) DEC LA50, LA75, LA100 or LA210 
  41.                             or Epson-compatible dot matrix printer. 
  42.  
  43.  
  44. Software Requirements:  (a) MS-DOS V2.05 (or later) for MS-DOS version.
  45.  
  46.                         (b) CP/M 86/80 V2.0 (or later) for CP/M version.
  47.  
  48.  
  49. -------------------------------------------------------------------------------
  50. The complete distribution package includes the files:
  51.  
  52.         JOBSDUMP.EXE          MS-DOS version of JOBSDUMP V4.2
  53.         JOBSDUMP.CMD          CP/M 86/80 version of JOBSDUMP V4.0
  54.         JOBSDUMP.DOC          This documentation file.
  55. -------------------------------------------------------------------------------
  56.  
  57.  
  58.  
  59.  
  60.                         WHAT'S NEW IN VERSION 4.0,4.1 ?
  61.                         *******************************
  62.  
  63.      a)  It runs FASTER than 3.x and previous versions.
  64.  
  65.      b)  The DEC sixel files are about A FACTOR OF 10 SMALLER than 3.x
  66.             and previous versions.
  67.  
  68.      c)  The -e option has been added to the command-line option set.  It
  69.             lets you output the graphics in EPSON-compatible (IBM) format.
  70.  
  71.      d)  The -dnn option has been added to the command-line option set.  It
  72.             lets you DISPLAY on the screen for nn seconds the graphics that
  73.             will go to the printer.
  74.  
  75.      e)  The -n option has been added to the command-line option set.  It
  76.             lets you print the image in NEGATIVE mode to save printer
  77.             ribbons when a picture has very little white space.
  78.  
  79.      f)  The user interface is a more friendly cursor-driven environment, 
  80.             reminiscent of DEC-written utilities.  The -g (GO) option has been
  81.             added to the command-line option set, to allow command-line user
  82.             to avoid the cursor-driven user interface.
  83.  
  84.      g)  The CP/M version is functionally IDENTICAL to the DOS version as of
  85.             version 4.0.
  86.  
  87.      h)  The ERROR HANDLING for disk file output has been improved.  The output
  88.             now continues until the disk is full, at which time a graceful
  89.             exit (accompanied by a message) occurs.
  90.  
  91.      i)  The CP/M version is frozen at V4.0.  Version 4.2 for DOS includes
  92.             an option to select the colours which will print as black.  This
  93.             is accomplished using a DOS environment variable called JOBSCOLS.
  94.  
  95.  
  96.                         WHAT'S NEW IN VERSION 4.2 ?
  97.                         ***************************
  98.  
  99.      a)  The -l option has been added to the command-line option set.  It
  100.             compensates for the aspect ratio of the LA100 printer (different
  101.             from that of the LA50 and the Rainbow screen).
  102.  
  103.      b)  The operation of the -e (Epson mode) option has been enhanced, to
  104.             give improved pictures with correct aspect ratio.
  105.             
  106.      c)  The speed of the -e (Epson mode) option has been increased by means
  107.             of a sixel lookup table.
  108.             
  109.      d)  The menu display now shows more clearly the options in effect at any
  110.             given time.
  111.             
  112.             
  113.             
  114.                              (1) OVERVIEW
  115.                              ************
  116.  
  117.        JOBSDUMP is a utility program designed to give the Rainbow computer
  118. an important ability not included with the system - the ability to print out
  119. graphics screens directly on DEC or Epson-compatible printers.  It prints out 
  120. both medium and high resolution graphics screens in either of two
  121. formats :
  122.  
  123.         (a) Small, which is a dot-for-dot representation of the graphics
  124. screen and is smaller than the screen since printer dots are smaller than
  125. screen pixels for the Rainbow computer. 
  126.  
  127.         (b) Large, which is a double-size printout rotated 90 degrees
  128. counter-clockwise.  Thus, the right-hand-side of the screen picture is the 
  129. first part to arrive at the printer.  Large printouts just about fit on a page.
  130.  
  131.  
  132.         The program is interactive, prompting for the resolution, the
  133. printout size, the output file, the graphics protocol format (DEC or Epson), 
  134. the printing color and the preview option.  At any time, you have the option of
  135. aborting the program by pressing the <EXIT> or the <CANCEL> key.  This is useful
  136.  when you are not interested in printing the remainder of the graphics screen 
  137. (for example, when it is blank).
  138.  
  139.         Since most printers are monochrome devices, there is no simple way to
  140. distinguish among the various colours or shades of grey visible on the
  141. screen.  There are methods such as the error diffusion technique (see, e.g.
  142. "Digital Halftones by Dot Diffusion", by Donald E. Knuth in ACM Transactions
  143. on graphics 6, 245-273, 1987, and references therein).  They operate by 
  144. simulating, in a local average way, grey tones using randomly chosen black dots.
  145. However, these tend to be very demanding in terms of storage space and 
  146. floating-point computation. Such techniques are better suited to larger 
  147. machines.  The latest MS-DOS and CP/M versions of JOBSDUMP handle this in two 
  148. different ways.  
  149.  
  150. **V4.0:
  151.         Any colour which differs from black on the screen is 
  152. printed out in black on the printer.  When the -n option is in force, everything
  153. except the background is white.
  154.  
  155. **V4.2:
  156.         An environment variable called JOBSCOLS may be used to specify the
  157. colours to print.  e.g.
  158.  
  159.                          SET JOBSCOLS=1234ABC 
  160.  
  161. will cause colours 1, 2, 3, 4, 10, 11, 12 (hex notation) to print as black, 
  162. while all others will be white.  If JOBSCOLS is not defined, then the behaviour
  163. will revert to that of V4.0 above.
  164.  
  165.         If you're not sure about what to do with JOBSCOLS, ignore it!  It's
  166. not at all necessary in most situations.
  167.  
  168.  
  169.         In order to give a correctly-scaled representation of the screen
  170. graphics, the printer has to have a 2:1 pixel aspect ratio.  This is no
  171. problem for the LA50, LA75 and (I think) LA210 printers.  However, the
  172. LA100 printer does not support an aspect ratio of 2:1 exactly.  This
  173. caused LA100 printouts not to be proportional to the screen image in previous
  174. (4.1 and earlier) versions of JOBSDUMP.  JOBSDUMP 4.2 takes care of this by 
  175. repeating every fourth sixel.  While this approach reproduces the correct aspect
  176. ratio, the output may not always be pleasing;  you should experiment and make
  177. your own judgement.
  178.  
  179.         A similar problem exists for the Epson-compatible
  180. mode of output due to the difference in dot density between Epson printers
  181. and DEC printers.  JOBSDUMP 4.1 ignored every sixth column of dots in
  182. Epson mode, in order to achieve the correct aspect ratio.  This occasionally led 
  183. to a loss in picture quality, especially in pictures with lots of vertical 
  184. lines.  JOBSDUMP 4.2 instead bitwise OR's together every 
  185. fifth and sixth sixel, giving much better results.  In any case, this 
  186. feature can be disabled by invoking the command-line option -ei (the Epson 
  187. option, (I)gnoring the aspect ratio correction), if necessary.
  188.  
  189.  
  190.                      (2) PRINTING OPERATIONS
  191.                      *********************** 
  192.  
  193.         JOBSDUMP allows you to print the graphics either a) directly to the
  194. printer or b) to a file, for later printing using the DOS PRINT command.  This
  195. is useful if you want to print several pictures in background while you do
  196. something else on the computer.  The files created by pre-4.xx versions of
  197. JOBSDUMP were large - about 40k for a small printout and 110k for a large
  198. printout.  This has been drastically reduced in the present version to typical
  199. values of about 4k for a small printout and 8k for a large printout.  It IS
  200. possible to get up to about 35k (small) or 90k (large) if the picture is
  201. sufficiently complex.  However, even with digitized photographs, I have not
  202. yet encountered a large printout larger than 30k or a small printout larger
  203. than 15k.  (For the DEC format, that is - the Epson-compatible output is just
  204. about as big as the old DEC sixel files.)
  205.  
  206.         In any case, to get started, all you have to do is type
  207.         
  208.                                 JOBSDUMP
  209.                                 
  210. and follow the prompts.  This simple invocation will be all that most people
  211. will want.  All of the options are set in roughly the same way.  To select an
  212. option to change, use the up/down cursor keys.  The selected option has an arrow
  213. to its left and its current value is displayed in reverse video.  To change the
  214. value of the current option, use the left/right cursor keys.  The screen
  215. immediately reflects the changed value.  In the print destination option, the
  216. left/right keys toggle between the values "Printer" and "File  OUT.SIX".  If you
  217. have selected "File OUT.SIX" and you would like a file other than one called
  218. "OUT.SIX", pressing the <SELECT> key will prompt you for the new filename.  If
  219. you prefer not to use the arrow keypad, <RETURN> has the same effect as the
  220. down arrow, while the spacebar has the same effect as the right arrow.
  221.  
  222.  
  223.                       (3) COMMAND-LINE OPTIONS
  224.                       ************************
  225.  
  226.         Although the program has a cursor-driven interface, the options can
  227. instead be supplied as command-line parameters using the same type of syntax as
  228. UNIX commands.   For example (spaces other than the first one
  229. after "JOBSDUMP" are optional),
  230.  
  231.             JOBSDUMP -R 2 -S L -F E:\GRAPHICS\SIXLFILE.PIC -D 7 -N -E I
  232.  
  233. will prepare to dump the graphics memory, assuming high (-R)esolution (2), as a
  234. large (L) (-S)ize picture, into the (-F)ile E:\GRAPHICS\SIXLFILE.PIC, pausing
  235. first to (-D)isplay the graphics on the screen for 7 seconds.  Furthermore, the
  236. picture will be in (-N)egative format (just like a photographic negative), if
  237. you have chosen the default colours to print - all except the background.  If, 
  238. on the other hand, you have specified a group of colours to print, the -n 
  239. option will choose these as the colours NOT to print i.e. again, a negative.
  240. Also, the output will be in (-E)pson-compatible format, (I)gnoring correction
  241. of the scaling.  The options set in the command-line will be displayed on the
  242. screen along with the default values for all options not specified.  At this
  243. point, other changes may be made interactively if desired.  When you have set
  244. all of the options, start JOBSDUMP by pressing the <DO> key.  If you want to run
  245. JOBSDUMP unattended or in batch mode, set all of the required options on the
  246. command-line as well as the -g option.  The latter option instructs JOBSDUMP to
  247. -(G)o ahead without waiting for the <DO> key to be pressed.  Full instructions 
  248. on the use of the command-line parameters may be found by typing (the H stands 
  249. for help!)
  250.  
  251.                                  JOBSDUMP -H
  252.  
  253. at the MS-DOS prompt.  The latter instructions may be redirected into the
  254. file "filename" by typing
  255.  
  256.                         JOBSDUMP -H >FILENAME
  257.  
  258. in order to get a permanent record of the instructions.  (A copy of the
  259. latter file is appended to this documentation file.)  As an example of
  260. employing defaults, the command line
  261.  
  262.                         JOBSDUMP -g
  263.  
  264. will cause JOBSDUMP to proceed directly to an active state without any
  265. prompting of the user, using the default values for resolution (2), size (S),
  266. file (LST:, the printer), graphics (DEC), color (colours specified or all
  267. except background) and preview (off).
  268.  
  269. NOTE that there are three items which may only be specified in the commane-line
  270. option set.  The first of these is the -ei option, described above.  In
  271. addition, the -d (display) option takes a second argument which is a number
  272. between 1 and 30 - the number of seconds to display the graphics preview.  If it
  273. is not set on the command line (e.g. -d10) the default preview time is 5
  274. seconds.  Finally, the aspect ratio for the DEC LA100 printer may only
  275. be set from the command line using the -l option described above.  If not 
  276. specified, the default is to use the LA50 aspect ratio (2/1).
  277.  
  278.         The parameters may be entered in ANY ORDER on the command line.  In
  279. addition, there is extensive error checking included in the program.  If any
  280. command line parameter does not make sense to the parser, it is disregarded.  In
  281. addition, if the same parameter is given more than once, the value farthest to
  282. the right in the command line will be the one used.  As the printing proceeds,
  283. JOBSDUMP periodically reports the percentage of the output which has been
  284. completed.
  285.  
  286. ------------------------------------------------------------------------------
  287.                               **WARNING**
  288.  
  289. If you plan to use the graphics preview facility, be sure that you GET THE
  290. RESOLUTION RIGHT!  If you give the incorrect resolution and try to use the
  291. preview option, you will DESTROY THE PICTURE in graphics memory!  (You'll also
  292. get garbage printout, but without preview you won't destroy the picture by
  293. specifying the wrong resolution).  Thus, although the preview option can be
  294. useful, use it carefully.  If you are not sure what the correct value of the
  295. resolution is for a certain type of picture, try each possibility (1,2) WITHOUT
  296. preview first.  You can deduce the correct resolution by whether you get a
  297. printed picture or garbage.  
  298.  
  299. e.g. Lotus 123      uses      MEDIUM                        resolution
  300.      GW-BASIC                 MEDIUM or HIGH
  301.      DRAW14                   MEDIUM or HIGH
  302.      GSX-86                   MEDIUM or HIGH
  303.      RBDVI                    HIGH
  304.      etc., etc.
  305. _________________________________________________________________________
  306.  
  307.  
  308.  
  309.                     (4) ERROR CHECKING (File output only)
  310.                     *************************************
  311.  
  312.  
  313.         Each (size, resolution) combination generates a distinctive
  314. size of sixel-file in the worst case.  If there is less space than this on the
  315. default disk (or the disk specified in the sixel-file <filespec>), the program
  316. flashes a warning on the screen that there MAY be insufficient space.  (The
  317. warning is not given in the CP/M 86/80 version of the program).  Usually,
  318. however, this can be safely ignored except for very complex pictures or very
  319. full disks!  If, during the course of the program, the disk fills up, JOBSDUMP
  320. will halt with a message to that effect.  The portion of the file written up
  321. to that point will be saved.
  322.  
  323.         If the pathname in <filespec> is not valid, or a nonexistent
  324. disk drive is selected, the program reports this condition and halts.
  325. (If a nonexistent disk drive is specified in CP/M, the program halts with
  326. a BDOS error.  However, any other type of file error in CP/M will be
  327. handled by JOBSDUMP.)
  328.  
  329.  
  330.                           (5) USE WITH GW-BASIC
  331.                           *********************
  332.  
  333.         JOBSDUMP may be used as follows inside GW-BASIC:
  334.  
  335.  
  336.  
  337.                        XX SCREEN 2                 'or "SCREEN 1"
  338.                               .
  339.  
  340.                               .
  341.  
  342.                        XX REM User's graphics program, etc.
  343.                               .
  344.                               .
  345.  
  346.                        XX REM The next line is all you need
  347.                        XX SCREEN 0 : SHELL"JOBSDUMP <parameters>"
  348.  
  349.  
  350.         As shown in the example above, the program is invoked as a child process
  351. running under GW-BASIC in MS-DOS.  It is very important to include the statement
  352. "SCREEN 0", since otherwise JOBSDUMP will interfere with the graphics screen.
  353. This is since the "SHELL" command goes to MS-DOS in whatever graphics mode the
  354. computer happens to be using at the time the command is encountered.  The "XX"
  355. in the example above just refers to an arbitrary line number in GW-BASIC. The
  356. field "<parameters>" refers to the command-line parameters described above.
  357.  
  358.         Both COMMAND.COM and JOBSDUMP.COM must be accessible from within
  359. your GW-BASIC program, so you should already have issued the PATH command
  360. (possibly in AUTOEXEC.BAT) to enable MS-DOS to find JOBSDUMP.COM.  In
  361. addition, make sure that the environment variable COMSPEC is pointing
  362. at a valid copy of COMMAND.COM.  This is automatically taken care of as long as
  363. COMMAND.COM is on the disk from which MS-DOS was started.
  364.  
  365.  
  366.  
  367.               (6) USE DIRECTLY FROM THE MS-DOS or CP/M 86/80 PROMPT
  368.               *****************************************************
  369.  
  370.     JOBSDUMP may instead be run directly from the MS-DOS prompt, and it
  371. will print out whatever data remains in the RGO memory, even if it has not
  372. been generated by a GW-BASIC program.  Once an application (such as Lotus
  373. 123, GW-BASIC etc.) has written data into graphics memory, it remains there
  374. until the computer has been turned off unless it is overwritten or erased.
  375. The graphics memory will even survive a <SETUP>/<CTRL><SETUP> reset
  376. operation, as long as the power is not interrupted.  You must know what the
  377. resolution of the graphics data is, in order to get the correct results the
  378. first time.  However, if you make the wrong choice and garbage is printed
  379. out, it is possible to abort and try again with the correct resolution.  This
  380. is possible since JOBSDUMP was written to be unable to erase or otherwise harm
  381. graphics memory.
  382.  
  383.  
  384.         For example, instead of the last line in the GW-BASIC example above, you
  385. could use the statement:
  386.  
  387.                                 XX SCREEN 0 : SYSTEM
  388.  
  389.  
  390. which would take you back to MS-DOS.  Now, typing "JOBSDUMP <parameters>" would
  391. have exactly the same results as you would get using the GW-BASIC example above.
  392.  
  393.  
  394.  
  395.  
  396.               (7) DIFFERENCES IN CP/M VERSION OF JOBSDUMP
  397.               *******************************************
  398.               
  399.         The CP/M version is identical to release 4.0 of MS-DOS JOBSDUMP.  It 
  400. has all the same features as V4.2 except:  (i) the enhanced Epson correction;
  401. (ii) the LA100 handling capability;  (iii) some minor cosmetic bug fixes.
  402.  
  403.         Other minor differences occur in the error handling described in 
  404. section (4) above: (i) the program does not like to get an incorrect disk
  405. drive in CP/M  and (ii) disk space warnings will not be given in CP/M.
  406.  
  407. -------End of JOBSDUMP documentation
  408.  
  409. -------Output of JOBSDUMP -h follows
  410.  
  411. JOBSDUMP [-r [{1|2}]] [-s [{s|l}]] [-f [<filespec>]]
  412.          [-e [i]] [-n] [-l] [-d [nn]] [-h]
  413.  
  414. JOBSDUMP V4.2 prints out DEC Rainbow graphics memory contents
  415. to a DEC- or Epson-compatible printer, or to a disk file.
  416. Any subset of colours may be specified for printing as black.
  417.  
  418.     -r sets the resolution   :         1 = medium
  419.                                        2 = high (default)
  420.  
  421.     -s sets the size         :         s = small (default)
  422.                                        l = large 
  423.  
  424.     -f sets the output file  :         PRN = printer (default)
  425.                                        <filespec> = named file (w/pathname)
  426.  
  427.     -e outputs Epson format  :         i = ignore correction
  428.  
  429.     -n gives a "negative" printout
  430.  
  431.     -l corrects the aspect ratio for LA100 output
  432.  
  433.     -dnn shows the picture   :         nn = display time (secs)
  434.  
  435.     -h gives this help
  436.  
  437.     -g starts the program immediately without pressing <DO>
  438.  
  439.  
  440. The default is to print out all colours except colour number 0,
  441. the usual background colour.  If the environment variable
  442. JOBSCOLS exists, it is used to set the colours to be printed
  443. as black.   For example, entering
  444.  
  445.                  SET JOBSCOLS=12ACD
  446.  
  447. prints colours 1, 2, 10, 12, 13 in black.  Colours are in hex
  448. notation and are 0-3 for high resolution and 0-F for medium
  449. resolution.  Note that the default is equivalent to
  450.  
  451.                  SET JOBSCOLS=123456789ABCDEF
  452.  
  453. Note also that, if -n were invoked on the command line, the default
  454. colour settings could be obtained using
  455.  
  456.                  SET JOBSCOLS=0
  457.  
  458. ____________________________________________________________
  459.  
  460.  
  461. If you appreciate the benifits of this software, and would
  462. like to show your appreciation, please send a $25 donation
  463. to the author:
  464.                     James A. O'Brien
  465.                     1166 Hope St. #6
  466.                     Stamford, CT 06907
  467.                             USA
  468.                             
  469. -------End of JOBSDUMP -h output
  470.