All script variables represent text strings, however they can also be used to store numbers (as text strings). Before each line of a script is executed, its variables are converted to their values before the line is executed. Variables are specified by preceding the variable name with the "$" character. As such if the variable "text" contains the words "this is a message" then the following two lines produce the same result.
echo $text
echo "this is a message"
If a variable name is preceded by two "$" characters, the variable name itself becomes a variable which is in turn evaluated. For example, if the variable "text" contains "variable1" then the expression "$$text" would be converted to the value of "variable1".
The types of variables available are as follows:
Variable names are not case-sensitive, but it is good convention to use all capital letters so as to make them easily identifiable.
Syntax: set variable_name value
Syntax: variable_name= value
Syntax: set variable_name variable1 plus variable2
Syntax: set variable_name value1 +-/* value2
Description: This command either creates and sets the value of a variable or it changes the value of an existing variable. It can also be used to perform basic math or concatenate two text strings. Note that an easier way to set the value of a variable is to reference it by name as the first parameter of a line followed by an "=" character. For example, "set variable_name" just becomes "variable_name=". Below are some examples:
|
set imagedirectory "c:\images" |
sets the value of the variable "imagedirectory" to "c:\images" |
|
Imagedirectory= "c:\images" |
same as above |
|
year= 2006 |
sets the value of the variable "year" to the constant 2004 |
|
count= $count + 1 |
sets the value of the variable "count" to one larger than its current value |
|
set message "Date: " plus today |
sets the value of the variable "message" to "Date: today" |
|
count= $count * $increment |
sets the value of the variable "count" to the the value of "count" multiplied by the value of "increment" |
userset
Syntax: userset variable_name
Description: This command displays a dialog box that prompts the user to specify a value for the variable "variable_name".
eraseuservariables
Syntax: eraseuservariables
Description: This command erases all user-specified varaibles.
ARAP has many pre-defined variables as listed below. Several of these variables can only be accessed and not changed by a script.
|
Variable Name |
Read/Write |
Description |
|
TELESCOPECONNECTED |
No |
True if the connection to the telescope is enabled |
|
CCDCONNECTED |
No |
True if the connection to the ccd camera is enabled |
|
DOMECONNECTED |
No |
True if the connection to the dome is enabled |
|
X10CONNECTED |
No |
True if the connection to the X10 interface is enabled |
|
CLOUDSENSORCONNECTED |
No |
True if the connection to the cloud sensor is enabled |
|
TELESCOPEERROR |
Yes |
True if the last telescope-related command failed |
|
CCDERROR |
Yes |
True if the last CCD-related command failed |
|
FOCUSERROR |
Yes |
True if the last Focus-related command failed |
|
CALIBRATIONERROR |
Yes |
True if the last CCD calibration command failed |
|
PINPOINTERROR |
Yes |
True if the last PinPoint plate-solve command failed |
|
DOMEERROR |
Yes |
True if the last dome-related command failed |
|
X10ERROR |
Yes |
True if the last X10 command failed. |
|
FINDERROR |
Yes |
True if the last object database search command (such as 'goto' or 'find') failed |
|
ZIPERROR |
Yes |
True if the last 'zip' command failed |
|
FILEERROR |
Yes |
True if the last file input/output or directory-related command failed |
|
FTPERROR |
Yes |
True if the last 'ftp' command failed |
|
SCPERROR |
Yes |
True if the last 'scp' command failed |
|
CLOUDSENSORERROR |
Yes |
True if the last cloud sensor related command failed |
|
FATALERROR |
Yes |
Set to true when a fatal error occurs. A fatal error also be initiated by setting this variable to true |
|
USEFATALERRORSCRIPT |
Yes |
If true, this causes the specified script to run following the occurance of a fatal error |
|
FATALERRORSCRIPT |
Yes |
The script that optionally runs in the event a fatal error occurs |
|
IMAGEDIRECTORY |
Yes |
The drive and directory where image files are stored. |
|
IMAGECOUNTER |
Yes |
The current image counter that is optionally appended to image filenames |
|
IMAGECOUNTERENABLED |
Yes |
The current image counter is appended to image filenames when set to true |
|
FILTERINDEX |
Yes |
The index of the optical filter. The first filter has an index value of 0 |
|
FLIPX |
Yes |
New 'light' images are flipped from left to right when set to true |
|
FLIPY |
Yes |
New 'light' images are flipped top to bottom when set to true |
|
CALIBRATIONENABLED |
Yes |
New 'light' images are automatically calibrated when set to true |
|
KERNELFILTERINDEX |
Yes |
The MaxIm DL kernel filter type (see the MaxIm DL documentation for details) |
|
KERNELFILTERVALUE |
Yes |
The MaxIm DL kernal filter value (see the MaxIm DL documentation for details) |
|
KERNELFILTERENABLED |
Yes |
New 'light' images are automatically kernel filtered when set to true |
|
RA |
Yes |
The right ascension in hours. Acceptable formats when setting this value are a floating point number, hours and minutes separated by a colon or in hours, minutes and seconds separated by a colon. Example valid values are: 01:10, 01:10.1, 0:10.343, 01:15:30, 1:15:30.55. |
|
DEC |
Yes |
The declination in degrees. Acceptable formats when setting this value are a floating point number, degrees and minutes separated by a colon or in degrees, minutes and seconds separated by a colon. Example valid values are: -01:10, +01:10.1, 0:10.343, -01:15:30, 1:15:30.1. |
|
SIDEOFPIER |
Yes |
True of the telescope is on the west side of the pier as set by the GETSIDEOFPIER command |
| EPOCH | Yes | The epoch of the coordinates used by the telescope. It is set connecting to the telescope. A value of -1 means that the epoch of current date is used. |
|
PIXELSIZEX |
Yes |
The horizontal pixel size in arc-seconds |
|
PIXELSIZEY |
Yes |
The vertical pixel size in arc-seconds |
|
DATE |
No |
The current date in the format: 'YYYY-MM-DD' |
|
TIME |
No |
The current time in the format: 'HH:MM:SS' |
|
HALFFLUXDIAMETER |
Yes |
The current star diameter as set by the last 'autofocus' command |
|
TELESCOPE |
Yes |
The name of the ASCOM telescope driver |
|
DOME |
Yes |
The name of the ASCOM dome driver |
|
OUTGOINGEMAIL |
Yes |
The from address used by the 'email' command |
|
SMTPSERVER |
Yes |
The domain name of the internet mail server used by the 'email' command |
|
FILELINE |
Yes |
The text returned from the GETFILELINE command |
|
FILELINES |
Yes |
The number of lines in a file as returned by the GETFILELINES command |
|
FILELINENO |
Yes |
The line number of a string in a file as returned by the FINDFILELINE command |
|
NUMFIELDS |
No |
The number of fields found as a result of the SPLITFIELDS command |
|
PPSEARCHOVERLAP |
Yes |
The image overlap, in percent, used when building search pattern
used to solve |
|
PPMINIMUMBRIGHTNESS |
Yes |
The minimum brightness that a star must be to be used by PinPoint |
|
PPSIGMAABOVEMEAN |
Yes |
The minimum signal to noise ratio that a star must have before it is used by PinPoint |
|
PPMINIMUMMATCHSTARS |
Yes |
The minimum number of stars that must match to provide a successful PinPoint solve operation |
|
PPMAXIMUMSOLVESTARS |
Yes |
The maximum number of stars to use in PinPoint solve operations |
|
PPCATALOG |
Yes |
The PinPoint catalog type (see the PinPoint documentation for info) |
|
PPCATALOGPATH |
Yes |
The drive and directory that PinPoint looks for its star database |
|
PPCATALOGMINIMUMMAGNITUDE |
Yes |
The brightest magnitude stars from the catalog used in PinPoint solve operations |
|
PPCATALOGMAXIMUMMAGNITUDE |
Yes |
The faintest magnitude stars from the catalog used in PinPoint solve operations |
|
PPROTATIONTOLERANCE |
Yes |
The maximum number of degrees (0 to 20) from north-south that an image can deviate before an otherwise successful PinPoint solve is rejected. |
|
PPSCALETOLERANCE |
Yes |
The maximum amount, in percent, that the image scale can deviate from PIXELSCALEX and PIXELSCALEY before an otherwise successful PinPoint solve is rejected. |
| PPERRORNUMBER | No | The error number as reported by PinPoint if the solve is unsuccessful. |
| PPERRORMESSAGE | No | The error message as reported by PinPoint if the solve is unsuccessful. |
|
POSITIONERROR |
No |
The telescope position error, in arc-minutes, as set by the ‘solveandsync’ command (set it -1 on error) |
|
SKYSTATE |
Yes |
The state of the sky as set by the 'getcloudsensordata' command. It will be one of the following: UNKNOWN, CLEAR, CLOUDY, VERYCLOUDY, or WET |
|
SKYTEMPERATURE |
Yes |
The relative sky temperature (in integer degrees Celsuis) as set by the 'getcloudsensordata' command |
|
AMBIENTTEMPERATURE |
Yes |
The ambient temperature (in integer degrees Celsuis) as set by the 'getcloudsensordata' command |
|
AZ |
Yes |
The azimuth east of north in degrees |
|
ALT |
Yes |
The altitude above the horizon in degrees |
|
HA |
Yes |
The current hour angle of RA and DEC (set by calchourangle command) |
|
SIDEREALTIME |
No |
The current sidereal time in hours |
|
AIRMASS |
Yes |
The current air mass of RA and Dec (set by calcairmass command) |
|
JD |
Yes |
The current Julian Date as set by the calcjuliandate command |
|
SEPARATION |
Yes |
The angular separation as set by the azaltseparation and radecseparation commands |
|
ILLUMINATION |
Yes |
The illumination of the Moon as set by the moonradec command |
|
REFRACTIONENABLED |
Yes |
When enabled relevant calculations are corrected for atmospheric refraction |
|
ELAPSEDTIME |
Yes |
The number of seconds that have elapsed since program start. ELAPSEDTIME is set to zero when program starts, but can be set to any arbitrary positive value. |
|
EXITCODE |
No |
The result sent from external programs. Used by execute, zip, and scp commands. |
|
DOMESTATUS |
No |
The status of the dome shutter (set by getdomestatus command) (0 = open, 1 = closed, 2 = shutter is opening, 3 = shutter is closing, 4 = shutter error) |
|
ORBITERROR |
Yes |
True if the last orbit-related command failed |
|
ORBITMAG |
No |
The magnitude of the most recently computed comet or asteroid |
|
ORBITNAME |
No |
The name of the most recently computed comet or asteroid |
|
ORBITSLOADED |
No |
The number of orbits currently loaded |
|
MAXIMERROR |
Yes |
True if the last MaxIm DL image processing command failed |
|
MAXIMCONNECTED |
No |
True if the connection to MaxIm DL is enabled |
|
XPOSITION |
Yes |
X coordinate returned by radectoxy command and used by the xytoradec command |
|
YPOSITION |
Yes |
Y coordinate returned by radectoxy command and used by the xytoradec command |
|
PHOTOINTENSITY |
No |
The integrated intensity inside the aperture (set by the ‘photometry’ command) |
|
CCDLEFT |
Yes |
The left most pixel, in binned pixels, defining the sub frame used for CCD imaging commands |
|
CCDTOP |
Yes |
The top most pixel, in binned pixels, defining the sub frame used for CCD imaging commands |
|
CCDWIDTH |
Yes |
The width, in binned pixels, defining the sub frame used for CCD imaging commands |
|
CCDHEIGHT |
Yes |
The height, in binned pixels, defining the sub frame used for CCD imaging commands |
|
CCDBINNING |
Yes |
The binning factor used for CCD imaging commands (defaults to 1 in x and y dimensions) |
|
PHOTOMAX |
No |
The maximum pixel value inside the aperture (set by the ‘photometry’ commands) |
|
PHOTOMIN |
No |
The minimum pixel value inside the aperture (set by the ‘photometry’ commands) |
|
PHOTOFWHM |
No |
The full width half max of the star inside the aperture (set by the ‘photometry’ commands) |
|
PHOTOSNR |
No |
The signal to noise ratio of the star inside the aperture (set by the ‘photometry’ commands) |
|
PHOTOFLATNESS |
No |
The flatness (0=round, non-zero=non-round) of the star inside the aperture (set by the ‘photometry’ command) |
|
PHOTOBGAVE |
No |
The average of the background annulus (set by the ‘photometry’ commands) |
|
PHOTOBGSD |
No |
The standard deviation of the background annulus (set by the ‘photometry’ commands) |
|
PHOTOX |
No |
The X-coordinate centroid of the star inside the aperture (set by the ‘photometry’ command) |
|
PHOTOY |
No |
The Y-coordinate centroid of the star inside the aperture (set by the ‘photometry’ command) |
|
PHOTOAPERTURE |
Yes |
The radius of the aperture, in pixels, used by the ‘photometry’ command |
|
PHOTOGAP |
Yes |
The width of the gap between the aperture and the annulus, in pixels, used by the ‘photometry’ command |
|
PHOTOANNULUS |
Yes |
The width of the annulus, in pixels, used by the ‘photometry’ command to determine the background level |
|
PHOTOAPERTURERATIO |
Yes |
The ratio between a star’s full width half maximum and the aperture used by the ‘photometry’ command’s auto-aperture feature. |
|
PHOTOAPERATUREUSED |
No |
The radius of the aperture, in pixels, set and used by the ‘photometry’ command’s auto-aperture command |
|
PHOTOGAPUSED |
No |
The width of the gap between the aperture and the annulus, in pixels, set and used by the ‘photometry’ command’s auto-aperture feature |
|
PHOTOREFMAG |
Yes |
The reference magnitude corresponding to the reference intensity (used by the ‘photometry’ and ‘intensitytomagnitude’ commands in converting integrated intensities to magnitudes) |
|
PHOTOREFINTENSITY |
Yes |
The reference intensity corresponding to the reference magnitude (used by the ‘photometry’ and ‘intensitytomagnitude’ commands in converting integrated intensities to magnitudes) |
|
PHOTOMAG |
Yes |
The magnitude of a star, compared to a reference star (set by the ‘photometry’ and ‘intensitytomagnitude’ commands) |
| PHOTOLM | No | The limiting magnitude of a star in the field at SNR=3 (calculated by photometry commands using reference star magnitude). |
| PHOTOERR | No | The error estimate of PHOTOMAG. |
| AREAMIN | No | The minimum pixel value as set by the "areainfo" command. |
| AREAMAX | No | The maximum pixel value as set by the "areainfo" command. |
| AREAAVERAGE | No | The average pixel value as set by the "areainfo" command. |
| AREASD | No | The standard deviation of pixel values as set by the "areainfo" command. |
|
FILENAME |
Yes |
The filename with directory found by the ‘findfile’ command. |
|
PHOTOJDMID |
No |
The mid-exposure julian date associated with the most recent ‘photometry’ command (0 if unknown). |
|
PHOTODATEMID |
No |
The mid-exposure date and time (taken from the DATE-MID fits header key) associated with the most recent ‘photometry’ command (0 if unknown). |
|
PHOTOHJDMID |
No |
The mid-exposure heliocentric julian date associated with the most recent ‘photometry’ command (0 if unknown). |
|
PHOTOAIRMASS |
No |
The airmass associated with the most recent ‘photometry’ command (0 if unknown). |
|
FOCUSERCONNECTED |
No |
True if the connection to the focuser is enabled |
|
FOCUSERERROR |
Yes |
True if the last focuser-related command failed |
|
FOCUSERPOSITION |
No |
The current position of the focuser (valid for absolute focuser – caused error if used for incremental focusers). |
|
FOCUSERSTEPSIZE |
No |
The step size, in microns, for the focuser |
|
FOCUSERTEMPERATURE |
No |
The temperature of the focuser (valid only for focusers that have a temperature sensor). |
|
FOCUSERMAXSTEP |
No |
The maximum position of the focuser (absolute focusers only) |
|
FOCUSERMAXINCREMENT |
No |
The maximum amount that the focuser position can be moved at one time |
|
PHOTOMINAPERTURE |
Yes |
The minimum aperture used by the ‘photometry’ command’s even when auto-aperture feature would have calculated a smaller number. |
|
TAB |
No |
A string containing the ASCII tab character |
|
CRLF |
No |
A string containing the ASCII carriage return and line feed characters |
| QUOTE | No | A string containing the " (double-quote) character |
|
NULL |
No |
An empty string |
| VERSION | No | The version number of ARAP |
|
NATIVERESULT |
No |
The result returned from the telescope following a ‘nativecommand’ command |
Scripts report two types of errors: soft errors and fatal errors. Soft errors are reported in the log (all errors are displayed beginning with "!!!" so that they are easy to identify) and usually set a corresponding 'ERROR' variable to true. Scripts can either ignore these errors or use an IFTRUE or IFFALSE command to handle the error in appropriate way. An example of a soft error is a "goto" command where the objectname is not found in the database. In this case the FINDERROR variable would be set to true.
Fatal errors cause the script to abort immediately and are triggered when critical errors occur such as those in the table below. If the variable USEFATALERRORSCRIPT is true, then the specified by the FATALERRORSCRIPT variable is run after the script aborts. This script is intended to be used to gracefully shutdown the telescope, CCD camera, dome, etc.
|
Fatal script syntax or other error |
Caused when an error is detected in the syntax of a command |
|
Fatal script error opening sub-script |
Caused when a sub-script cannot be found |
|
Fatal telescope error |
Caused when the 'telescopeon' command fails |
|
Fatal CCD error |
Caused when the 'ccdon' command fails |
|
Fatal CCD image save error |
Caused when a ccd image cannot
be saved. This is usually because the hard disk is full |
|
Fatal dome error |
Caused when the 'domeon' command fails |
|
Fatal X10 interface error |
Caused when the 'x10on' command fails |
|
Fatal ZIP file error |
Caused when the 'zip' command fails to start up its helper
program or if it runs longer |
|
Fatal SCP file error |
Caused when the 'scp' command fails to start up its helper program |
|
Fatal Cloud Sensor error |
Caused when the 'cloudsensoron' command fails |
|
Fatal Planetary Terms error |
Caused when the files used to compute planetary, Sun and Moon positions can’t be read. |
|
Fatal Database error |
Caused when a database file cannot be opened (usually at program startup) |
|
Fatal Focuser error |
Caused when the ‘focuseron’ command fails |