
			   CATCHER_V1
                (1D/2D Data Catcher For Scan Record)

			    OVERVIEW	

This program automatically catches and displays 1D/2D scan data 
detected by monitoring the EPICS 3.12.2 scan record.  The monitored 
scan can be invoked within the data catcher or invoked by any 
outside CA client.
 
Each scan record can contain up to 4 positioners and 15 detectors. At 
the end of each scan the defined positioners and detectors array are
automatically saved. In addition to scan data, a user can use the
environment file to save additional operating parameters.  At the 
normal completion of data catcher the new configuration file will
be automatically saved. 

This program operates in two mode: acquisition and view data mode. 
The default mode is always the data acquisition (i.e. data catching)  
mode. A user can select the view data mode to examine the scan data 
previously captured. At the end of view data mode it automatically 
returns to the data acquisition mode.

There are two view data modes: 1D and 2D. The view 2D mode is covered
by the VIEW2D program, it will not be discussed here.

The acquistion mode supercedes the view data mode. During the 1D viewing 
mode if the data catcher detects any scan invoked by the outside CA 
clients, it will close the 1D viewing mode and yields to the data 
acquisition mode right away.

The data catcher Release 1.5 now provides two additional option keywords: 
NOSAVE and VIEWONLY. If the /NOSAVE option is specified, every feature of the
data catcher is available except the new scan data captured will not be 
saved. If the /VIEWONLY option is specified, only the features of viewing
the scan data from a file are accessable. 

Be aware that the text fields entered will not be in effect until the user 
entered the carriage return.

			    FILE USED 

config.file		Before quiting the data catcher a configuration 
			file will be automatically saved if the monitored
                        scan record is properly connected. If it is not 
                        given on command line, 'catch1d.config' is used.  

data.file 		This file is used to record the 1D scan data.
			Complete 1D scan data is automatically saved at 
			the end of each scan. If not given on command 
			line, 'catch1d.trashcan' is used.

env.file		Optional. This file should contain a complete list 
                        of environment PV variables to be saved with the
			1D scan. If not given on command line, 
			'catch1d.env' is used.

data.file.image  	This file is used to save 2D image data for 2D
                        scan.  Each detector defined for the scan record
			one possesses its own 2D image. 
			Complete 2D scan data is automatically saved at 
			the end of 2D scan. The name convention for the 
                        image file is the data file name suffixed with the
			'.image'. If the data file name is not given on 
                        the command line, the default 'catch1d.trashcan.
			image' is assumed.

Report files    	Various levels of report files can be generated
			by the data catcher. The default name convention
                        is the data file name suffixed with the range of
                        scan numbers.  If the data file name is not given on 
                        the command line, the default root name of 
			'catch1d.trashcan.xxxx_xxxx' is assumed.

catch1d.ps              Postscript 1D plot file. 

view2d.ps               Postscript 2D image/surface plot file. 



			   USER INTERFACE

The user interface is very simple and is complete mouse driven. 
Defaults are automatically set up by the data catcher. The only 
thing needing to be set up at the first time to bring up the data 
catcher is the scan record PV names. The function of each widget
is briefly given below.

Two types of mouse pointer are used by the data catcher: a normal
pointer and an hourglass pointer. Normally the arraow pointer or 
cursor point in drawing area is shown. When the data catcher is 
busy an hourglass pointer is shown.

The arrow pointer is changed to hourglass pointer when the data 
catcher is busy with time consumed functions. The hourglass pointer
will return back to the arrow pointer when the data catcher is
idling and waiting for any X event. 

The main window of the data catcher can not be closed by the window
manager. This will avoid the user accidentally close the data catch
which may disrupt the file saving. This will insure the integrity of 
data file and the configuration file.


			     FILE MENU

The File menu let the user to change the directory and name of the
file to be used by the data catcher. While the scan is going on
this menu will not be accessable by the user, only when the data catcher 
is in an idling stage a user can access any entry in this menu.

The File pulldown menu consists of six selection items: 'New ...', 
'Open ...', 'Close', 'Save As ...', 'Copy ...', and 'Quit'.

New ...			Pops up a file selection box. A non-existing
			file name is expected. New scan data acquired 
			will be saved in this file from now on.

Open ...		Pops up a file selection box. Existing file can
			be selected or new file can be entered. A message
			dialog will pops up showing the current file path, 
			file name, and scan # in the selected file. New 
			acquired data will be automatically appended to
			this file.  It defaults to 'catch1d.trashcan'.

Close			Close the curretly opened data file for saving 
			the acquired data, and the user should select
			another data file if more scanning to be done.
			Otherwise the default 'catch1d.trashcan' will be 
			assumed. Normally a user never need to worry 
			about closing the file.

Save As ...		Pops up a file selection box. A non-existing
			file neame is expected. It saves the currently
			acquired scan data to a brand new file.

Copy ...		Pops up a dialog to copy an existing data
			file to a new file.

Quit			Saves the new configuration file and exits 
			the IDL data catcher program.



			       SETUP MENU 

The Setup pulldown menu consists of six selection items: 'Acqusition', 
'AutoSave', 'Realtime', 'TextWin', 'Scan ...', and 'Color ...'

This menu shows the initial set up of data catcher while it is invoked.
At normal operation all the entry items are availale. At the /NOSAVE 
mode, the item  'AutoSave' is in-active. At the /VIEWONLY operation only
the change color table item 'Color ...' is available.

 
Acquisition		Off/On. Turns data acguistion off or on.
			It defaults to On.

AutoSave		Off/On. Turns data save option off or on.
			It defaults to On.

Realtime		Off/On. Turns realtime dispaying option off or on.
			It defaults to On.

TextWin			Off/On. Turns realtime text terminal window off or on.
			It defaults to Off.

Scan ...		Pops up dialog windows for setting up for 1D or
			2D scan. The scan record name is required for data
			acquisition.  The 1D scan PV name is required for 
			1D scaning.  Both 1D and 2D scan PV names are 
			required for 2D scannig. 

Color ...               Loads the IDL color table program. The data catcher
			currently uses 32 colors. A user can use the private
			ezcaidl_startup.pro to override this default number
			of colors used by the IDL.




		             PLOT OPTIONS MENU

The Plot Options pulldown menu consists of seven selection items: 'Plot vs',
'Plot Style', 'Y Scale', 'Grid', 'Err Bars', 'Versus P#', 'Color Curve', and 
'Plot ...'

Colors 			Colors/Black&White. Turns the option of color curve 
			plot on or off. It defaults to Colors.

Lines                   Solid or various line styles. It default to colored
			solid lines. 

Symbols 		Lines/Symbos/Both. Plots data as line, symbol, or line
			plus symbol. It defaults to line plot.

Grid			Off/On. Turns grid lines off or on. It defaults to
			grid lines off.

Err Bars		Off/On. Turns error bar (10%) option off or on. It
			defaults to off.

Y Scale			Linear/Linear (Y>0)/Log. Y axis uses linear or log 
			scale. It defaults to linear scale.

Ranges ...              Pops up a plot specification dialog for setting the
			user preferred x- or y- plot ranges and replot.

Labels ...		Pops up a plot specification dialog for setting the
			plot tilte, xlabel, ylabel, comment.



			       HELP MENU

The Help pulldown menu consists of five selection items: 'Version ...',
'Release Note ...', 'Help ...', 'Catcher Html ...', and 'ezcaIDL Html ...'.

Version ...		Pops up the message window to show the version 
                        information.

Release Note ...        Pops up the release note window.

Help ...		Pops up this help text window.

Catcher Html ...        Pops up the netscape window to show the packaged
			data catcher reference manual 

ezcaIDL Html ...        Pops up the netscape window to show the 
			ezcaIDL reference manual 



			     VIEWDATA MENU

The ViewData pulldown menu consists of two selection items: '1D ...',
and '2D ...'.

1D ...			Pops up the 1D data displaying dialog. It allows
			the user to browse through previously captured 1D 
			scan data.

2D ...			Runs the IDL  VIEW2D program.  It allows the user
			to browse through previously captured 2D scan data.



			     STATUS FIELD 

This text field gives the current status of the SCAN Record. It reflects 
the acquired data points for both 1D and 2D scan.  It will provide the 
status for PV setup.  It will also provide the status of scanning while 
the scan is going on,  e. g. 

	For 1D PV Setup:
	>> PV Valid <<

	For 2D PV Setup:
	>> PV2 Valid <<

	For 1D scanning: 
	SCANNING: 12 of 100 Pts 

	For 2D scanning: 
	SCANNING: 12 of 100 Pts At 10'th Scan 
	
	For End of Scan: 
	IDLE : Acquired  100 Pts 



			     PRINT MENU 

The Print pulldown menu consists of two selection items: 'Plot',
and 'Report ...'.

Plot			Creates the 'catch1d.ps' file and generates a hard
			copy of 1D plot at the user default printer.

Report ...		Pops up a report generation dialog. Three types
			of reports can be generated: with complete header,
			abbreviated header, and data only. It provides
			flexible creating, viewing, and printing features. 
			Before viewing or printing the report it must be 
			generated first.


			       ZOOM MENU

The Zoom pulldown menu consists of five selection items: 'Zoom To Box',
'Zoom In', 'Zoom Out', 'Auto Scale', and 'User Scale'.

Zoom To Box		Selects bounding box option. 
			Steps:
			   Move mouse into the drawing area
			   LMB to position the bounding box
			   MMB to adjust the bounding box size
			   RMB to zoom to the bounding box 

Zoom In 		Selects zoom in mode 
			(must be terminated by the RMB)
			   LMB to zoom in to 1/2 scale
			   MMB to refresh to original size 
			   RMB to stop the zoom in mode 

Zoom Out		Selects zoom out mode
			(must be terminated by the RMB)
			   LMB to zoom out to 2 times
			   MMB to refresh to original size 
			   RMB to stop the zoom out mode 

Auto Scale		Replots with automatic scaling plus 5% margin.

User Scale ...		Replots with user specified xmin, xmax, ymin and
			ymax range. It pops up a set user scale dialog.



			   STATISTIC MENU

The Statistic pulldown menu consists of three selection items: 'No fitting ...',
'Fit-parameter window', and 'Fit parameters on plot'

None			No statistic values shown on the plot

Peak/Centroid/FWHM on plot
			This button displays the Peak, Centroid, and FWHM on the			plot for the selected detector.

Peak/Centroid/FWHM ...  This button turns on the statistic calculation and pops
			up a scroll window to display all the local Peaks, 
			Centroid, and FWHM for each selected detector. 
			The statistic calculation can be turned off by close 
			the statistic scroll window.

FWHM on Y ->One...      This button pops up plot of FWHM on Y for the first
			selected detector and option of listing detail fwhm.rpt
			(no window displayed for constant Y value case)

FWHM on Y ->All...      This button pops up plot windows of FWHM on Y for all
			detectors (except for those detectors with a constant
			Y value case)

FWHM on DY/DX ->One...  This button pops up plot of FWHM on DY/DX for the first
			selected detector and option of listing detail fwhm.rpt
			(no window displayed for constant Y value case)

FWHM on DY/DX ->All...  This button pops up plot windows of FWHM on DY/DX for 
			all detectors (except for those detectors with a 
			constant Y value case)

Averate/Deviation ...   This button pops up the standard deviation calculation
                        for all selected detectors   



			    DRAWING AREA


The drawing area is used for realtime and 1D plot. In realtime 
only live data, title, x label for the selected detectors are 
plotted. Post data scan the detailed plot title, labels, legends, 
timestamp, user ID, etc. are drawn in the drawing area.

The top left corner contains the data file name. The top right corner 
contains the scan #.  The bottom left corner contains the time stamp 
when this scan started and a comment line. The bottom right corner 
contains the user name.
  
The plot title, xlabel, ylabel and comment can be set up by the user
through using the 'Plot Options->Plot ...' option.  If not specified
the default scan record database name, description and engineering 
units will be used for the plot.  A user always can use the Plot ... 
dialog to modify the plot specification at the view data mode.

The plot range can be automatically scaled or user specified. The default
is auto-scaled, with a 5% margin. A user can use the Zoom->User Scale ...
or the Plot Options->Plot ...  menus to modify the plot range xmin, xmax, 
ymin, and ymax in the user-scaled plot.  



		         DRAWING AREA XY-COORD

Click the Left Mouse Button (LMB) on the drawing area will draw a 
cross-hair and pops up a XY-COORD dialog. It contains a positioner
number label, two text fields, a 'GoTo ...' button, and a 'Close' button. 
The X and Y field shows the intersection coordinates of the cross
hair.  Press the 'GoTo ...' button pops up the set positioner locations
dialog.  Press the 'Close' button terminates the query of cursor
loction.



		           GOTO ... DIALOG

The set positioner dialog displays a list of all the positioner locations 
corresponding to the drawing area cross-hair cursor, and a question whether 
to set the new motor position accordingly, and a close button.  
If the user press the carriage return for 'Y', then a channel access array 
put for all the specified positioner(s) will be issued and the hardware 
physically moves the positioner(s) to the new location(s). The Close button
closes the dialog.
 


			    X AXIS SELECTION

The X axis can be index number or the array of the positioner readback values.
If selected positioner is not defined, then the index number will be used in
the X axis plot.  It defaults to P1 axis.


			    Y AXIS SELECTION 

The radio buttons of Y plotting consists of 15 detectors and 4 positioners.
The selection button indicates whether the detector will be plotted or not.  
If it is pressed in the corresponding detector data will be plotted. The
default selected buttons are D1 and D2.


		  	    IMAGES SELECTION 

For 2D scan in addition of 1D realtime scan plot, an image strip showing 
live 2D images of all detectors.  Each detector's 2D image is updated at 
the end of each 1D scan based on it's own color scheme.

Two sizes of image selection  Small/Large. It defaults to small.


			
			    SCAN ... DIALOG

The scan setup dialog allows the user to setup which scan record will
be monitored by the data catcher. It consists a row of widgets for 
1D scan control, a row of widgets for 2D scan control, a row of widgets
for alternate 2D handshake, a 'Ok' button, and a 'Close' button.

The 'Ok' button accepts all the text fields and properly setup the
data catcher for monitoring the future scan. The 'Close' button closes this 
dialog and let outside CA clients have sole control of scanning.


			 1D Scan Control

The text field specifies the inner loop  PV name of a SCAN record to be 
scanned. The input should end with a carriage return.

The control of scanning consists of two buttons: 'Start' and 'Stop'.
The 'Start' button initiates the 1D scan and displays the real-time plot 
of captured data at the drawing area. The 'Stop' button aborts
the scan before the normal completion of 1D scan.


			 2D Scan Control

The text field specifies the outer loop PV name of a SCAN record which
controls the position of the outer loop.  The input should end with a 
carriage return.

The control of scanning consists of two buttons: 'Start' and 'Stop'.
The 'Start' button initiates the 2D scan and displays the real-time plot 
of captured data at the drawing area. The 'Stop' button aborts
the 2D scan before the normal completion of 2D scan.

 
			 2D Handshake Control

The text field specifies the PV name for 2D scan handshake, the second
text field specifies the value to be used for handshake. The input 
should end with a carriage return. If the handshake PV name is specified
a channel access put will be performed at the end of each inner loop scan.




		           LABELS ... DIALOG

Labels setup dialog consists of sets of push buttons and input text fields
which will be used by the data catcher in modifying the 1D plot. 

The plot title, x & y labels, comment text fields can be 
modified to override the default values.  The text field entered will be 
in effect by carriage return or until either the 
'Apply' or 'Done' is pressed. The 'Done' button will also close the dialog. 
If the 'Cancel' button is pressed, it terminates the modification and close 
the dialog.


			
			  RANGES ... DIALOG

The user scale dialog allows the user to dynamically specify the X and Y plot 
ranges.  It consists of xmin, xmax, ymin, ymax fields and three push buttons.
Slider bars are provided for the easy task of entering the plot ranges. 
Any value field ended with a carriage return initiates the replot right away
with the entered value.  The 'User Scale' button takes the X and Y ranges and
replot the data.  Data falls outside the plot ranges will not be shown in the
user scale plot.  The 'Auto Scale' button automatically re-plots the whole data
range based on the data array. 



			   VIEW 1D ... DIALOG

View 1D dialog allows the user freely to browse through the 1D scan data file.

View 1D dialog consists of: a label describes the current file opened 
for viewing, a label gives the ranges of scan data recorded in the
file, a text field shows the current record # from the opened file,
a slider bar for selecting the desired scan record, and two sets of 
push buttons. They can be divided as scan selection control and output control.

Selection Control:

The text field entry allows you to enter a scan #.

The slider allows you to go to any valid scan record.

Press 'First' to view the scan # 1.

Press 'Next' to view the next scan #.

Press 'Prev' to view the previous scan #.

Press 'Last ' to view the last scan #.

Press 'Done' to close the view mode.

Output Control:

The 'Print Plot', 'Modify Plot', 'ASCII View', and 'ASCII Print'  buttons
will be active only if the selection control has been activated and a set 
of recorded scan data has been loaded into data catcher.

Press 'Print Plot' generates the postscript plot file 'catch1d.ps' and sends
it to the user default printer.

Press 'Modify Plot' allows you to modify the plot specification and replot 
according to your changes.

Press 'ASCII View' saves the ASCII scan data in 'catch1d.trashcan.tmp' 
file and pops up a scroll text window to display the corresponding data
for the selected scan #.  

Press 'ASCII Print' prints the ASCII scan data from the 'catch1d.trashcan.tmp'.
It is accessible only if the 'ASCII View' has been pressed for the selected
scan #.


			  VIEW 2D ... DIALOG

This is a standing alone 2D image browser program. It allows the user 
flexiblely to browse the 2D scan image data saved by the data catcher. 
For a given image it provides TV, SURFACE, CONTOUR, SHOW3, and XSURFACE 
plot.  For more information please refer to VIEW2D on line help.
 

			     1D OVERLAY ... DIALOG

This is a standing alone 1D overlay plot program. It allows the user
to view few 1D scans for a selected detector.  Limited features of
1D overlay plot are available.



			   FILE DESCRIPTIONS

			        catcher
			        -------

A UNIX script file 'catcher' automatically invokes the IDL data catcher for
user. It can be run from any directory as long as the directory name
 '/usr/local/epics/extensions/bin/HOST_ARCH' is included in the user search 
path.  At APS the HOST_ARCH is either sun4 or solaris.

catcher  

	This will start the data catcher with complete default features. 
	It includes realtime plot, data acquisition, saving acquired data,  
	realtime text window, viewing old data option, listening to new data,
	etc.

catcher -n 

	This will start the data catcher as an old and live data displayer 
	but it will not save the acquired data. 
	It is assumed that there is another version of data catcher is 
	running and the acquired data is saved by that run. 

catcher -v

	This will start the data catcher as a data browser/viewer, no data
	acquistion will be done. It will only access the viewing features 
        of the data catcher, no data acquistion is performed by this option.	



			    catch1d.config
			    --------------

The configuration file 'catch1d.config' will be saved or updated  at the 
normal completion of the data catcher, i.e,  from the File->Quit menu.
Only if the scan record is properly connected at the termination time
then the configuration file will be updated.  The configuration is saved
at the directory where data catcher was initally invoked.

The contents of 'catch1d.config' include scan record name, home
directory where data catcher was invoked, the data directory  and
the data file name where the last scan data was saved, plot labels, 
plot options, and important scan setup fields of the scan record.  
Be aware that the 'catch1d.config' only remembers the last status of 
the data catcher when you exit the program. 



			     catch1d.env
			     -----------

The 'catch1d.env' provides the flexible feature of saving additional
IOC setting values with the scan data. For each PV name defined in
the 'catch1d.env' file the set value and description can be saved 
with the scan data.

Each line in 'catch1d.env' consists of a single valid PV name plus the 
field name followed with the field description. The PV name and the 
description is separated at least by one blank space. The PV name plus 
the '.field' name can not exceed 28 characters, and the filed descrpition 
can not exceed 40 characters.  No waveform record is allowed in 
'catch1d.env'. Currently, the number of lines allowed in 'catch1d.env' 
is 1000.

If the description is not specified in 'catch1d.env' for a given PV name, 
then the description from the record .DESC will be used in save data.
Any line begins with # in the first column will be treated as a comment
line. Any PV name is prefixed by '*', it will always be included in the
saved environment data.

A complete list of enviroment values will be saved for each reference 
case.  For subsequent scans only those values changed from the reference 
case will be saved or the PV name is prefixed by '*' will be saved.

The reference case is defined as the data catcher is ready for 
acquiring new scan data, i.e. when the set up new scan PV names
is called.  PV name setup is called for the case of initial startup of 
the data catcher, or the close of the viewing mode.


			catch1d_user.pro
			----------------

Data catcher provided two dummy routines before_scan, and after_scan.
The before_scan routine is called at the end of scan PV name setup. 
The after_scan routine is called at the end of each 1D scan.

A user can use these two reserved routines to access his/her own
before and after scan hooks.

The data catcher automatically loads in the 'catch1d_user.pro'. This is
the place where a user can provide his/her own version of before_scan and
after_scan routines in this file.  If provided, then the user version 
of before_scan and after_scan will be used by the data catcher.



			catch1d.trashcan
			----------------

The 1D scan data detected by the data catcher is automatically saved in this
file. A user can override this default name by using the File->Open menu 
or File->New menu to enter meaningful file name.


			catch1d.trashcan.image
			----------------------

This is the default 2D image file name used by the data catcher.
In addition to 1D scan data the 2D image data is also saved for the 2D scan.
The 2D image file name is composed of the 1D scan data file name suffixed 
with the '.image'.


			catch1d.trashcan.index
			----------------------

This is the scan data index file which is automatically generated by the
release R1.5 data catcher. This index file eliminates the wait time in read 
and greatly improves the scan data access time of the data catcher. The index
file name is composed of the 1D scan data file name suffixed with the '.index'.



