Gemini Twin-Arrays Infrared Camera User's Manual: Writing Scripts

Writing Scripts

The Gemini user interface software provides a script or macro capability that allows the user to put together any number of commands to be executed sequentially as a group, in much the same way as a UNIX shell-script or a VMS command procedure. This feature is especially useful for carrying out a repetitive observing/operation sequence, such as making a mosaic and doing repetitive engineering tests. The script tool is provided in both the menu interface mode and the command line mode.

List of Script Commands
Create a Script File
Execute a Script File
Example Script File

Script writing tool Currently does basic dithering scripts.

List of Script Commands

Almost all of the command-line commands are allowed in a script file file. However, it is recommended not to use commands that must run interactively in a script because of possible confusion during the script execution. Therefor, a list of script commands is created and given below which are proven to be rather useful in real observations. This script command list can be accessed on-line from the Gemini software menu mode under the Help item in the root menu.

System Commands

BEEP 0-10000 generate beeps for 0-10000 milliseconds

CONFIRM str print confirmation information str

DISKSPACE check free disk space

DO 1-1000 iteration operator for script file

ENDDO iteration operator for script file

ECHO str echo string str

PAUSE num str pause system num sec (0=indefinite) and print str

Observing Setup Commands

COADDA 1-9999 set number of co-adds for channel A

COADDB 1-9999 set number of co-adds for channel B

FILENUMA 1-9999 change image file running number for channel A

FILENUMB 1-9999 change image file running number for channel B

FILTERA filtername change filter for channel A

FILTERB filtername change filter for channel B

ITIMEA 0.000-999 set itime (seconds) for channel A

ITIMEB 0.000-999 set itime (seconds) for channel B

MULTIA 2-9999 set number of samples for multi-sampling mode, channel A

MULTIB 2-9999 set number of samples for multi-sampling mode, channel B

OBJECT str set current object name

SAMPMODEA 1-6 set sampling mode for channel A (1=single, 2=CDS, etc)

SAMPMODEB 1-6 set sampling mode for channel B (1=single, 2=CDS, etc)

OBSMODE Imaging|Polar|SpPolar change observing mode

STPAP Open|Spot|Sinslit|Dblslit change aperture wheel position

SPTAUX Open|Calcite|Polariz change auxiliary wheel position

STPDIC K@LW|K@SW change dichroic slide position

STPWPS Out|In change wave plate (IO) position

STPWPR 0|22.5|45|67.5 change wave plate (rotation) position

STP_INIT Ap|Aux|SWF|LWF|Dic|Pol|WPS|WPR initialize stepper motor

Observing Commands

Go A|B|2 start integration for channel A, B, or both

MOVIE A|B|2 start movie mode for channel A, B, or both

TEST A|B|2 take test frame(s) for channel A, B, or both

TV Display Commands

TV A|B|2|filename display channel A/B frame or FITS file filename

TV_DISP On|Off turn on/off TV auto-display

TV_GAINA 0.001-1000 set TV display gain for channel A

TV_GAINB 0.001-1000 set TV display gain for channel B

TV_OFFSETA +/-32767 set TV display offset for channel A

TV_OFFSETB +/-32767 set TV display offset for channel B

Math & File I/O Commands

IMDIFF A|B|2 calculate image difference and display

IMSTATS A|B|file calculate statistics for channel A or B frame or file

SAVE A|B|2 save test frame from channel A or B or both

WDISK A|B write channel A or B frame to disk in FITS

Telescope Control Commands

TELMOVE x y move telescope by x arcsec in RA and y arcsec in DEC

TELPOSN read current telescope position (RA, DEC, HA)

AUTRETSET p x y set autoguider reticle positions p=0 for guide reticle, p=1 for background reticle, x and y are the pixel positions of the reticle

AUTRETGET read current autoguider guide and background reticle positions

For more information on using autretset in scripts see http://www.ucolick.org/~egates/gemini/scripts.html

A few of the commands in the list are specifically designed for the script tool, such as BEEP, CONFIRM, ECHO, and PAUSE and the iteration operators DO and ENDDO.

Create a Script File

A script file is created or edited using the DOS screen editor. The DOS text editor can be invoked from inside the Gemini user interface program. In the menu mode, select Edit Script under the root menu item Option. In the command line mode, escape to DOS and run the editor directly. Script files are placed in the directory C:\GEMINI\SCRIPT and have the file name extension .SCR. When editing a script file in the menu mode, simply give the name of the script and the Gemini program will add the directory path and extension to it.

Each command must have one line in a script file, but it can start from any position in the line. Blank lines are allowed and a comment line starts with #. The following is an example.

# A test script file

# set parameters
ITIMEA 10
COADDA 3

# integrate
DO 3
GO A
ENDDO

Like in the command line mode, if a command parameter is not supplied in a script file, the program will prompt for the parameter during the execution.

The script tool provides a syntax check feature which checks the validity of a command and the validity and value range of its parameter. For example, a script with the following two lines

ITIME 10
COADDA 0

will yield the following error messages when running a syntax check:

CL Error: invalid command - line 1 > ITIME 10
CL Error: parameter value out of range - line 2 > COADDA 0
Script syntax check: 2 error(s) found

No syntax error is generated if a command parameter is not supplied in a script. The program will not make a syntax check when the parameter is entered during the execution.

To run the syntax check in the menu mode, select Check Script in the Option item. In the command line, type CHKSCRIPT {filename}.

Execute a Script File

The Gemini program always makes a syntax check first when running a script. If an error is found, the script execution is aborted before any command is executed. To run a script, select Run Script in the Option item (hot key CF3) in the menu mode or type SCRIPT {filename} in the command line mode.

During the execution, the command currently being executed is displayed in both interface modes. The next command will also be displayed in the menu mode. For example, the script execution status

3:7 > GO A 4:7 > FILTERA H

shows that the script file has a total of 7 command lines and the command being executed is the 3rd command line GO A; the next command to be executed is FILTERA H.

A script execution can be aborted by pressing the function key CTRL F2. Note: the software will say press CTRL F3 to abort the script - this is incorrect. CTRL F2 is the abort command. The execution stops only after the current command execution is finished. Therefore, to abort and active command in a script such as an integration immediately, press CTRL F2 first and then use the normal abort command.

IMPORTANT NOTES: If you are in the TV mode when a command execution is finished, you must come back to the text mode in order for the next command in the script to get started. Also, do not switch between the menu mode and the command line mode or escape to DOS during a script execution or the execution status display will get messed up.

Example Script File

# script to make a 1x9 mosaic
ECHO script to make a 1x9 mosaic

# set observing mode
OBSMODE imaging

# turn on tv display
TV_DISP on

# set observing parameters
OBJECT
SAMPMODEA 2
SAMPMODEB 2
FILTERA j
FILTERB kp
ITIMEA 30
ITIMEB 6
COADDA 2
COADDB 10

# confirm setup; Y to continue and N to quit
CONFIRM Is the setup correct?

# start 1st integration
GO 2

# loop 8 times
DO 8

# pause to turn off guider
PAUSE 0 Turn off guider

# offset 160 arcsec north
TELMOVE 0 160

# pause to find guide star
PAUSE 0 Find guide star

# integrate
GO 2

ENDDO

# beep 3 sec to wake up
BEEP 3000

Last modified: Thu Feb 15 15:49:05 PST 2007 by Elinor Gates

User's Guide to the Gemini Twin-Arrays Infrared Camera

Table of Contents

Writing Scripts

System Commands
BEEP 0-10000	generate beeps for 0-10000 milliseconds
CONFIRM str	print confirmation information str
DISKSPACE	check free disk space
DO 1-1000	iteration operator for script file
ENDDO	iteration operator for script file
ECHO str	echo string str
PAUSE num str	pause system num sec (0=indefinite) and print str
Observing Setup Commands
COADDA 1-9999	set number of co-adds for channel A
COADDB 1-9999	set number of co-adds for channel B
FILENUMA 1-9999	change image file running number for channel A
FILENUMB 1-9999	change image file running number for channel B
FILTERA filtername	change filter for channel A
FILTERB filtername	change filter for channel B
ITIMEA 0.000-999	set itime (seconds) for channel A
ITIMEB 0.000-999	set itime (seconds) for channel B
MULTIA 2-9999	set number of samples for multi-sampling mode, channel A
MULTIB 2-9999	set number of samples for multi-sampling mode, channel B
OBJECT str	set current object name
SAMPMODEA 1-6	set sampling mode for channel A (1=single, 2=CDS, etc)
SAMPMODEB 1-6	set sampling mode for channel B (1=single, 2=CDS, etc)
OBSMODE Imaging\|Polar\|SpPolar	change observing mode
STPAP Open\|Spot\|Sinslit\|Dblslit	change aperture wheel position
SPTAUX Open\|Calcite\|Polariz	change auxiliary wheel position
STPDIC K@LW\|K@SW	change dichroic slide position
STPWPS Out\|In	change wave plate (IO) position
STPWPR 0\|22.5\|45\|67.5	change wave plate (rotation) position
STP_INIT Ap\|Aux\|SWF\|LWF\|Dic\|Pol\|WPS\|WPR	initialize stepper motor
Observing Commands
Go A\|B\|2	start integration for channel A, B, or both
MOVIE A\|B\|2	start movie mode for channel A, B, or both
TEST A\|B\|2	take test frame(s) for channel A, B, or both
TV Display Commands
TV A\|B\|2\|filename	display channel A/B frame or FITS file filename
TV_DISP On\|Off	turn on/off TV auto-display
TV_GAINA 0.001-1000	set TV display gain for channel A
TV_GAINB 0.001-1000	set TV display gain for channel B
TV_OFFSETA +/-32767	set TV display offset for channel A
TV_OFFSETB +/-32767	set TV display offset for channel B
Math & File I/O Commands
IMDIFF A\|B\|2	calculate image difference and display
IMSTATS A\|B\|file	calculate statistics for channel A or B frame or file
SAVE A\|B\|2	save test frame from channel A or B or both
WDISK A\|B	write channel A or B frame to disk in FITS
Telescope Control Commands
TELMOVE x y	move telescope by x arcsec in RA and y arcsec in DEC
TELPOSN	read current telescope position (RA, DEC, HA)
AUTRETSET p x y	set autoguider reticle positions p=0 for guide reticle, p=1 for background reticle, x and y are the pixel positions of the reticle
AUTRETGET	read current autoguider guide and background reticle positions