Article # 189, added by Geoworks, historical record
| first | previous | index | next | last |

How the null modem lines should be connected.


Screen Dumper Instructions

Introduction
------------

As part of our on-going efforts to make PC/GEOS more enjoyable, we
at Geoworks have released for your use a simple utility, called
"Screen Dumper," that allows you to dump screens, windows, and even
portions of a window to DOS files. This is the manual for that utility.
Screen Dumper creates screen dumps in many formats, including
Encapsulated PostScript and TIFF. It can even create color dumps.

Before we go further, it's time for a disclaimer:

"Screen Dumper" is unsupported software. It is provided as-is in the
hope that it will be useful, but without any warranty of any kind,
express or implied. On no account will Geoworks be responsible for
any damage arising out of the use of this program.  If you're not
comfortable using this utility on these terms, please don't use it.

Before You Dump Your First Screen
---------------------------------

Before you attempt to dump a screen, the screen dumper will make sure
your PC/GEOS system is properly configured. This configuration
involves disabling the blinking of text cursor throughout the system
in order to avoid a deadlock (similar to gridlock) when you dump all
or part of the screen.

When you launch the screen dumper for the first time, you will get a
dialog box telling you that it must turn off the blinking of your
cursor. When you click Ok, PC/GEOS will shutdown and automatically
restart, leaving you just where you were, but with your text cursor
not blinking. When you are done dumping screens, you may wish to
re-enable the blinking by choosing the Enable Blinking Cursor Again
option from the Options menu. The blinking will be back when next you
start up PC/GEOS.

Start Screen Dumper and Set the Options
---------------------------------------

Start PC/GEOS the way you normally would and enter the Professional
Workspace. Double-click the Screen Dumper icon in the GeoManager
window to start the utility. The Screen Dumper window appears:

You should click Read Me the first time you launch Screen Dumper so
you know under what conditions you are using it. Once you've read it,
you can ignore that button forever.

By now it's too late to point you to the Help text, since you're
reading this manual, but it'll provide you with a quick summary of the
keys you can use to create screen dumps, should you forget.

You should change the options in the window before you dump your first
screen.

Base Name: Screen Dumper uses this name to create the file for each
screen dump. It replaces the percent symbol (%) with the current Dump
number. So, if you had a base name of

	\screens\dump%

the first file you would create would be "\screens\dump00.tif"
(assuming that you were dumping in TIFF format). The next file
would be "\screens\dump01.tif" and so on.

If you don't make this name absolute (by starting with a \), the path
you give will be taken as relative to the DOCUMENT directory in the
GEOWORKS tree.

Dump Number: Each screen that you dump is placed into its own file. To
give each file a unique name, Screen Dumper replaces the percent sign
(%) in the Base Name with the current Dump Number. Every time that you
dump something, the number goes up by one.

Normally you change the Dump Number by clicking the two arrows.
However, if you decide to enter a number from the keyboard, you must
press Return before the number will take effect.

Formats: You can dump screens in any one of five formats:

Raw Bitmap
This is a format that is useful only here at Geoworks and is included
only for historical reasons. It places the different slices of the
screen dump in an internal bitmap format that we used to convert to
PostScript before we changed Screen Dumper to create PostScript dumps.

Full-Page PostScript
Used to create single-page full-screen dumps, usually, though it will
work with any of the regular dumping options (given below). The main
differences between this and Encapsulated PostScript is a full-page
dump has a showpage command at the end of the dump, and the dump is
centered in the indicated page space (See PostScript Parameters,
described below).

Encapsulated PostScript
This is a good format to use if you wish to include a screen dump in
a document that is to be printed on a PostScript printer.

TIFF
Creates a black and white, 16-color, or greyscale TIFF file in Intel
byte-order. Some Macintosh programs have had difficulty with files
produced in this manner.

PC-Paintbrush
This is the standard PCX format used in the PC world. Screen Dumper
can create either black and white, or color PCX files.

Note that no bit image is produced with either of the PostScript
options. If you import the file to PageMaker or some other graphics
program, you will see a grey box, not a screen image. This has no
effect on the printed output.

Annotation:
Screen Dumper can create a log of all the screens dumped. Turn the
Enable option on and change the Log name to be the appropriate file
name. Turn Append on if you want to preserve the current contents of
the log file, or turn it off if you want to completely replace the
current contents.

With the Enable option turned on, Screen Dumper presents a dialog box
every time you dump a screen. In this dialog box, you can enter a bit
of text that identifies the screen that you've dumped. This text is
then added, along with the file name, to the log file.

Banish:
You can leave the Screen Dumper window on the screen if you choose.
However, if it gets in the way of your screen dump, you can banish
it before dumping. When you click Banish on the menu bar, the window
disappears, even though the program is still present and functioning.
To get the banished Screen Dumper window back, enter control mode by
holding CTRL and SHIFT and then pressing TAB. Press F1 to get the
window back.

Options:
When you choose either PostScript option, or the TIFF option, there
are additional parameters you can set. These are available as the
Postscript and TIFF entries in the Options menu.

Set the PostScript Options, if necessary

When you choose to dump in either of the two PostScript formats, you
have additional options that can affect the final output:

Image Name:
The name that you enter here appears on the grey box that represents
the PostScript image when you paste it into your document (in some
desktop publishing programs, such as PageMaker). The name serves only
to document the contents of the screen dump file; it has no effect on
the image itself, or on the name of the file in which the dump is placed.

Color:
Choose the type of color model you wish to use for the screen dumps.
You should choose a model that works with the equipment that you will
use to print the dumps. Use RGB if you will be viewing the dumps on a
color monitor. For color printers, CMYK is usually the appropriate
color model, while Greyscale is best for black and white printers and
monitors. The resulting screen dump for both RGB and CMYK uses the
color extensions to PostScript (specifically, the colorimage operator).
If the device doesn't support this operator, you should choose
Greyscale, as choosing the wrong model will likely give you a
PostScript error when you attempt to print the document.

Number of Copies:
For full-page PostScript images, you can print several copies of each
dump. This is especially important for color PostScript dumps, as some
dumps can take up to half an hour to process, but once processed, the
printer can print several copies relatively quickly. Enter the number
of copies desired in this field.

Orientation:
This option is mostly for full-page PostScript format. If you choose
Portrait orientation, the image will print normally. If you choose
Landscape orientation, the image will print sideways. This is useful
for full-page dumps, as it is much closer to the aspect ratio of a
monitor than Portrait is.

Width, Height:
This is the size of the image, in inches. Your dump will appear to be
this size when you print it. If the dump isn't actually this size on
the screen, then it will be stretched to fit. There currently is no
way to have Screen Dumper automatically size the Width and Height to
match the dump, so you will have to manually size the image when you
import it into your document.

Paper Size:
This option is only relevant to full-page PostScript screen dumps.
You can choose the size of the paper on which you print the image.
The image will be centered within this space.

Set the TIFF Options, if necessary

If you are dumping to a TIFF file, you have additional options that
may be reached using the TIFF entry in the Options menu:

Dump Color As:
When dumping to a TIFF file on a color screen, the colors can be placed
in the file as-is, or mapped to the appropriate level of gray (one of
16). This option has no effect if you're dumping a monochrome screen.

Image Compression:
This option is currently not supported, but will allow you to specify
how the image is to be compressed, if it is to be compressed. Packbits
is a simple run-length encoding scheme used on the Macintosh, while
LZW is an adaptive compression scheme that is widely used and provides
good compression for color dumps. As a general rule, you should use
Packbits for monochrome dumps and LZW for color dumps. Be aware,
however, that some programs (notably older versions of PageMaker)
cannot handle LZW-compressed images.

Using the Screen Dumper
-----------------------

Prepare the screen dump by starting the necessary applications and
opening the appropriate documents. When the screen is properly set up,
dump the portion of the screen that interests you.

One way to dump a screen is to enter control mode and press one of the
function keys. In some cases, you can simply press a shortcut key.

While you are in control mode, the screen is frozen and you can type
Screen Dumper commands on the keyboard. You can still move the pointer
around on the screen, but it will return to its original position when
you leave control mode (either by dumping the screen or by pressing ESC).

Dumping the Entire Screen
-------------------------
Press  SHIFT + PrtScrn

Or, hold down CTRL and SHIFT, and press TAB. This freezes GEOS temporarily
and puts you in Dumper control mode. Press F6 to dump the screen.

If you've enabled the Annotation feature, a dialog box will appear so
you can enter a description of the dump:

Annotate: This writes the notes to the log file you selected in the
main window preceded by the name of the file to which the dump was
made, e.g.:

	================
	betadocs\dump03.pcx
	That was the annotation box

Cancel dump: Clicking this causes the dump number not to increase and
the dump to effectively be forgotten. Use this if you made a mistake
in the dump and want to go back and do it again.


Dumping a Particular Window
---------------------------

1. Hold down CTRL and SHIFT, and press TAB. This freezes PC/GEOS
   temporarily and puts you in Dumper control mode.

2. Position the pointer on the title bar of the window you wish
   to dump.

3. Press F3 to dump the window without the pointer, or press F4
   to dump both the window and the pointer.

If you've enabled the Annotation feature, a dialog box will appear so
that you can enter a description of the dump (see above). Click
Annotate to complete the dump.

For keyboards that contain the extended function keys, you can skip
all three steps above and simply press F11 to dump the window without
the pointer, or press F12 to dump the window with the pointer.


Dumping a Portion of the Screen
-------------------------------

1. Hold down CTRL and SHIFT, and press TAB. This freezes GEOS
   temporarily and puts you in Dumper control mode.

2. Press F5 to show the dump rectangle. This dotted rectangle
   outlines the area of the screen that will be dumped. Change the
   size and position of the dump rectangle with the numeric keypad.


Keypad Key	Action
------------------------------------------------------------------------------
1 to 9		Moves the dump rectangle one pixel in the 
		direction of the key (e.g., pressing 9 moves 
		the rectangle one pixel up and to the right).

ALT + key	Move the dump rectangle eight pixels at a time.

SHIFT + key	Enlarges the dump rectangle one pixel in the given 
		direction. Hold ALT down, too, to enlarge it eight 
		pixels at a time.

CTRL + SHIFT + key	Shrinks the dump rectangle one pixel in the
		given direction. Hold down ALT, too, to shrink it
		eight pixels at a time.

3.	Press F6 to dump the screen surrounded by the dump rectangle.

If you wish to dump the same portion of the screen over and over
again, position and size the dump rectangle the first time you dump
the screen. For subsequent dumps, press CTRL + SHIFT + TAB to enter
control mode and press F6 to dump the same area as before.


If you decide not to dump...

If you've decided not to dump after already pressing CTRL + SHIFT +
TAB to enter control mode, press ESC to leave control mode and "thaw"
GEOS.

Tips and Advice
---------------

Experience has shown there are some quirks you should know in order to
use the Screen Dumper well.

Placing EPS into PageMaker

Screen Dumper does not include a bit-image of the screen with
PostScript dumps. While this has no effect on printing, it does mean
that most programs will only show you a grey box when you import the
dump. The program should display the name you gave the image in the
PostScript Parameters box, so you won't be lost.

TIFF dumps

When you select TIFF format, Screen Dumper dumps the screen in PC TIFF
format. You may find it difficult to import PC TIFF files into
Macintosh programs (though some programs, notably PageMaker, can
handle importing PC TIFF files). In order to even see the file in a
file selector, you may need to use "Res Edit" to change the file's
token to be TIFF (we set the creator to be DGDR-Digital Darkroom_).
Some programs prefer color TIFF files to be in the form of greyscale
dumps (e.g. Aldus Freehand_) while others have fits if given a
greyscale dump and much prefer color (e.g. Aldus PageMaker). You'll
have to experiment.

When dumping a window, put the pointer on the title bar

When you dump a window, Screen Dumper dumps the window that is
directly under the pointer. In many cases, though, PC/GEOS windows are
built up from a few little windows that don't look like windows. The
GeoManager window is a good example of this. The icons sit inside a
window within the GeoManager window. If you were to put the pointer
over this area and dump the window, you would get the icons and the
surrounding rectangle, but not the surrounding GeoManager window.

To avoid this kind of problem, always put the pointer on the title bar
before dumping the window. This will dump the window and all the
windows contained within it.

Setup Screen Dumper, then exit PC/GEOS to freeze its state

It can take a bit of time to prepare Screen Dumper. If PC/GEOS should
crash for any reason, you will have to prepare Screen Dumper all over
again (since it won't have been able to save its state).

For this reason, it's usually a good idea to shut down PC/GEOS as soon
as you've set up for your first dump, to force Screen Dumper to save
its state. This way, if PC/GEOS should crash while you're dumping a
screen, Screen Dumper will still be prepared when you start PC/GEOS
again. Just be sure not to answer "Reset Professional Workspace" when
Welcome asks what it should do about the abnormal exit that occurred
last time.


======================================================================


See also: Why does Swat "time out"?

Are you experiencing the error "Can't contact PC: Call timed out"
when you run Swat? Does PCCom seem to work correctly between the
the two PCs? If so, then perhaps you have a null modem cable that
is not a true null modem. Swat is picky about the exact wiring of
the null modem cables. Below are the configurations we recommend
for your null modem cable.

Here are two possible configurations for 9-pin cables:

In  Out    In   Out
-------    --------
1   4      1    -
2   3      2    3
3   2      3    2
4   1,6    4    6
5   5      5    5
6   4      6    4
7   8      7    8
8   7      8    7

Here are three possible configurations for 25-pin cables:

In  Out    In   Out    In   Out
-------    --------    --------
1   1      1    -      1    1
2   3      2    3      2    3
3   2      3    2      3    2
4   8      4    1      4    5
5   20     5    -      5    4
6   20     6    -      6    20
7   7      7    7      7    7
8   4      8    -      8    20
.
.
20  5,6    20   1      20   6,8