                  24-pin Printer Screen Dump Utility v. 2.0          10/18/88
                                    by
                                Dan Wilga


This program is designed as a replacement for the screen dump function built-
into GEM, for people who, like me, went out and bought a 24-pin printer only
to discover that GEM was not designed to take full advantage of the higher
resolutions offered by these printers. The program includes the ability to
choose various sizes for the output, send the printout in "landscape" mode,
or even directly to a disk file so that multiple copies of the same dump
can be made easily.

Changes from version 1.0:

  The default scaling for high resolution has been corrected.
  Scaling factors may now range from 1 to 9, not just 1 to 4 or 8. Using a
      number that cannot be evenly divided into 24 for the y-scaling
      (5, 7, or 9) produces extra lines of dots. They are really barely
      noticeable though.
  Landscape dumps can be made.
  A configuration file can be used to specify new default values.
  Output to disk is slightly faster now that it is buffered.
  Previously, sending two screen dumps of different lengths without
      deleting the disk file in between would cause the file to be
      garbaged if the second output was shorter than the first.
  Also, in the first version, pressing Control-C to stop a program would
      cause a system re-boot under TOS 1.4.

Use:

  To install the screen dump program, either place SCRDMP24.PRG in the AUTO
  folder of the disk you boot your system with, or click on this file from
  the desktop. If you are using a configuration file for the default settings,
  place this file in the same folder as the program, unless you have placed
  SCRDMP24.PRG in an AUTO folder for automatic execution at boot in which case
  you should place the config file in the *root* directory. See below for a
  description of the contents of the configuration file.
  
  From that point on, whenever you hold down the Alt key and press Help (or
  select "Print Desktop" ) my program takes over.
  
  This program also intercepts any calls to the XBIOS command Scrdmp(), or
  the VDI function v_hardcopy(). This is possible because Atari provided
  one vector that would take care of all these situations. The only programs
  this one is incompatible with are those that also intercept the Atl-Help
  key combination.
  

Scaling:

  This program has the ability to expand the image being printed in both the
  horizontal and vertical directions. This is necessary because if no scaling
  is done on a 24-pin printer then, at 360 dpi, a medium resolution image
  ends up being 640/360, or 1.8 inches wide!
  
  Scaling causes the data for each row or column of dots that make up the
  picture to be duplicated. For instance, a scaling factor of (2,2) -- the
  first '2' refers to the horizontal direction, and the second to the
  vertical -- will mean that each row and column of dots is duplicated once,
  (3,3) means each is duplicated twice.
  
  Because of the way 24-pin printers work, you will probably not be that
  thrilled with the quality at (1,1) scaling anyway, not to mention the
  size of the picture. In order to give the printer head time to shoot-out
  enough ink, you usually have to use a scaling of atleast (2,2).
  
  For landscape printing, the x-scale refers to the scaling of the image
  across the narrow edge of the printed page. Please note that a y-scale
  of nine in landscape mode produces unusual results.

  If you want to get a printout that does not look distorted, you should set
  the ratio of the scaling as follows. The "Largest" column shows you the
  largest scaling that will fit completely on an 8.5 x 11" page for that
  resolution and mode, while maintaining the appropriate ratio:
  
                  -- Normal Mode --     -- Landscape Mode --
  Resolution:     Ratio:    Largest:    Ratio:      Largest:
  ----------      -----     -------     -----       -------
     low           2:1       (8,4)       2:1         (4,4)
    medium         1:1       (4,4)       4:1         (4,2)
     high          2:1       (4,2)       2:1         (2,2)

Landscape Mode:

  Sometimes it is preferable to have the picture sideways on the page. This
  is referred to as "Landscape Mode". This is the opposite of "Normal" or
  "Portrait Mode".

Changing options:

  If a configuration file is not present when this program has been first
  run, then the scaling factors are set for the resolution you booted in,
  according to the first "Largest" column of the chart above. Also, output
  defaults to the printer and in Normal mode.
  
  To change these settings, you simply have to do the following:
  
    1.  Press Alt-Help.
    2.  You then have a few seconds to enter parameters. Begin by typing a
        horizontal scaling factor from 1 to 9 by simply pressing the
        appropriate key on either the numeric keypad or the main keyboard.
        If a correct key has been pressed, you will see the screen flicker
        briefly to show you that your input has been accepted.
    3.  If you selected a horizontal scaling factor, you can then do the
        same for the vertical. Again, this is a number from 1 to 9.
    4.  The next parameter determines where the output is to be sent. Press
        the "d" key to send it to a disk file, or the "p" key to send it to
        the printer.
    5.  The final parameter chooses Portrait or Normal modes. Press either
        the "p" or the "n" key.
    5.  When all parameters have been entered, or too much time has elapsed
        between keypresses, a bell will sound. This means that output is
        about to begin.

  If you skip a setting, it will retain its previous value. For example:
  
    You have just re-booted in medium resolution without a configuration file.
        The default settings for this resolution are "4", "4", "p", and "n".
    You press Alt-Help.
    Then, you hit the "2" key and wait for the bell to sound.
    The result would be 2-times scaling in the horizontal direction, 4-times
        in the vertical, and output going to the printer in 

  This also means that if you send one printout to a disk file and then want
  to revert to using the printer, you will have to use the "p" option.

  The one disadvantage to this method is that if you just want to change the
  y-scaling, you must first set the x-scaling, since the order is critical.

Disk Output:

  When the "d" option is active, the output is redirected from the printer
  to a disk file. The name of the file will always be "SCRDMP24.DAT" and it
  will always be in the root directory of the drive that SCRDMP24.PRG was on
  when you first ran it.

  If, for some reason, the file could not be opened, output is sent to the
  printer. Beware that there is very little error handling for this feature.

Stopping:

  Since any screen dump can be time consuming (not to mention noisy) you
  will be glad to know that a very responsive method of aborting has been
  included. Simply hold down the Control key and press "c". This will free-up
  the mouse almost immediately.
  
  One caution about stopping:  If you have aborted a screen dump and you then
  send something else to the printer (even another screen dump) without
  clearing its internal buffers, you will most likely get alot of garbage.
  To clear the printer's buffer, either turn it off and back on again or
  refer to your manual on how this can be done from the printer's front
  panel controls.

Configuration File:

  When the program is first run, it looks in the folder where it is for a
  file called SCRDMP24.CFG. (if the program is run from the AUTO folder at
  boot time, then the config file must be in the *root* directory of the
  boot disk, this is a system limitation) If this file is found then its
  contents are read and the default settings are changed accordingly. The
  new defaults are displayed on the screen.
  
  The format for config files is very rigid, due to the simplicity of the
  code that reads the file. All data must appear in the first column after
  the carriage return. Numbers for scaling must be only one digit each and
  must be separated with a sigle space or other character.
  
  Comments can also be entered in the file by starting the line with a
  semi-colon (;) character.
  
  The general format for the options within the file is as follows:
  
      ;comments
      [low-rez scaling in "x y" format]
      [med-rez scaling]
      [high-rez scaling]
      ["d" or "p" to set Disk or Printer]
      ["l" or "n" to set Landscape or Normal]
  
  The order of the lines is not important for the most part. If you want to
  put the Disk option before the comments and the Landscape option in between
  medium and high-rez scaling, that is fine. The only important thing is that
  the low-rez scaling is followed by the medium-rez, which is in turn followed
  by the high-rez, somewhere within the file.
  
  The following example is the one that should be included with this program
  and its values match those that would be present even if no config file
  was found:
  
      ; This is a comment
      8 4       The rest of the line is ignored. Set low-rez scaling to (8,4)
      4 4       Medium rez.
      4 2       High rez.
      l         Choose Landscape mode.
      p         Choose Printer output.
      
Potential Problems:

  The only possible problem I can see would arise in different interpretations
  of the code used to line feed the printer to the next line. This program
  was tested on a Star NX-2400 which has both a "native" mode, and an "IBM"
  mode. In IBM mode this code will result in the carriage not moving down
  far enough past the line that was just printed and the next line will
  overlap the previous one. For this reason, this utility should only be
  used when your printer is in "native" mode, not "IBM" mode. The code used
  to do this is "ESC J".

                                  Enjoy it!

                                  Dan Wilga
                                  GEnie:  GRIBNIF
                                  Bitnet: Gribnif@UMASS.Bitnet

