The CAPTURE Tool

CAPTURE will copy all (or only part) of the text displayed on a terminal screen (or contained in terminal memory) to a printer or a designated disc file. The terminal must obey standard Hewlett- Packard terminal control codes.

CAPTURE may be executed either as a stand-alone program or as a callable procedure. Several options are available at run-time that permit you to capture only that portion of the screen desired, in the format you require.

Operation

To use CAPTURE as a stand-alone program, simply type: CAPTURE at the system prompt. Doing this will cause CAPTURE to copy your entire screen memory to the line printer. Like all LPS-Tools, CAPTURE displays the standard LPS-Tools banner. In this case, however, the banner display follows the screen dump. See the following screen display for an example of how this works.

Figure 4.1 CAPTURE Screen

You are limited to capturing up to 1023 characters per line on the screen. You may suppress portions of the informational displays that usually follow a successful screen capture, and you may also suppress some of the error handling procedures of the program.

CAPTURE permits you to control the handling of escape codes that are often present on a screen, but not always desirable in a copy.

Capabilities

Program capabilities required include IA, BA, DS, and PH. No special user capabilities are required to run CAPTURE.

Usage

The MPE syntax for executing CAPTURE is:

RUN CAPTURE.PUB.LPSTOOLS [;INFO="keywords"][;PARM=parms]

The default mode of operation sends a copy of the entire terminal memory to the system line printer, which is designated with the formal file name of LPSLP.

NOTE There are many keywords (see Table 4.1) available for use with CAPTURE using the INFO="keywords" option. You must supply the full keyword, or only the portion indicated with capital letters. More than one keyword may be used; the space character is the delimiter.

Option Summary

Unlike other LPS-Tools, CAPTURE is a single-command tool, where the CAPTURE command is the only command that can be specified. Several options, however, can be used to further define the task at hand. These options are listed next.

Table 4.1 CAPTURE Options

Option	Description
COMPRESS	Compressed portrait output to LaserJet
CUT firstcol/lastcol	Specify columns to capture
FF	Formfeed line printer
FFL	Formfeed LaserJet
FLAT	Directs output to a disk file
HELP	Starts CAPTURE’s help subsystem
Landscape	Landscape output to LaserJet
LEFT column	Specifies left column to capture
[NO]CHEck	Limits error checking activity
[NO]ENHance	Strips display enhancements
[NO]ENHOFfeol	Adds printer escape sequence at end of line
[NO]RESETL	Reset LaserJet
[NO]SETMSG	Controls SETMSG use during capture
[NO]STAmp	Provides for a date and time stamp to be displayed
[NO]SUMmary	Suppresses line & timestamp on the screen
OFFSET	Specifies offset in output column
PARTial	Captures a user-specified range of lines
QUIET	Suppresses error messages
RIGHT column	Specifies right column to capture

CAPTURE Commands

CAPTURE (parm=0)

(No parameters)

Running CAPTURE without any options causes your entire screen memory to be captured.

CAPTURE starts copying from the top of terminal memory (line number 1) and copies through the line that contains the cursor’s original location. CAPTURE does not alter terminal memory. The output from CAPTURE will be sent to the line printer attached to your system. The formal file equation that CAPTURE (as well as all other LPS-Tools) uses is LPSLP. To redirect CAPTURE’s output to a line printer other than LP, simply issue an appropriate file equation.

Options Definitions

CAPTURE options may be specified as keywords in the INFO string or as bits in the PARM value.

COMPRESS

Format for LaserJet compressed output. This option can be used in Landscape mode.

CUT firstcol/lastcol

This option is used to specify the column range (where n equals the column number) used in the capture.

FF

This option instructs capture to send a formfeed command at the end of the screen capture. It is used for line printer output.

FFL

This option is the same as FF except that it is used for LaserJet output.

FLAT

This option is used to tell CAPTURE that you wish to redirect output to a disk file. The formal file designator for the disk file is also called FLAT. You may redirect output to a file of another name by using an appropriate file equation.

NOTE The file is built with a default record length of 80 bytes, that it must not exist prior to running CAPTURE, and that if a system problem prevents the saving of the file as permanent, an attempt will be made to save it as session temporary. When FLAT is used, only the lines of text in terminal memory are copied to the disc file. There will be no additional information lines appended by CAPTURE for audit purposes, such as information summaries or date and time stamps. CAPTURE will not purge any existing file when the FLAT option is used.

HELP

Starts Capture’s help subsystem.

Landscape

Format for LaserJet landscape output.

LEFT column

This option is used to specify the starting (left) column for the capture.

[NO]CHEck

This option inhibits CAPTURE from checking certain error conditions. This can be useful if you have non-HP terminals that are similar to standard, but that would be ignored by CAPTURE if it detected the error conditions. Using NOCHECK also causes CAPTURE to ignore errors that might be generated when running in BATCH mode.

Be sure that you understand what you are doing when you use this option. Ports and jobs could be hung if this option is used improperly.

[NO]ENHance

When NOENHANCE is specified, the text read from terminal memory is examined for escape sequences that control the screen enhancements. If any are found, they are removed.

[NO]ENHOFfeol

ENHOFFEOL forces a special escape sequence to be appended to any line that has a screen enhancement. This special sequence manually terminates the enhancement, which is useful when the output is directed to a LaserJet. In normal operation, use of enhancements may cause unexpected LaserJet output if proper enhancement terminators have not been used, ENHOFFEOL solves this problem.

[NO]RESETL

Resets the LaserJet with an <esc> E before sending the capture.

[NO]SETMSG

This option controls whether or not capture uses SETMSG ON (default) or SETMSG OFF.

[NO]STAmp

CAPTURE provides for a date and time stamp to be displayed on the screen at the start of the screen capture process, and for this line to be displayed at the end of any LPSLP listing. Use of the NOSTAMP keyword will suppress the display on the listing; the display on the screen will remain.

CAPTURE provides for a date and time stamp to be displayed on the screen at the start of the screen capture process, and for this line to be displayed at the end of any LPSLP listing. Use of the STAMP keyword will ensure that the display appears on both the listing and the screen. This keyword is a default setting.

[NO]SUMMARY

CAPTURE provides for a summary of the number of lines printed and the keywords selected to be displayed on the screen at the start of the screen capture process. Use of this keyword will suppress this display from the screen.

NOSUMMARY also suppresses the display of the date and time stamp on the screen. However, this information line will be displayed on the LPSLP listing.

OFFSET #

This option is used to specify a column offset for the capture output.

PARTIAL

Using this option tells CAPTURE to capture only a portion of the lines in terminal memory. CAPTURE will interactively request that you mark the last line an then the first line of text that you want to CAPTURE. Use of this option will suppress the information summary (see SUMMARY) from the display.

QUIET

Suppresses CAPTURE’s error messages.

RIGHT column

This option is used to specify the ending (right) column for the capture.

PARMs

You may use PARMs instead of INFO= strings in many circumstances. Table 4.2 indicates the parm value, the INFO= keyword string to which it is equivalent, and the bit location of the keyword when represented as a binary value.

Table 4.2 CAPTURE’s PARM

Parm	Bit	INFO= String
32768	0	HELP
16384	1	QUIET
8192	2	RESETLaserjet
4096	3	COMPRESSED Laserjet
2048	4	LANDSCAPE Laserjet
1024	5	<internal use>
512	6	FFLaserjet
256	7	FF line printer
128	8	NOSETMSG
64	9	NOSTAmp
32	10	ENHOFfeol
16	11	NOENHance
8	12	NOSUMmary
4	13	NOCHEck
2	14	FLAT
1	15	PARTial

Combinations of keywords may be represented by adding the parm numbers (their decimal values) together. For instance, to combine NOCHECK with NOSUMMARY you need only add 8 and 4 yielding a parm value of 12. This is equivalent to setting bits 12 and 13 to an "on" value in a binary string.

TOOLBOX STANDARDS

The ToolBox collections from Lund Performance Solutions have a uniform user interface. As a result, in addition to the commands specific to each Toolbox tool, most tools allow the commands described in "TOOLBOX STANDARDS".

CAPTURE Examples

Use CAPTURE to select portions of the terminal screen, send the contents to a flat file, or combine various options. Combine the two (CAPTURE and PARTIAL) of CAPTURE’s options to realize a partial screen capture. See Figure 4.2. Do this with the command CAPTURE PARTIAL.

Figure 4.2 Capturing a Portion of Screen Memory

Figure 4.3 shows the Capture of columns 10 through 30 and starting output in the capture file at column 8.

Figure 4.3 Column CAPTURE

The following example demonstrates how to set a file equation so that CAPTURE’s output goes to the filename of your choice.

Figure 4.4 Sending CAPTURE Output to a File

Using CAPTURE as a Callable Procedure

CAPTURE may be used as a callable procedure from both CM and NM programs. To include CAPTURE in a CM program, refer to the USL file in the USL group of the LPSTOOLS account. For inclusion in an NM program, take a look at the NMOBJ file in the O group. The following display is from the file CAPTURE.PASCAL.LPSTOOLS. Use it as a reference in implementing CAPTURE in your program for sending screen memory to the line printer. Also provided are examples in C, COBOL, and SPL, as well as RL and XL versions of the executables.

Figure 4.5 CAPTURE as a Callable Procedure

Using CAPTURE Procedures in COBOL

The following code fragment illustrates the use of CAPTURES in COBOL code where whatever is on the screen is sent to the line printer.

Figure 4.6 CAPTURE Procedures in COBOL

Using CAPTURE Procedures in SLPash!

The following code fragment illustrates the use of CAPTURE in SPLash!, the native mode SPL compiler. Whatever is on the screen is sent to the line printer.

Figure 4.7 CAPTURE in SPLash

CAPTURE Error Messages

Each CAPTURE error message is described in the following table.

Table 4.3 CAPTURE Error Messages

Message	Cause	Action
Could not open FLAT file	Possible bad file-equation for FLAT.	Check file equation for FLAT with the HP command LISTEQ.
Could not open LPSLP	Possible bad file-equation for LPSLP.	Check file equation for LPSLP with the HP command LISTEQ.
Error in attempt to turn off echo.	As part of the screen capture process, CAPTURE needs to disable echo on the terminal - temporarily.	Try running CAPTURE again with PARM=4.
Error writing to LPSLP	Possible bad file-equation for LPSLP.	Check file equation for LPSLP with the HP command LISTEQ.
I/O error in reading terminal status	During an fcontrol(,4,3) (a three second read) CAPTURE received an error status.	Try running CAPTURE again with PARM=4.
I/O error on read from screen	CAPTURE failed to read a line of text from the screen via an ESC d command.	Terminal may not be compatible with HP26xx commands. Try again with PARM=4.
Not a 26xx terminal	CAPTURE determined that the terminal was not compatible with the HP 26xx command set.	Depending on the terminal, running with PARM=4 may allow correct CAPTURE operation.
Too many empty lines found (more than 99)	CAPTURE remembers how many empty (consecutive) lines it has read. Currently the maximum allowed is 99. CAPTURE does this so that a "runaway" screen capture will not send (possible thousands) unwanted empty lines to LPSLP.	Make sure that the CAPTURE range (for a partial capture) is valid.
Too many lines found (more than 9000)	CPATURE can only screen capture 9000 lines at a time.	Use CAPTURE’s partial option to break the screen capture into smaller pieces.
Unknown CAPTURE option:	An invalid option was input.	Make sure that the option is spelled correctly. It may have captured the screen contents anyway and disregarded the invalid option. Try CAPTURE again, using the correct option.