CAPTURE

CAPTURE

Support Command

Redirects DATAPLOT alphanumeric output to the specified file rather than to the screen. The END OF CAPTURE command reverts alphanumeric output back to the screen.

The CAPTURE command is useful for adding DATAPLOT output from FITS into reports, printing out debugging information, and generally saving DATAPLOT output for future use.

CAPTURE <file name>
where <file name> is the name of a file where alphanumeric output is written.

This is the standard form of the CAPTURE command.

If the file name does not contain a period, place a period (no spaces) at the end of the file name.

CAPTURE FLUSH

This command closes the current capture file, issues an ERASE command to the open graphics devices, and then prints the contents of the capture output on the graphics devices using the TEXT command (i.e., each line of the capture command is printed using a distinct TEXT command). The capture file is then re-opened (it will start at the beginning).

CAPTURE <file name>
where <file name> is the name of a file where alphanumeric output is written;
and    <HTML/LATEX/RTF> specifies that the output is to be written in either HTML, LaTex, or RTF format.

This syntax writes the output in either HTML, LaTex or RTF (Rich Text Format) format. Enter HELP CAPTURE HTML, HELP CAPTURE LATEX, or HELP CAPTURE RTF for more information on this.

RTF is a Microsoft format that can used to import Dataplot output into Microsoft Word. A number of other word processors have RTF format. We have successfully used Abiword and WordPad. We have had less success with several other word processors.

If the file name does not contain a period, place a period (no spaces) at the end of the file name. Typically, the file will have an ".htm" or ".html" (for HTML), ".tex" (for LaTex), or ".rtf" (for RTF) extension.

CAPTURE FITOUT.DAT
... DATAPLOT COMMANDS ....
END OF CAPTURE

DATAPLOT has the following restrictions on the file name:
1. The file name should be a valid file name on the local operating system.

2. It must contain a period "." in the file name itself or as a trailing character. DATAPLOT strips off trailing periods on those systems where it is appropriate to do so. On systems where trailing periods can be a valid file name (e.g., Unix), DATAPLOT opens the file with the trailing period.

3. On systems where file names are case sensitive (i.e., Unix), the case is preserved as entered on the CAPTURE command.

4. The file name cannot contain more than 80 characters.

5. If the file name contains a space, then use the SET FILE NAME QUOTE command and enclose the file name in quotes. For example,
   SET FILE NAME QUOTE ON
   CAPTURE "junk temp.out"
   

The capture command can be toggled on and off (END OF CAPTURE redirects alphanumeric output to the screen). However, a new file name should be used each time since invoking a new CAPTURE command overwrites any existing file (END OF CAPTURE automatically closes the file).

The CAPTURE command does not affect graphics output to the screen (unless a CAPTURE FLUSH command is issued).

It is often helpful to turn both the feedback and echo on when CAPTURE is used in order to identify the command that generates the output.

It is currently not possible to direct the output to both the screen and to a remote file. However, the LIST command can be used after the END OF CAPTURE to print the contents of captured file.

NOTE: The capability to do this is now available. To specify that the output will be sent to both the capture file and the screen, enter the command

CAPTURE SCREEN ON

To restore the default that the ouput is sent only to the capture file, enter

CAPTURE SCREEN OFF

Sometimes it may be useful to selectively send output to the CAPTURE file. You can do this with the following commands:
CAPTURE SUSPEND
CAPTURE RESUME


where SUSPEND specifies that output will be sent to the screen rather than the CAPTURE file (note that the CAPTURE file remains open) and RESUME will send the output to the currently open CAPTURE file. You can enter as many CAPTURE SUSPEND/CAPTURE RESUME sequences as you like between a CAPTURE/END OF CAPTURE session.

Note that OFF is a synonym for SUSPEND and ON is a synonym for RESUME.

The April, 2012 version of Dataplot added the command
CAPTURE SCRIPT <filename>

This command saves the subsequent commands to a file without executing them. The intended purpose of this is to allow scripts for external programs (e.g., Python, Perl, and so on) to be created within a Dataplot macro. You can subsequently use the SYSTEM command to execute the script.

This command was updated 2016/12 in the following two ways.

1. Changes were made so that the CAPTURE SCRIPT would work correctly when embedded within a LOOP/END OF LOOP sequence.

2. Added the command
   SET CAPTURE SCRIPT LOOP SUBSTITUTION <ON/OFF>

   If ON, then substitutions denoted by the "^" character will be performed before writing the line to the CAPTURE file. If OFF, no substitution will be performed. ON is the default. The OFF is typically only needed if the "^" character is used and has a specific meaning you want to preserve (e.g., "^" is the exponentiation symbol in many scripting languages).

The purpose of CAPTURE FLUSH command is to allow Dataplot text output to be written to the graphics output file. This can be useful when you are writing a macro and you want the analytic output (for example, the output from a fit) to be included with the graphics output. The following shows a sample of how this command is used:
device 1 x11
device 2 postscript
.
title automatic
skip 25
read gear.dat y x
.
mean plot y x
.
move 5 95
margin 5
capture junk.dat
tabulate mean y x
capture flush
end of capture
.
device 2 close
system lpr dppl1f.dat


The initial CAPTURE command directs text output to the file "junk.dat". When the CAPTURE FLUSH command is encountered, the capture file is closed, an ERASE command is generated for the graphics devices, the contents of the capture file are printed on the graphics devices using the TEXT command (i.e., each line of the file generates a distinct TEXT command), and then the capture file is re-opened (it will start at the beginning).

Since the lines are generated with the TEXT command, the appearance of the text can be controlled with the various TEXT attribute commands. Also, it is recommended that CRLF be set to ON (the default), a MOVE command be given to set the position for the first line of the text, and a MARGIN command be entered to set the beginning x-coordinate for the line.

Some output may be too long to display on one page. You can control the number of lines printed per page with the following command:

SET CAPTURE LINES <value1> ... <value5>

Up to 5 values may be entered. The first value is for the first page of output, the second value is for the second page of output, and so on. If more than 5 values are entered, then the page limits start over (i.e., page 6 uses the value for page 1, page 7 uses the value for page 2, and so on). The default is 25 lines for all pages.

If the MULTIPLOT switch is ON, the initial page erase is suppressed. The following example shows how this feature can be used:

device 1 x11
device 2 ps
device 1 font simplex
.
title automatic
skip 25
read gear.dat y x
.
multiplot 2 2
multiplot corner coordinates 0 0 100 100
multiplot scale factor 2
.
mean plot y x
sd plot y x
.
move 5 98
margin 5
plot
capture junk.dat
tabulate mean y x
capture flush
end of capture
move 5 98
plot
capture junk.dat
tabulate sd y x
capture flush
end of capture
.
end of multiplot


Note that the null PLOT command is used to move to the next plot area without actually generating a plot.

This example draws a mean and standard deviation plot on the first row and then suplements that with the numeric values generated using the TABULATE command on the second row.

The following two commands are also available.

SET CAPTURE NUMBER <ON/OFF>
SET CAPTURE BOX <ON/OFF>


If SET CAPTURE NUMBER ON is entered, the output lines are numbered. This is primarily a convenience function to help determine what values to enter for the SET CAPTURE LINES command in order to generate breaks at the appropriate spots.

If SET CAPTURE BOX ON is entered, a box will be drawn for each page of the output. Use the BOX 1 CORNER COORDINATES command, before the CAPTURE FLUSH, to specify the cooridinates of the box. Use the various BOX attribute commands to set the properties of the box.

The April, 2012 version of Dataplot added the following command
SET CAPTURE FLUSH ERASE <ON/OFF>

This controls whether the CAPTURE FLUSH command performs the initial screen erase. The ON setting specifies the default of performing this screen erase while the OFF setting suppresses this screen erase.

This command does not apply when the MULTIPLOT switch is active.

The December, 2015 version of Dataplot added the following commands
SET CAPTURE CUMULATIVE <ON/OFF>
SET CAPTURE SPLIT <ON/OFF>


These commands are primarily used when Dataplot is being controlled by an external program (e.g., Python).

When the SET CAPTURE CUMULATIVE switch is ON, Dataplot will close the capture file at the end of an Analysis command and then re-open the capture file in append mode. This allows the external file to maintain a "cumulative" capture file without the Dataplot session manually closing and re-opening the capture file.

If the SET CAPTURE SPLIT ON switch is given, then Dataplot will create a separate capture file each time an Analysis command is entered. Note that this is in addition to the specified capture file. For example, if the commands

SET CAPTURE SPLIT ON
CAPTURE CUMCAP.OUT


commands are given, then the file CUMCAP.OUT will contain all the alphanumeric output. In addition, the files

CUMCAP_1.OUT
CUMCAP_2.OUT
...


will also be generated. The split occurs whenever an Analysis command is entered. This command makes it easier for an external program to extract a desired subset of the output.

The default is for both of these switches to be OFF.

None

None

CAPTURE HTML	=	Write Dataplot output to an external file in HTML format.
CAPTURE LATEX	=	Write Dataplot output to an external file in LaTex format.
CAPTURE RTF	=	Write Dataplot output to an external file in RTF format.
END OF CAPTURE	=	Revert alphanumeric output back to the screen.
LIST	=	Lists the contents of a file.
CALL	=	Execute commands stored in a file.
CREATE	=	Echo entered commands to a file.
POSTSCRIPT CONVERT	=	Automatically generate JPEG, PDF, TIFF, PBM, PGM, PPM, or PNM from postscript output.

Saving Alphanumeric Output

Pre-1987
2002/07: CAPTURE FLUSH feature added
2002/08: CAPTURE HTML and CAPTURE LATEX feature added
2002/11: CAPTURE HTML support for PNG, JPEG, and SVG
2003/01: CAPTURE HTML support for Postscript and PDF
2006/01: CAPTURE SCREEN ON/OFF added
2006/01: CAPTURE SUSPEND/RESUME added
2012/04: CAPTURE SCRIPT added
2015/12: SET CAPTURE CUMULATIVE added
2015/12: SET CAPTURE SPLIT added
2016/12: CAPTURE SCRIPT corrected to work within a loop
2016/12: SET CAPTURE SCRIPT LOOP SUBSTITUTION added

 
    ECHO ON
    FEEDBACK ON
    CAPTURE FITOUT.DAT
    FIT Y X1 X2
    END OF CAPTURE
    

The FIT output will be written to the file FITOUT.DAT.