rsaa 2.3 metre telescope observer's manual a preliminary...

1 RSAA 2.3m Observer's Manual Command Summary

RSAA 2.3 metre Telescope

OBSERVER'S MANUAL

A preliminary DRAFT

Research School of Astronomy and Astrophysics The Australian National University Date 3-October-2008 Revision number 1K Number of Pages 62 ____________________________________________________________________________________________ _________________________________________CONTENTS ________________________________________ 1. Introduction and Description................................................................................................................................................. 2 2. Safety and Rules.................................................................................................................................................................... 2 3. Operation of Plant and Auxiliary Systems ............................................................................................................................ 2 4. Telescope Control Console ................................................................................................................................................... 2 5. Remote Control of the Telescope .......................................................................................................................................... 2 6. Operating the Telescope........................................................................................................................................................ 2

6.1 Starting up...................................................................................................................................................................... 2 6.1.1 Starting the telescope when operating remotely .................................................................................................. 2

6.2 An Introduction to the TCS Commands ......................................................................................................................... 2 6.3 Control of the telescope from the rotator handset........................................................................................................... 2

6.3.1 Rotator control in Manual mode .......................................................................................................................... 2 6.3.2 Telescope Control from the Selected Rotator Handset ........................................................................................ 2

6.4 Control of the Telescope from elsewhere in the 2.3m Building ..................................................................................... 2 6.5 Use of the Console Programmable Pushbuttons............................................................................................................. 2 6.6 Observer Files ................................................................................................................................................................ 2 6.7 Shutting Down ............................................................................................................................................................... 2 6.8 Summary of Startup and Shutdown Procedures ............................................................................................................. 2 6.9 Differences between MSOTCS and VAX/VMS Systems .............................................................................................. 2

6.9.1 Changed command syntax ................................................................................................................................... 2 6.9.2 CFILES................................................................................................................................................................ 2 6.9.3 Aperture Definition............................................................................................................................................. 2 6.9.4 Format of coordinates .......................................................................................................................................... 2

7. Command Summary.............................................................................................................................................................. 2 7.1.1 Commands for overall system control ................................................................................................................. 2 7.1.2 Commands for configuration, calibration and mode selection............................................................................. 2 7.1.3 Motion Control & Tracking Commands .............................................................................................................. 2 7.1.4 Auxiliary subsystem commands .......................................................................................................................... 2 7.1.5 Commands for information/status retrieval ......................................................................................................... 2

7.2 Command Syntax – quick reference............................................................................................................................... 2 8. Command Specifications .................................................................................................................................................... 3

8.1 General.......................................................................................................................................................................... 3 8.1.1 Accessibility of Commands ............................................................................................................................... 3 8.1.2 Command response ........................................................................................................................................... 3 8.1.3 Syntax ................................................................................................................................................................. 4 8.1.4 Case Sensitivity .................................................................................................................................................. 4 8.1.5 Syntax outside the cmd_handler environment ................................................................................................ 4 8.1.6 Abbreviation....................................................................................................................................................... 4 8.1.7 Command execution and pre-emption ............................................................................................................. 4 8.1.8 User files ............................................................................................................................................................. 5

8.2 Commands for overall system control ........................................................................................................................ 5 8.3 Commands for configuration, calibration and mode selection................................................................................. 9 8.4 Motion Control & Tracking Commands.................................................................................................................. 20 8.5 Auxiliary subsystem commands................................................................................................................................ 52

8.5.1 List of telescope subsystems ............................................................................................................................ 57 8.5.2 Abbreviation of subsystem names .................................................................................................................. 57

8.6 Commands for information/status retrieval............................................................................................................. 58 9. Remote Control of the Telescope ........................................................................................................................................ 62 10. Control of Telescope Configuration ............................................................................................................................. 62 11. Rotator control.............................................................................................................................................................. 62 12. Celestial Coordinate Format......................................................................................................................................... 62 13. Coordinate, Ephemeris and Orbit Files......................................................................................................................... 62 14. Telescope Console Display .......................................................................................................................................... 62 15. Autoguiding.................................................................................................................................................................. 62 16. Appendix A: Telescope Specification .......................................................................................................................... 62 17. Appendix B: Telescope Operational Limits ................................................................................................................. 62 18. References .................................................................................................................................................................... 62 19. Revision History Table................................................................................................................................................. 62

117 With regards this particular example, note that one cannot place qualifiers within a coordinate specification which must be a contiguous string complying with chapter 1. Thus the command track coord =SAO_252838= 14 39 35.88 wait cw –60 50 7.4 J2000.0 is invalid.

3 RSAA 2.3m Observer's Manual Command Specifications

1. Command Specifications This chapter specifies in detail the syntax and function of the MSOTCS commands used to control the RSAA 2.3metre telescope.

1.1 General

1.1.1 Accessibility of Commands All of the available commands are specified here including those which are intended solely to support engineering operations on the telescope. Accessibility of particular commands or of particular options or field values is on the basis of two TAROS user privilege levels: observer and engineer. No matter whether it is typed into the TCS display window, typed remotely by the user or issued automatically by a remote GUI, every command is checked for privilege by the TCS. A command verb, field value or option setting may be rejected on the basis of that privilege. The TCS response message to a command rejected because of privilege is: [INSUFPRIV] User has insufficient privilege for supplied command or argument.

1.1.2 Command response The response to any user command is identically directed to (i) the TCS display "command response" window which is always visible, (ii) the TCS system log, and (iii) returned to the user's local command line or GUI. The individual responses for each command are given in the command desscriptions below. Standard responses which may be generated by any of the TCS commands include the following: If the TCS processes are running but telescope systems are “off” ie no startup command has been issued, the following string is output: [STARTUP] telescope-name telescope systems are OFF; use the command "startup" to start software and switch on telescope systems If the user does not have privilege equal to or greater than that needed by the command verb or by a specific option or value requested, the following string is output: [INSUFPRIV] User has insufficient privilege for requested command or argument; command ignored If telescope systems have been started and the remote-observer-lockout interlock is subsequently asserted, a remote user will encounter the following response to any command entered: [ROBLOCK]Remote observer lockout is set; command ignored Many commands have fields which are mandatory or which are inter-related; where not all of the required fields have been supplied, one the following strings is output: [MISSPARAM] Missing command line parameter; command ignored [MISSITEMS] Expected variable or field is missing Where parameters which are mutually exclusive or contradictory have been supplied, the following string is output: [MUTEXPARAM] Parameters encountered in command string are mutually exclusive Where extraneous parameters are encountered after the command syntax has been satisfied, the following string is output: [XTRAPARAM] Extraneous parameters encountered in command string

4 Command Specifications

1.1.3 Syntax The command syntax takes the general form: <verb> [ <object> ] [ <value or argument> ] [<qualifier> <qualifier> ..] Whitespace (spaces or tabs) is used as the field delimiter. Many of the verbs, objects and arguments are retained from the existing command set but the VAX/VMS constructs of /QUALIFIER or PARAMETER=VALUE have been discarded because they do not sit comfortably in a POSIX shell command line. Qualifiers are now simply additional fields and, in many cases, may appear anywhere in the command line. For example track coord =SAO_252838= 14 39 35.88 –60 50 7.4 J2000.0 wait cw track coord cw wait =SAO_252838= 14 39 35.88 –60 50 7.4 J2000.0 track coord cw =SAO_252838= 14 39 35.88 –60 50 7.4 J2000.0 wait are all valid and equivalent17.

1.1.4 Case Sensitivity TCS command verbs, standard parameter values and qualifiers must be in lower-case to be accepted. File names, object names and other user-supplied data incur the usual case sensitivity of a UNIX shell environment and if mixed-case is used, such names must be kept consistent. Only a few specific fields will be allowed to be of optional case, for example an equinox specification: J2000.0 or j2000. Such fields are identified clearly below.

1.1.5 Syntax outside the cmd_handler environment In certain cases TCS commands may be generated in a manner which does not quarantine them enroute to the TCS. For example an engineer logged into the QNX6 system on the TCS computer or running a shell script will have TCS commands such as set or shutdown usurped by that shell; such command words are predefined in the shell. To preserve telescope commands from misinterpretation in such environments, the command verb can be preceeded by the "metaverb" tcs. This may be done on an individual command basis since the TCS will strip off the metaverb and ensure that the appropriate TCS commmand is executed. Thus the following command will always be interpreted correctly as in §1.1.3 above: tcs track coord =SAO_252838= 14 39 35.88 –60 50 7.4 J2000.0 wait cw

1.1.6 Abbreviation Command verbs, parameters and qualifiers can be abbreviated by any unique string of two or more characters from the start of the template string; for example rot is permitted as a diminutive for the rotator command. In some cases such as subsystem names, the rule for abbreviation is more relaxed than for other command elements: these may be abbreviated by any n ≥ 2 characters which uniquely match a string of n consecutive characters anywhere in the template. For example: ventilation_fans may be shortened to vent or fans (or even _fa ) when the relevant command is manually entered. Note that abbreviation is intended for use when entering a command string manually. As a convention, abbreviated forms should never be used in scripts or in documentation nor generated by a GUI since this defeats the objectives of clarity and self-documentation.

1.1.7 Command execution and pre-emption Commands are checked for correct syntax and then for appropriate privilege level before being executed in the order of arrival. Most commands will return control to the user immediately they have been accepted and will complete execution (or time-out) before another command is started, ie ordinary commands are queued. However commands which affect telescope motion or activate mechanisms such as the focuser are executed independently from ordinary commands and differ in their queueing behaviour. When a motion control command is issued, it will always pre-empt or over-ride any other motion control command that was previously issued whether that command has finished execution or not. It will not affect another (non-motion-control) command because they are handled independently. All commands normally return control to the user immediately they are accepted. However motion control commands (and some others) may have the wait qualifier appended to ensure that control is only returned once the motion has completed (for example when the telescope is tracking the desired position). The wait qualifier is especially necessary when motion control commands are embedded in scripts or automatic sequences.

Command Specifications 5

The command halt is special in that it will pre-empt any motion control command even if that command had the wait qualifier set and will cause the telescope axes and rotator (and building rotation drive) to stop.

1.1.8 User files User files such as configuration files, coordinate files, ephemeris or orbit files may be downloaded to the TCS machine using the command fetch. They are stored in the telescope user data area $MSOTCS_DATA which is normally set to the directory /home/telescope/data. No other directory in the embedded machine is accessible to an observer. The contents of this directory and that of any given user file may be viewed at the files tab of the TCS display. User files cannot, however, be editted or deleted whilst in the TCS environment; such manipulation must be carried out in the user's environment before fetching into the TCS.

1.2 Commands for overall system control startup simulate shutdown See also the motion control command halt and the information command diagnose. startup (priv=observer) Synopsis startup [user|current|filename] Description This command starts the telescope system by initializing the TCS processes, loading the central database with constant parameters and the telescope configuration and turning on the telescope and plant control electronics. After the database is loaded with site parameters and IERS data18 a default configuration file is read and loaded. An additional user-specified configuration file may be loaded depending on the command line parameter supplied. If the necessary control processes are not running they are started automatically. A hardware diagnostic sequence is executed and a TCS database flag is set to enable user control. This command must be used be issued ahead of any other TCS command (except simulate, see below) to give the observer control of the telescope. If telescope systems are off, startup and simulate are the only commands accepted by MSOTCS.

Parameters A command line parameter controls whether the system attempts to load an additional configuration file. If the parameter is the keyword user then a search is made for the file config_user. This file is supplied to the TCS by the user and is the primary means the observer has of tailoring the telescope operations to their requirements. Thus the command startup user brings the telescope system up in a known initial state. If the parameter is the keyword current the configuration file config_current is sought. MSOTCS creates this file and writes to it all changes to the telescope configuration. The command startup current is the way an observer can recover the configuration in place immediately before a shutdown. If a string other than the keywords user or current appears, it is taken literally as the filename of the required configuration file; the directory /home/telescope/data is searched for the file.

Standard Response As soon as the command is accepted the following message is output: [TELSTARTUP] Starting 2.3m telescope systems… Subsequently various messages are issued as the startup sequence progresses or problems are encountered. When the startup sequence completes successfully the following message is output: [TELSYSOK] Telescope systems functioning and ready for observing

18 IERS data is derived from the International Earth Rotation Service and contains information specifying polar motion and earth rotation angle.


If the telescope system is currently running the command is ignored with the following message: [TELSTARTX] 2.3m telescope systems are running or startup in progress; command ignored. If the telescope system is not running but the remote observer lockout interlock is set, the startup sequence will be executed as far as switching on the console; at this point the remote observer lockout will be detected and the system shutdown again; the following message is issued: [ROBLOCK] Remote observer lock-out is set; command ignored If the telescope system is currently running and the remote observer lockout interlock is set, the command (or any command issued by a remote user) will be rejected with the [ROBLOCK] message. Should the startup sequence fail unredeemably, the following message is output: [TELSYSFAIL] Startup sequence failed – TELESCOPE SYSTEMS UNUSEABLE – Should the startup sequence fail for minor reasons, the following message is output: [TELMTNPOSS] Startup completed; telescope systems abnormal but observing may be possible, see diagnostic messages If the nominated configuration file cannot be found or cannot be opened, the startup sequence is continued but the file problem is signalled by an appropriate warning message: [CFILOADERR] Configuration file is missing or cannot be opened simulate (priv=observer) Synopsis simulate [options] Description This command permits the individual controllers which make up MSOTCS to run in simulation mode. When in simulation mode, a controller ignores status and feedback data from the telescope hardware and mimics the action using simple mechanistic models, realistic delays and pseudo-random noise. The observer sees plausible measurement values for all encoders and transducers and appropriate states for the various digital inputs. If a subsystem does not named in the option list, then its control regime and reported status are unaffected. The command must preceed the startup command19 and functions by 'arming' a number of database flags which are inspected by the code which implements the startup sequence. After telescope systems have started, the simulate command cannot be used to add or remove subsystems from simulation (the telescope must be first shutdown); however it may be used to get information which ones are being simulated. The subsystem simulation described above leaves the TCL control channel to the telescope hardware intact. A deeper level of simulation is provided which mimics this UDP protocol and can be run even in the absence of the telescope electronic hardware. This protocol simulation can be accessed only by an engineer logged into the QNX6 operating system and is not available as a TCS command. It is however, reported in the informational message[SIMULIST].

Parameters Any combination of the parameters azimuth, altitude, rotator, focuser, dome, wscrn, aux and manual may be supplied, in any order, separated by whitespace. A parameter may be abbreviated by any unique consecutive substring. Each parameter which is present causes the appropriate subsystem or controller to be placed in simulation mode. simulate all The single parameter all may be used to ensure that all of the subsystems/controllers are simulated. simulate none The single parameter none may be used to ensure that none of the subsystems/controllers are simulated. The command without any parameters: 19 simulate is in fact the only command which can be validly entered ahead of the command startup.


simulate can be used at any time (including when the telescope is running) to request information on which sub-systems are in simulation mode.

Standard Response A successful change to the mix of simulated sub-systems is indicated by one of the following messages: [SIMULIST] Sub-systems simulated: [az][alt][rot][foc][dome][wscrn][aux][man] [protocol] [NOSIMUL] Sub-systems normal; no sub-system is being simulated When the telescope systems are running, an attempt to change the simulation is rejected with the message: [CANTSIMUL] Telescope systems are running; no change of simulation possible, you must first shutdown! The command simulate is a request for information and is always answered with the messages: [SIMULIST] Sub-systems simulated: [az][alt][rot][foc][dome][wscrn][aux][man] [protocol] [NOSIMUL] Sub-systems normal; no sub-system is being simulated shutdown (priv=observer) Synopsis shutdown [options] Description Shuts down the telescope control system in an orderly fashion and switches off the telescope control electronics. The exact sequence of operations can be controlled by options appended to the command. Specifically, the command slews the mount to the park position and halts, stows the tertiary mirror, closes the mirror cover, waits for three seconds to allow the mirror cover to race the building shutter then switches off the ventilation fans and closes the building shutter. After another 4 second wait, the TCS commences checking for completion of the various actions; appropriate success or failure messages are issued for each operation. The console displays are blanked and finally the telescope sub-systems are switched off. (Note that the rotator and focuser are halted at their positions when the command is issued.) The observer also has control of whether the TCS component processes are killed20 or continue to run and may also force a complete reboot of the QNX operating system.

Parameters Any combination of the parameters park, tertiary_mirror_drive, mirror_cover, ventilation_fans, building_shutter, telsys or console may be supplied in any order separated by whitespace. A parameter may be abbreviated by any unique consecutive substring. Each parameter which is present causes that operation to be included in the shutdown sequence: park the telescope is driven to the park position; tertiary_mirror_drive the tertiary mirror (if installed) is driven to the stowed position; mirror_cover the primary mirror cover is closed; ventilation_fans the ventilation fans are switched off; building_shutter the building shutter is closed; telsys telescope systems (hardware and plant) are switched off; console 2.3m control console is switched off; kill_processes all MSOTCS component processes are killed 21 (except cmnd_server); no_restart all MSOTCS component processes are killed and additionally are prevented from restarting; reboot the QNX6 operating system is shut down and the TCS machine rebooted; Two exclusive parameters all or fast may be used to execute frequently needed variants of the command: The command shutdown all performs an "end-of-the-night" shutdown and parks the telescope; it is interpreted as shutdown park tertiary_mirror_drive mirror_cover fans shutter telsys console The command shutdown fast simply halts the telescope (and all auxiliary mechanisms) and, after minimal delay, implements a TCS software hibernation without switching anything off or closing shutter or mirror cover.

20 Unlike the VAX/VMS TCS, MSOTCS does not normally kill its component processes when it shuts down. The database flag tel_systems_state indicates to all processes whether they should function and whether there is controllable telescope hardware. 21 Note that MSOTCS can always be restarted after the processes have been killed; the cmnd_server is able to start watchdog and therefore all of the component processes upon receipt of the command startup.


The exclusive parameters kill_processes, no_restart or reboot may be needed for maintenance or diagnostic operations: shutdown kill_processes performs a telescope systems switchoff and asks the watchdog process to kill all of the TCS processes except safe_start. Similarly, shutdown no_restart performs a telescope systems switchoff and kills the processes, but in this case they will not be automatically be restarted. shutdown reboot performs a telescope systems switchoff, kills the TCS processes and performs a standard QNX6 operating system reboot. If no parameter is present, a default sequence is executed in which most options are included but the telescope is not parked. Observers will often use this form of the command to wait out an adverse weather situation. Hence shutdown is interpreted as shutdown tertiary mirror_cover fans shutter telsys The option mirror_cover should always be included when shutter is present to reduce the chance of debris from the shutter falling onto the primary mirror as the shutter closes (the mirror cover will close before the shutter).

Standard Response As soon as the command is accepted, the following message is output: [TELSHTNGDN] Shutting down 2.3m telescope systems If telescope systems are already shutdown, the following message is output: [TELSHTDNX] 2.3m telescope systems are not running; command ignored As each operation completes successfully, a specific message such as the following is output: [COVCLOSED] Primary mirror cover has closed Alternatively if an operation fails or times out, a specific message such as the following is output: [COVNOCLOSE] Time-out - Primary mirror cover failed to close Any failure which is deemed more serious generates an augmented message; thus: [SHTNOCLOSE] Time-out - BUILDING SHUTTER FAILED TO CLOSE. [NOTIFY] *** TELESCOPE IS NOT IN A SAFE STATE TO LEAVE; notify technical staff on site. ***


1.3 Commands for configuration, calibration and mode selection calibrate configure fetch retrieves a nominated cfile/coord/ephem/orbit file from the user (TAROS) environment load configures telescope settings using a nominated cfile ls lists the contents of the use data directory MSOTCS_DATA pushbutton save saves current configuration as a user cfile tpclose the tp*** commands manage pointing data files and permit capture of pointing data... tpcomment tpcount tpdata tpopen calibrate pointing (priv=observer) Synopsis calibrate pointing [xc yc] Description Corrects the telescope pointing in the local region by modifying the two collimation constants xc and yc. The behaviour of the command depends upon whether the collimation values have been supplied explicitly. If xc and yc are given, they are immediately loaded into the appropriate configuration variables; they take effect when a subsequent track command is issued. If the telescope is already tracking, it is offset to reflect the new pointing calibration. By contrast, the automatic command calibrate pointing assumes that the observer has positioned an object (whose coordinates are accurate) in the selected aperture (which has been accurately defined). The collimation constants are automatically calculated from the offsets (celestial or focal plane) which have been introduced in order to centre the object, and those offsets are absorbed into the new collimation constants; the telescope is not moved from its current tracking position.

Parameters The parameter pointing must appear. The parameters xc and yc must be valid numerical quantities and are interpreted as the collimation constants in arcseconds; both parameters must be present or neither. The collimation offsets lie in the standard (non-rotating) focal plane: yc is the collimation correction in the direction of altitude (η direction), xc lies in the transverse direction (ξ direction).

Standard Response Upon successful return from the explicit command, the following message is output: [CALPOINT] Pointing calibrated: collimation constants Xc, Yc changed from xxx.xx, yyy.yy to xxx.xx, yyy.yy (arcsec) Upon successful return from the automatic command, the following message is output: [CALPOINTA] Pointing calibrated for object name RA= hh:mm:ss.s DEC= ±dd:mm:ss.ss Cosys= eqnx; \n collimation constants Xc, Yc changed from xxx.xx, yyy.yy to xxx.xx, yyy.yy (arcsec) If the telescope was not tracking when the automatic form was issued, the following message is output: [NOTRACKING] The telescope is not tracking; command ignored If one or both of xc or yc are not valid numerics, the following message is output: [INVPARAM] Invalid command line parameter; command ignored If only one numeric field is present, the following message is output: [NEEDBOTHXY] Both collimation constants must be specified calibrate aperture (priv=observer)


Synopsis calibrate aperture aper-name Description Starts an interactive sequence to calibrate an aperture (pointing origin). The observer sets on a object whose coordinates are known accurately and makes consecutive adjustments repeatedly centring the object in the aperture to be calibrated. The instrument rotator is rotated through a known angle between the settings22. The system calculates the aperture position xa, ya and the two collimation constants xc, yc. An optional additional sequence permits calibration of an instrument alignment angle, for example for a slit aperture. In this case, the system calculates the iaa value and includes it in the aperture definition. If this sequence is skipped, iaa for the aperture is set to zero. The telescope must already be tracking before the command is issued. The aperture definition and collimation constants are automatically calculated from the offsets (celestial or focal plane) which have been introduced in order to centre the object. If desired, these collimation values can be loaded into the observer's configuration variables enshrining them as the local pointing correction. At the completion of the command, the aperture just calibrated is selected. The offsets are absorbed into the new aperture definition and (optionally) the collimation constants. In this case, the telescope is left tracking at its current tracking position. This interactive sequence of steps is facilitated by inviting the observer to enter the pseudo-command next to proceed to the next step.

Parameters The parameter aperture must appear. The aperture name aper-name gives the name or designation by which the aperture is to be known. It may be any string of up to 16 standard printable characters; the case of the characters in the string is preserved in the aperture table but ignored when seeking a match for the purpose of aperture selection or deletion. The aperture name "0 " is reserved and cannot be redefined by this calibration command.

Standard Response Since the command is interactive, various messages are issued at stages during the calibration sequence. When the command is accepted, the following message/prompt is output: [CALAPER] Calibrating focal_stn aperture aper-name When the first data is needed, the following message/prompt is output: [GETAPER1] Without moving rotator, centre star in aperture \n and type "next" (or "cancel" to quit): When the rotator commences moving automatically, the following message is output: [REPOSROT] Now repositioning rotator 120 degrees away; please wait... If the rotator must be repositioned manually, the observer is prompted by the message: [MOVEROT] Please move rotator to dddd.dd degrees (or dddd.dd if more convenient) \n and type "next" (or "cancel" to quit): If the rotator is NOT_IN_USE, the observer is prompted to manually enter the current rotator angle: [ENTEROTANG] Enter current rotator angle in degrees: If the rotator cannot be repositioned inside the current limits, the following message is output: [CALROTLIM] Current rotator limits do not allow the rotator to be repositioned \n Aperture calibration cancelled After the rotator has been repositioned and the second data is required, the following message/prompt is output: [GETAPER2] Without moving rotator, centre the same star in aperture \n and type "next" (or "cancel" to quit): After the aperture constants xa, ya have been calculated, the following message/prompt is output: 22 It is highly desirable that the rotator be configured so that it removes field rotation ie rot_reference should be set to POSITION_ANGLE. However, an aperture can be calibrated satisfactorily with the rotator STATIONARY or under manual control if the observer works quickly.


[SLITCAL] If this aperture is a slit and the orientation of the slit needs to be calibrated \n the star will have to be centred at each end of the slit; \n Do you wish to calibrate orientation angle iaa (e.g. for a slit aperture)? [N] When the first slit calibration is needed, the following message/prompt is output: [GETSLIT1] Without moving rotator, centre star at "beginning" of slit \n and type "next" (or "cancel" to quit): When the second slit calibration is needed, the following message/prompt is output: [GETSLIT2] Without moving rotator, centre star at "end" of slit \n and type "next" (or "cancel" to quit): With the completion of aperture calibration, the following message is output: [CALAPER] Aperture aper-name calibrated: xa = xxx.xx ya = yyy.yy iaa = ddd.dd To determine whether or not to discard the collimation constants, the following prompt is output: [CALPOINTOO] Do you wish the pointing to be calibrated at this position? [Y] If the observer wanted the collimation constants to be used to correct the pointing, the following message is output: [CALPOINT] Pointing calibrated: collimation constants Xc, Yc changed from xxx.xx, yyy.yy to xxx.xx, yyy.yy (arcsec) If the telescope is not tracking when the command is issued, the following message is output: [NOTRACKING] The telescope is not tracking; command ignored If the telescope zenith distance is excessive, the following message/query is output: [ZDTOOLARGE] Zenith distance is greater than 45 deg; results may be affected by refraction \n Do you wish to continue? [N] If the telescope zenith distance is small, the following message/query is output: [ZDTOOLARGE] Zenith distance is less than 20 deg; results may be affected by field rotation \n Do you wish to continue? [N] If the parameter aper-name is missing, the following message is output: [APERMISSNG] Aperture specification missing If the aperture table is full, the following string is output: [EXMAXAPER] Insufficient room in aperture table; attempt to define further apertures ignored If the aperture table already contains an aperture with the supplied name, the following message is output: [APEREXISTS] Supplied aperture name already exists; command ignored If the supplied aperture name is disallowed or contains illegal characters, the following string is output: [XAPERNAME] Supplied aperture name is not legal; command ignored If an attempt was made to clear aperture 0, the following string is output: [RESAPNAME] Reserved aperture name; attempt to redefine or delete aperture 0 ignored If a response was terminated by a CTRL/Z character, the following message is output: [CALAPCANCL] Aperture calibration cancelled


configure (priv=observer) Synopsis configure variable-name value [wait] Description Sets the TCS scalar configuration variable to the value supplied. The configuration value can be one of a set of options, a free-field numeric quantity or a file-specification depending on the variable. A list of configuration variables for the 2.3m telescope is given in chapter 1. For configuration variables which are distinct for each focal station,23 the value supplied is set only into the operational area of the central database; any focal station data previously introduced from a configuration file is not changed unless a subsequent save command re-writes that file. For multi-valued configuration variables the syntax is somewhat more complicated and is specific to the particular set of variables; the multi-valued variable form of the command is given below. Note that, for convenience, some configuration variables can also be set from within dedicated commands; for example the rotator may be set to position-angle mode by the command rotator position_angle. Where possible the syntax of these alternative means of configuration has been kept as consistent as possible with that of the configure command. To configure the telescope using a configuration file (cfile), see the command load.

Parameters The parameter variable-name must be one of a list of telescope-specific configuration variables and value a permitted value or option for that variable. If the flag wait is present, the system returns control only after the configuration action (or motion) has successfully completed. Otherwise control is returned immediately. The wait option is particularly useful when operating from a script or when configuring items (such as focal_station) which involve mechanical motion (the tertiary mirror may need to be moved to switch focal stations).

Standard Response As soon as the command is accepted, the following string is output: [CONFIGCMD] Changing telescope configuration If the parameter variable-name is illegal or unexpected, the following string is output: [UNXPCONFIG] Unexpected configuration variable encountered If the parameter value is invalid or out of range, one of a number of strings may be output; (these are given below for the command load). If the wait qualifier has been appended, the response generated when the motion completes successfully is: [CONFIGFIN] Telescope configuration complete configure (multi-valued variables) (priv=observer) Synopsis configure group-name value1 [value2...] Description Sets a group of related TCS configuration variables to the values supplied. This form of the command is used where a number of related variables must be set atomically to consistent values. In most cases the syntax given above coincides closely with alternative commands which affect the particular variable. The specific cases are given below: group-name = iaa_source (see rotator command for detailed definitions) configure iaa_source aper configure iaa_source slit aper_1 23 Such configuration data includes rotator control settings, apertures and beams etc which are set independently for each focal station.


configure iaa_source radial aper_1 configure iaa_source aper_pair aper_1 aper_2 configure iaa_source angle φ There are also five scalar rotator configuration variables are closely related to this group: configure rotator_cw_limit θlimit configure rotator_ccw_limit θlimit configure rotator_reference not_in_use|stationary|position_angle| vertical_angle configure rotator_wavelength λ configure rotator_opt field|slit group-name = aperture (see aperture define command for detailed definitions) configure aperture aper-name xa ya [iaa] group-name = beam (see beam define command for detailed definitions) configure beam A|B|C coord-spec [guide coord-specg expose time win bin] configure beam A|B|C offset ∆ra ∆dec [guide ∆rag ∆decg expose time win bin] group-name = guide (see guide command for detailed definitions) configure guide coord coord-spec configure guide expose time win bin configure guide free|fixstage|fixpixref group-name = pushbutton (see pushbutton command for detailed definitions) configure pushbutton n [command-string [label label-string ]] Parameters The parameter group-name must be one the telescope-specific configuration groups rotator, iaa_source, aperture, beam, guide or pushbutton. The parameters value1, value2 etc contain the values for the component variables in the group. They must occur in the order prescribed and (except as follows) must all be present. In some cases, the last required value may be omitted; this and other issues are made clear in the command descriptions for the dedicated commands: rotator, aperture define, beam define, guide and pushbutton. Control is returned immediately.

Standard Response If the command is successful, one of the following strings is output: [ROTCWLSET] Rotator clockwise limit set to xxxx.xxx (degrees) [ROTCCWLSET] Rotator counter-clockwise limit set to xxxx.xxx (degrees) [ROTREFSET] Rotator reference set to XXXXXXXX_XXXXX [ROTIAASET] IAA source set to XXXXXX aper1=aper1name aper2=aper2name iaa_obsvr=ddd.dd (deg) (Note that fields indicated with shading may be individually supressed with blanks if they are not relevant to the current setting of iaa_source.) [ROTWAVSET] Rotator wavelength set to xxxxx.x (nm) [ROTOPTSET] Rotator control optimization set to XXXX [APERDEF] Aperture aper-name defined at xa = xxx.xx ya = yyy.yy iaa = ddd.dd [BEAMDEF] Beam X has been defined [BEAMDEFNOG] Beam X has been defined; no guide object was specified [GUIDEDEF] Guide object defined name RA= hh:mm:ss.s DEC= ±dd:mm:ss.ss Cosys= eqnx [PPBDEF] Console pushbutton n set to command-string label= aaaaaaaa/bbbbbbbb If the parameter group-name is illegal or unexpected, the following string is output: [UNXPCONFIG] Unexpected configuration variable encountered If a parameter valuex is invalid or out of range, one of a number of strings may be output; (these are given below for the commands rotator, aperture define, beam define, guide and pushbutton). fetch (priv=observer)


Synopsis fetch url [filename] Description Fetches or retrieves a text file from the TAROS environment. This is the mechanism by which user configuration, coordinate, ephemeris and orbit files are loaded into the TCS. The file is stored in the TCS data directory $MSOTCS_DATA with the same filename as the source or alternatively may be given a new filename in the TCS system. The types of user files which are of interest are tabulated below:

file type file extension (preferred but not mandatory)

purpose

configuration file or "CFILE" .cfile telescope configuration and optional settings coordinate file .coord lists of celestial objects ephemeris file .ephem ephemeris data for tracking celestial object orbit file .orbit standard orbital elements for tracking celestial object

The TCS can host a number of user files which serve as configuration files (CFILEs), coordinate files, ephemeris files or orbit files. These are text files and must comply with the format specifications given in chapter 1. Filenames are case sensitive and, unless the parameter filename is present, are preserved across the TAROS system. The extensions .cfile, .coord, .ephem and .orbit are preferred but not enforced 24. Problems with the syntax or contents of a file will only be detected when it is read and acted upon by the TCS, not at the time it is fetched. Note that system control files such as the telescope parameter file and pointing correction files cannot be loaded by the command fetch; they may only be loaded by an engineering user logged into the QNX6 TCS machine. Files fetched using this command persist indefinitely in the TCS directory $MSOTCS_DATA until deleted by engineering staff 25. It is possible in future that an automatic clean-up mechanism will be deployed to prevent user files accumulating but this is not considered here.

Parameters The parameter ur l is mandatory and must specify the location of the file as a Universal Resource Locator (URL); it may take any of the usual forms such as ftp://host/file-spec or http://host/file-spec. If ur l takes the form ~username/file-spec, it is interpreted as http://mso.anu.edu.au/~username/file-spec. The parameter filename is optional and specifies the filename to be used in the TCS system. It must not specify a directory or extended file path. If it is omitted, the filename (filename only) of the source is preserved.

Standard Response Upon successful return, the following string is output: [FETCHEDFIL] User file filename fetched from URL If the parameter ur l was omitted, the following string is output: [MISSPARAM] Missing command line parameter; command ignored If the URL cannot be accessed or if the required file could not be found, the following string is output: [FETCHFAIL] URL cannot be accessed or requested file cannot be found If the file in the TCS user area $MSOTCS_DATA could not be opened for writing, the following string is output: [FETCHFLERR] User file filename could not be created or over-written If the user specified a directory or extended path for the parameter filename, the following string is output: [FILNAMEBAD] The TCS filename must not be a directory or path load (priv=observer) Synopsis load [filespec] 24 TCS commands which access user files may retry file operations by appending the appropriate extension to the filename. For example, track file filename will first attempt to find $MSOTCS_DATA.filename but if it cannot be found or opened, tries to open the file $MSOTCS_DATA.filename.coord 25 A user may, of course, overwrite any file by fetching another file and re-using the filename.


Description Configures the telescope system by "loading" the nominated configuration file (cfile). During telescope startup the system automatically loads the default cfile: $MSOTCS_HOME/config/config_std. Depending on the options supplied to the startup command, it then attempts to augment this configuration with a cfile nominated by the user. The command load enables the observer to reconfigure the telescope using an alternative cfile at any time. If unexpected data or an invalid record is encountered in a cfile, the load command fails and all of the configuration represented by the file is ignored.

Parameters If present, the parameter filespec must contain a file specification of the file with which the user wishes to configure the telescope system. If filespec commences with a leading / character, it is interpreted as a complete path specification and referenced in its entirety; otherwise it is assumed to be only the filename and is prepended with the default data directory so that the file specification becomes $MSOTCS_DATA.filespec. The command attempts to open and interpret the cfile; if the file is not found with the filename/file specification supplied, the suffix .cfile is appended and the file open retried. If no filename parameter is supplied, the system reopens the user configuration file: $MSOTCS_DATA/config_user.

Standard Response If the file is succesfully loaded, the following string is output: [CFILELOAD] Configuration file filespec loaded If the file cannot be found or cannot be opened, the following string is output: [CFILOADERR] Configuration file filename missing or cannot be opened If an unexpected or invalid record is encountered, one of the following strings is output and the configuration read so far is ignored: [CFILGROUP] Unexpected configuration variable encountered in group group (unexpected records listed) [UNXPCONFIG] Unexpected configuration variable encountered [CNFDECVBL] Configuration variable name invalid or cannot be decoded [CNFDECVAL] Configuration variable value invalid or cannot be decoded [MISSITEMS] Expected variable or field is missing [OUTRANGE] Supplied variable is out of range [SECNOTDEF] Secondary mirror must be defined before configuring focal station [SECWRONG] Secondary mirror not compatible with focal station configured [CNFPREREQ] Attempt to configure variable for which there are prequisite variable(s) missing [ERRINEQX] Error in coordinate system (equinox or epoch) supplied [MISSCOSYS] Coordinate system specification (cosys) missing [APNOTDEF] Nominated aperture is not defined [APERNOTDIF] APER1 and APER2 must refer to different apertures [APERMISSNG] Aperture specification missing [IAARANGE] Supplied instrument alignment angle (IAA) is out of range [IAAMISSING] Instrument alignment angle (IAA) specification is missing [RESAPNAME] Reserved aperture name; attempt to redefine or delete aperture 0 ignored [EXMAXAPER] Insufficient room in aperture table; attempt to define further apertures ignored [ERRINRA] Error in right ascension coordinate supplied [ERRINDEC] Error in declination coordinate supplied [SKYCONLY] Coordinate system specification error; AZEL_TOPO is not permitted [APPTONLY] Avoidance object may only be specified using apparent coordinates [CFILIGNORD] CAUTION - User configuration file was ignored; default or prior configuration prevails pushbutton (priv=observer) Synopsis pushbutton n [command-string [label label-string ]] pushbutton clear


pushbutton [show] Description Associates the console programmable pushbuttons with particular telescope commands. Note that this command applies only to the programmable pushbuttons physically located on the telescope console or on the telescope handset near the focal station. Its purpose, therefore, is to manage a “legacy” system and to allow the console functionality to be set from a script; the command cannot be used to configure the equivalent programmable widgets present in the TCS GUI at the TAROS level. The programmable pushbutton layout is shown below.

Parameters pushbutton n [command-string [label label-string ]] associates the command command-string with push button number n. n must be an integer in the range 1 to 16. Whenever that pushbutton is depressed, the associated command is executed. The mimic on the console display monitor is labelled with two lines of eight characters obtained from label-string or, if this is omitted, the first 16 characters of the command-string. If both strings are omitted, the pushbutton is set to "undefined" and any previous association it had is lost. Thus the command pushbutton n can be used as a means of clearing an individual programmable pushbutton. The command pushbutton clear causes all 16 programmable pushbuttons to be undefined. The command pushbutton show or simply pushbutton causes a list to be output showing the current definitions for all 16 programmable pushbuttons.

Standard Response Upon successful return, the following string is output: [PPBDEF] Console pushbutton n set to command-string label= aaaaaaaa/bbbbbbbb If the pushbutton index was out of range, the following string is output: [PPBNUM]Pushbutton not defined: index must be in range 1 to 16 If the command-string was of excessive length or is corrupted, the following string is output: [PPBCMDERR] Pushbutton n not defined: command string is corrupted or too long If the qualifier clear is present, the following string is output: [PPBALLCLR] All programmable pushbuttons cleared If the qualifier show is present or if the command is entered without any parameters, the following string is output: [PPBDATA] Current console progammable pushbutton definitions: PPB1: command-string [aaaaaaaa/bbbbbbbb] \n PPB2: command-string [aaaaaaaa/bbbbbbbb] \n .. PPBn: (not defined) \n .. PPB16: command-string [aaaaaaaa/bbbbbbbb] \n Note: (i) the label-string cannot generate an error since the label is robustly extracted as the first 8x2 characters of the

string, and (ii) no check is performed on the validity of a command at the time of defining the pushbutton; an error in the

command only becomes evident when the pushbutton is activated and the defined command is executed. save (priv=observer) Synopsis save [filename]


Description Saves the current telescope configuration data to the TCS user area $MSOTCS_DATA as a configuration file (cfile) with the filename supplied. Current configuration data which is focal station dependent26 is saved under a group heading [NASMYTH_A], [NASMYTH_B]or [CASSEGRAIN] which is appropriate for the currently selected focal station; the current configuration data for the other focal stations is preserved unchanged. Only configuration data can be "saved"; other types of user files such as a coordinate, ephemeris or orbit files cannot be modified or have data appended once they are "fetched" into the TCS system and so is not possible to subsequently "save" them.

Parameters The parameter filename specifies the user's filename for the configuration file in the TCS user data area $MSOTCS_DATA. If the file name does not have an extension, the extension .cfile is appended. If no filename parameter is supplied, the system records the "current" configuration file: $MSOTCS_DATA/config_current.

Standard Response Immediately the command is entered, the following string is output: [SAVECFILE] Saving current telescope configuration Upon successfully saving the configuration, the following string is output: [CFILESAVED] Current configuration saved as filename If the file in the TCS user area $MSOTCS_DATA could not be opened for writing, the following string is output: [CFILSAVERR] User CFILE filename could not be created or over-written If the user specified a directory or extended path for the parameter filename, the following string is output: [FILNAMEBAD] The TCS filename must not be a directory or path To allow access to user data files and enable the observer to transfer user files to an external machine, the TCS system runs a minimum web-server. For the 2.3metre telescope the URL is //merope.anu.edu.au and the visible data is restricted to the $MSOTCS_DATA area. tpclose (priv=engineering) Synopsis tpclose Description Writes an END record to the currently open file containing telescope pointing data and closes the file. The name of the file and the number of observations in the file are reported. An alternative message is issued if there was no pointing data file open. The END record has the simple format: END

Parameters none

Standard Response Upon successful return, the following message is output: [TPFCLOSED] Pointing data file filename closed; nnnn observations recorded If there was no pointing data file open, the following message is output: [TPFNOTOPEN] No pointing data file open tpcomment (priv=engineering) 26 Such configuration data includes rotator control settings, apertures and beams etc which are set independently for each focal station.


Synopsis tpcomment [comment-string] Description Inserts a comment record into the currently open pointing data file by first writing a ! character27 followed by the supplied comment string. Alternatively a completely blank record is written.

Parameters The comment-string may be any text string up to 79 characters long. White space must separate the comment from the command verb, but any subsequent white space is treated as part of the comment and copied verbatim to the file record. The recorded comment is truncated after 79 characters. If no comment string is present, a blank record is written to the file.

Standard Response Upon successful return, the following message is output: [TPFCMNT] Comment inserted in pointing data file after observation nnnn If there was no pointing data file open, the following message is output: [TPFNOTOPEN] No pointing data file open tpcount (priv=engineering) Synopsis tpcount Description Causes a message to be output showing the number of telescope pointing measurements recorded so far in the currently open pointing data file. No change is made to the contents or status of the file.

Parameters none

Standard Response Upon successful return, the following message is output: [TPFCOUNT] Pointing data file filename open; nnnn observations recorded If there was no pointing data file open, the following message is output: [TPFNOTOPEN] No pointing data file open tpdata (priv=engineering) Synopsis tpdata [autoguider] [aux1 [aux2 [aux3]]] Description Records a telescope pointing measurement by writing an observation record to the currently open telescope pointing data file (tpdata file). The pointing observation record is compatible with the TPOINT analysis package28 INDAT format #4 and takes the form: az_obs alt_obs az_tel alt_tel aux1 aux2 aux3 where: az-obs is the observed29 azimuth of the star, alt-obs is the observed altitude of the star, az-tel is the telescope mount azimuth reference, alt-tel is the telescope mount altitude reference,

27 Most MSOTCS control files permit ! or # characters to be used anywhere to delineate comment records; a pointing data file can use only the ! character since it must be compatible with the TPOINT package. 28 TPOINT A Telescope Pointing Analysis System version 8.3 Patrick Wallace, Tpoint Software, Abingdon, Oxfordshire, UK OX14 4HH 29 The observed place of a star is the actual topocentric direction to the star as read from the scales of a perfect theodolite; it is the apparent place corrected for earth rotation, diurnal aberration and astronomic refraction.


aux1, aux2 and aux3 are optional auxiliary data readings. The auxiliary data30 values may be supplied by appending them to the tpdata command line; if they are omitted they are obtained from database variables auxil_data[0], auxil_data[1] and auxil_data[2]. The angular variables must be recorded in degrees.

Parameters The qualifier autoguider (or a suitable abbreviation) may be used to cause the autoguider31 to return the centroid of the object so that the observer does not have to interactively position the star in the selected aperture to make the pointing observation. In this case the telescope is set blind on the object, the position of the object is determined in the instrument focal plane coordinates <x, y> and the appropriate data calculated without any further telescope movement. If one or more numeric parameters aux1, aux2, aux3 is present, those values are used for the auxiliary data values; those not supplied are obtained from the database32.

Standard Response Upon successful return, the following message is output: [TPOBSVN] Observation # nnnn appended to pointing data file If the system could not write to the file, the following message is output: [TPFWRERR] System error: could not write to pointing data file If the telescope was not tracking at the time the command was issued, the following message is output: [TELNOTRACK] Telescope is not tracking; no pointing data recorded If there was no pointing data file open, the following message is output: [TPFNOTOPEN] No pointing data file open tpopen file-name (priv=engineering) Synopsis tpopen [file-name] [append] Description Opens a sequential text file in the telescope data area for recording pointing observation data. All such tpdata files have the extension .dat .

Parameters The parameter file-name gives the name of the required pointing data file. If it is an absolute path specification (ie has a leading /), it is implemented exactly as given; otherwise it is located with respect to the TCS environment variable MSOTCS_DATA which will normally point to the directory /home/telescope/data. The extension .dat is automatically appended to the filename. If the filename parameter is omitted completely, the system generates a file in the MSOTCS_DATA directory with a name of the form FOCUSyrmondd.dat (so that the focal station and date is encoded in the file name). If a pointing data file is already open, a message giving the full pathname of the currently open file together with the number of pointing observations is issued. If the keyword append is present, then the message[TPFEXISTS] is suppressed and an existing file of that name is found and opened in append mode so that further observations can be added 33. When the tpdata file is created, a header is written to the file comprising four comment records, a caption record, an option record and a run-parameters record thus: ! ! RSAA SSO 2.3metre Pointing Data Observation (TPDATA) file filename date 30 At this stage there is no projected use of these auxiliary data for the 2.3m telescope. 31 The A&G system must be accurately calibrated. The exposure parameters given to the autoguider are those set for the current guide object. 32 Note that TCSpk provides for three auxiliary parameters but the TPOINT manual mentions only two. The TPOINT analysis package does not read aux3. 33 This facility is provided to enable re-opening a file which has been inadvertently closed; pointing observations from different times or runs cannot be sensibly combined without appropriate processing; see the TPOINT manual.


! TPOINT analysis package INDAT format #4 ! RSAA 2.3metre alt-az; focus = focal-station aperture = aper_name UT = date & time : ALTAZ Ldeg Lmin Lsec Year Month Day temperature pressure height RH wavelength TLR where the run-parameters record contains the following quantities: Ldeg Lmin Lsec are degree, arcmin, arcsec fields derived from the site latitude, Year, Month, Day are the UTC date, temperature is the outside air temperature in Celsius, pressure is the atmospheric pressure in hPa, height is observatory height AMSL in metres, RH is the fractional relative humidity, wavelength is the reference wavelength34 in micron, and TLR is the tropospheric lapse rate (= .0065 °K/m). Note that each of the records is a maximum of 80 characters in length.

Standard Response Upon successful return, the following message is output: [TPFOPENED] File filename has been opened for pointing data If an existing pointing data file is open, the following message is output: [TPFCOUNT] Pointing data file filename open; nnnn observations recorded If a file with the name supplied already exists, the following message is output: [TPFEXISTS] A file of that name already exists; command ignored When the system cannot open the new file, the following message is output: [TPFOPERR] System error: pointing data file could not be created

1.4 Motion Control & Tracking Commands aoffset offsets the aperture or pointing origin aperture selects or defines an aperture (pointing origin) in the focal plane beam selects a predefined position on the sky guide turns autoguiding on or off; sets autoguiding configuration variables halt halts azimuth, altitude and rotator motion horizon drives the telescope to the horizon limit offset offsets the telescope on the celestial sphere park drives the telescopein azimuth and altitudet to the park position rate drives the telescope to the zenith position rotator sets the rotator reference angle or rotator configuration variables slew drives the telescope to a fixed position in azimuth and altitude servo stow drives the telescope to the stow position for top-end removal etc track acquires and tracks a celestial object zenith drives the telescope to the zenith aoffset (priv=observer) Synopsis aoffset ∆x ∆y [units] [base] [wait] aoffset [show] Description Offsets the image of the celestial object in the instrument focal plane35. The telescope tracking coordinates are not changed; the image is moved in the focal plane. Strictly speaking, the offsets are linear distances in the instrument

34 We use the autoguider wavelength for input to TPOINT since it is most common to use the A&G system for pointing data capture. 35 The instrument focal plane rotates with the instrument rotator; the direction +y is called the instrument fiducial.


focal plane36 but the qualifier units permits them to be specified in angular units. The offsets can be applied with respect to the focal plane origin (rotator centre), or may be applied incrementally to the current pointing origin. An aoffset command would normally be issued after the telescope is already tracking an object and takes effect immediately. Note that a track command normally sets focal plane offsets to zero but this action may be overridden: if the qualifier offset is appended to the track command, the existing focal plane offsets are retained and applied when imaging the new source coordinates.

Parameters The parameters ∆x and ∆y must be valid numeric quantities representing offsets ∆x and ∆y in the instrument focal plane directions x and y. Both must appear. Optional qualifiers may follow the numeric quantities in any order as described below. An optional qualifier units may appear; this may take the values arcsec, radian or mm and specifies the offset units: if arcsec appears, the offsets are interpreted as angles in arcseconds; if radian or rad appears, the offsets are interpreted as angles in radian; if mm appears, the offsets are taken to be tangent plane distances in millimetres and are applied by normalising them to the focal length of the telescope. If the qualifier is absent, it defaults to arcsec. If the qualifier base appears, the offsets are applied to the focal plane origin or rotator centre; if it is absent, the offsets are applied to the pointing origin and so consecutive aoffset commands are cumulative in their effect. If the qualifier wait is present in the command line, control is withheld from the observer until the image has acquired the new position. If not present, control is returned immediately the command is accepted, leaving the telescope in motion. The qualifier show (or the bare command aoffset without any other fields) causes the system to report the current values of the accumulated offsets from the rotator centre. The telescope is not moved.

Standard Response As soon as the command is accepted, the following string is output: [AOFFSET] Focal plane offset entered xxx.xx, yyy.yy; total IFP offsets X xxx.xx, Y yyy.yy (arcsec) If either ∆x or ∆y is not a valid numeric, the following string is output: [ERRINOFFST] Invalid offset supplied; command ignored If one of ∆x or ∆y is missing, the following string is output: [NEEDBOTHOF] Both coordinate offsets must be specified If an unrecognized qualifier is present, the following string is output: [INVPARAM] Invalid command line parameter; command ignored If the telescope is not tracking, the following string is output: [NOTYETRACK] CAUTION: telescope is not yet tracking; offset/rate may not be applied If the parameter show was present or implicit, the following string is output: [AOFFSTDATA] Current focal plane offsets xxx.xx, yyy.yy; current pointing origin

X xxx.xx, Y yyy.y (arcsec) aperture (priv = observer) Synopsis aperture aper-name [wait] aperture show 36 The offsets are projection plane distances and the conversion from "arcseconds" or "radians" to units of focal length has geometric validity only close to the rotator centre. Because the equivalent angles are small, this is of no practical consequence.


aperture Description Selects an aperture or pointing-origin in the instrument focal plane from the current aperture table. The aperture table may contain up to 16 distinct pointing-origins accessed by name; one of these is reserved by the system for the rotator centre and designated aperture "0". Each of the focal stations has its own aperture table which is usually populated by means of the user's configuration file. The aperture selection takes effect immediately and affects the current and all subsequent tracking operations; the telescope is moved so that the celestial object (tracking coordinates) is imaged at the position of the selected aperture in the focal plane. Selecting an aperture 37 clears any focal plane offsets previously entered using the aoffset command. Upon telescope system startup, aperture "0" is automatically selected. Note that, depending on the rotator configuration, selection of a different aperture may result in a change of the instrument alignment angle and consequently rotator motion38. Other forms of the command permit the creation or deletion of apertures as described below.

Parameters The aperture name aper-name may be up to 16 characters in length and is not case-sensitive39. If the flag wait is present, control is returned to the user only after any movement has finished and the telescope axes and rotator are tracking with the new pointing origin (and new rotator angle) established. If there no parameters supplied, the command aperture simply reports the currently selected aperture. If the parameter show is present, no change of aperture ocurrs but the command lists the current entries in the aperture table.

Standard Response As soon as the command is accepted, the following string is output: [APERSEL] New aperture (pointing-origin) aper-name selected If the command was submitted without any parameters, the following string is output: [CURRAPER] The currently selected aperture is aper-name If the parameter show was present, the following aperture table list is output: [APERDATA] Currently defined apertures for focal_station \n aperture xa(arcsec) ya(arcsec) iaa (deg) \n 0 0.0 0.0 0.0 \n aper1 xxx.xx yyy.yy ddd.dd \n .. .. apern xxx.xx yyy.yy ddd.dd \n *** aperture aper is currently selected *** If there are fields present other than the aperture name and wait, the following string is output: [INVPARAM] Invalid command line parameter; command ignored If the supplied aperture name is disallowed or contains illegal characters, the following string is output: [XAPERNAME] Supplied aperture name is not legal; command ignored If the named aperture was not found in the aperture table, the following string is output: [APNOTDEF] Nominated aperture is not defined

aperture define (priv = observer) Synopsis aperture define aper-name xa ya [iaa] 37 Reselecting the currently selected aperture also clears focal plane offsets. 38 When the configuration variable iaa_source is set to APER, the instrument alignment angle is set to the iaa value of the currently selected aperture and consequently may change with selection of a different aperture. 39 Internally MSOTCS handles apertures using a numerical index but the aperture table may be sparsely populated and the user does not see any index values.


aperture define aper-name here Description Defines an aperture (pointing-origin) in the instrument focal plane and places it in the current aperture table. The aperture is specified by its cartesian coordinates xa , ya in the focal plane and an optional instrument alignment angle iaa. The command aperture define aper-name here may be used to define an aperture at the current position of the optic axis in the focal plane (ie at the current position of a star in the field).

Parameters The qualifier define must appear as the first field. The aperture name aper-name may be any string of up to 16 standard printable characters; the case of the characters in the string is preserved in the aperture table but ignored when seeking a match for the purpose of aperture selection or deletion. The aperture coordinates xa and ya must be valid numerical quantities and must both be present. They represent the aperture position in a tangent plane projection whose tangent point is the rotator centre40. Consequently they are linear measure but are specified in arcseconds for convenience. See chapter 1 for a discussion of this. The instrument alignment angle iaa is optional and is usually needed only if the aperture relates to a slit41. It is specified in degrees in the range [0, 360). If it is not supplied, it defaults to zero. Where the qualifier here appears instead of an aperture specification, the aperture is defined by the current focal plane position of the object. For this latter variant of the command to be meaningful, the observer must have positioned the star in a previously calibrated aperture and issued a calibrate pointing or track zero command to zero the accumulated offsets before moving the star to the new aperture position. Apertures (pointing origins) can only be defined for the currently selected focal station; once aperture specifications have been determined, they are best incorporated into suitable configuration files.

Standard Response If the command is successful, the following string is output: [APERDEF] Aperture aper-name defined at xa = xxx.xx ya = yyy.yy iaa = ddd.dd If there are too many fields or too few valid numeric fields, the following string is output: [ERRINAPER] Aperture specification is invalid; command ignored If the supplied value for iaa is out of range, the following string is output: [IAARANGE] Supplied instrument alignment angle (IAA) is out of range If the aperture table is full, the following string is output: [EXMAXAPER] Insufficient room in aperture table; attempt to define further apertures ignored If the supplied aperture name is disallowed or contains illegal characters, the following string is output: [XAPERNAME] Supplied aperture name is not legal; command ignored If an attempt was made to redefine aperture 0, the following string is output: [RESAPNAME] Reserved aperture name; attempt to redefine or delete aperture 0

ignored

aperture clear (priv = observer) Synopsis aperture clear aper-name

40 The <x, y> focal plane system appears right-handed when facing the instrument rotator and looking at a ground-glass screen; the y-axis points along the instrument fiducial. See chapter 1. 41 The instrument alignment angle is measured (facing the instrument rotator) clockwise from the instrument fiduciary to the instrument principal direction.


aperture clear all Description Deletes an individual aperture from the current aperture table. The command aperture clear all is used to clear out the entire aperture table. As a precaution, it begins by searching the aperture table for an aperture named all and, if that exists, it alone is deleted. Only if there is no such aperture does the command proceed to clear the entire table42. The aperture defining the rotator centre (aperture "0") cannot be cleared. The command operates only upon the aperture table entries; if the currently selected aperture is cleared, the telescope will keep tracking normally until the next track command is implemented.

Parameters The qualifier clear must appear as the first field. The parameter aper-name may be any string of up to 16 standard printable characters; the case is ignored when seeking a match for the purpose of aperture deletion. It may be replaced by the keyword all which, unless there is an aperture named all, results in the clearing of the entire aperture table.

Standard Response If the command is successful in clearing an individual aperture, the following string is output: [APERCLEAR] Aperture aper-name cleared If the command is successful in clearing the entire aperture table, the following string is output: [APERTABCLR] All entries cleared from aperture table If there are fields present other than the allowed keywords and the aperture name, the following string is output: [INVPARAM] Invalid command line parameter; command ignored If the named aperture was not found in the aperture table, the following string is output: [APNOTDEF] Nominated aperture is not defined If the supplied aperture name is disallowed or contains illegal characters, the following string is output: [XAPERNAME] Supplied aperture name is not legal; command ignored If an attempt was made to clear aperture 0, the following string is output: [RESAPNAME] Reserved aperture name; attempt to redefine or delete aperture 0

ignored

beam (priv = observer) Synopsis beam A|B|C [guide|noguide] [wait] beam show beam Description Selects one of three predefined beams on the sky. A beam is characterised by the celestial coordinates of its centre and optionally those of an associated guide object. The telescope is driven so that the beam centre coordinates become imaged at the currently selected aperture and the autoguiding system is instructed to guide using the guide object associated with the beam. A track command (as distinct from another beam command) will deselect all of the beams. Other forms of the command permit the definition of beams as described below.

Parameters For the beam selection command, the beam name must be one of A, B or C and must appear; it is not case sensitive.

42 Observers are advised to refrain from naming apertures show, here, define, clear or all since some aperture commands may not function in the manner intended.


The behaviour of the autoguider depends upon the optional qualifier guide or noguide: if guide appears, the autoguider is instructed to commence guiding with the new reference position (new guide object) associated with the beam; if noguide appears, guiding is turned off (even if a valid guide object is defined for the beam in question). If the qualifier is omitted, it defaults to noguide. If the flag wait is present, control is returned to the user only after any telescope movement has finished and the axes and rotator are tracking with the new coordinates (and new rotator angle) established. If the parameter show is present, all other parameters are ignored and the command lists the current beam definitions in the beam table. No change of beam ocurrs and the telescope is not moved. If there no parameters supplied, the command beam simply reports the currently selected beam.

Standard Response As soon as the command is accepted, one of the following strings is output: [BEAMSEL] Beam X selected; guider enabled [BEAMSELNOG] Beam X selected If extraneous fields are present, the following string is output: [INVPARAM] Invalid command line parameter; command ignored If the beam name is other than A, B or C, the following string is output: [XBEAMNAME] Supplied beam name is not legal; command ignored If the nominated beam was not defined, the following string is output: [BEAMNOTDEF] Nominated beam is not defined If the qualifier guide was present but no guide object is defined for that beam, the following string is output: [NOGUIDEOBJ] No guide object is defined; guiding not commenced If the qualifier guide was present but no guider has registered with the TCS, the following string is output: [GUIDRNOREG] No guider is registered or has control; guiding not commenced If the command was submitted without any parameters, the following string is output: [CURRBEAM] The currently selected beam is selected_beam If the parameter show was present, the following beam table list is output: [BEAMDATA] Currently defined beams for focal_station \n beam A: RA = hh:mm:ss.sss DEC = ±dd mm ss.ss EQNX = J2000.0 \n (guide) RA = hh:mm:ss.sss DEC = ±dd mm ss.ss EQNX = APPT \n exp-time = nnnnnnn(msec) window = xxx(pix) binning = 2 \n \n beam B: RA = hh:mm:ss.sss DEC = ±dd mm ss.ss EQNX = B1965.5 \n (guide) no guide object defined \n \n \n beam C: not defined \n \n \n *** beam X is currently selected *** Note that a successfull beam command effectively initiates track coordinate and (possibly) guide on commands; these may in turn precipitate such messages as: [ACQUIRING], [TRACKING] or [PRECLUDE]. beam define (priv = observer) Synopsis beam define A|B|C coord-spec [guide coord-specg expose time win bin] beam define A|B|C offset ∆ra ∆dec [guide ∆rag ∆decg expose time win bin] Description


Defines a beam on the celestial sphere and places it in the current beam table. The beam may be specified by the celestial coordinates of its centre or by its offsets43 from the position of beam A. A guide object may be optionally associated with the beam by including its specifications together with A&G camera control parameters needed for guiding. This is facilitated by the inclusion of keywords guide and expose. The default configuration file (invoked at startup) does not have any beams defined but beam definitions may be included in a user supplied configuration file44. Beam definition can also be performed using the configure command.

Parameters The qualifier define must appear as the first field. The beam name A, B or C must follow as the second field; it is not case sensitive. Beam definition by coordinates The mode in which the celestial positions are defined (coordinate or offset) is determined by the qualifier offset which, if it is present, must follow immediately after the beam name. If it is omitted, the subsequent fields until the qualifier guide or the end-of-record (whichever is first) are interpreted as a celestial coordinate specification conforming to the specifications in chapter 1. This represents the FK4 or FK5 mean place or the apparent place of the beam centre and (for practical reasons) will usually be just the RA, declination and (possibly) equinox fields45. The RSAA coordinate specification format is described briefly in the track coordinate command below. The keyword guide is used to associate a guide object and camera control data with the beam. The fields immediately following guide and before the keyword expose are interpreted as a coordinate specification for the guide object; again they are most likely just the RA, declination and (possibly) equinox fields. The keyword expose delineates the camera control data which comprise: time the exposure time in milliseconds; win the guide window46 size in pixels; and bin the camera binning factor in both the xp and yp directions. The three quantities must appear in the order given and must be valid numerics. If no guide object is to be defined, the keyword guide and all of the guiding specification fields (those following guide) may be omitted. For a valid guide object definition, all these fields must be present in the order shown. Beam definition by offsets If the qualifier offset appears immediately after the beam name, the celestial positions are assumed to be defined by tangent plane offsets with respect to the position and guide object for beam A. Clearly only beams B and C can be defined in this manner. The command syntax is similar to that of coordinate definition mode above but with offset quantities defined as follows: ∆ra and ∆dec specify the offsets in the east and north directions from the beam A centre; ∆rag and ∆decg specify the offsets in the east and north directions from the beam A guide object; the units are arcseconds. Note that these are really tangent plane coordinates ξ , η and not offsets in the raw coordinate variables.

Standard Response If the command is successful, one of the following strings is output: [BEAMDEF] Beam X has been defined [BEAMDEFNOG] Beam X has been defined; no guide object was specified If the beam name is other than A, B or C, the following string is output: [XBEAMNAME] Supplied beam name is not allowed; command ignored If the qualifier offset is present but is not followed by exactly two valid numeric fields, the following string is output: [BEAMOFFSET] Offset specification for beam or guide object is invalid

43 If the offset mode of beam specification is used, then both the beam centre and the guide object are defined by their respective offsets; definitions which employ mixed mode are not supported. 44 The user configuration file may contain a separate beam specification for each of the telescope foci. 45 As for all source coordinate specifications, if the equinox field is omitted, the coordinate system defaults to the user's default_coord_system configuration setting. 46 The guide window is assumed to be a square of side win pixels.


If the coordinate data for either the beam or the guide object is in error, one of a number of strings is output: [NORA] No right ascension coordinate has been supplied [NODEC] No declination coordinate has been supplied [ERRINRA] Error in right ascension coordinate supplied [ERRINDEC] Error in declination coordinate supplied [INVEPOCH] Invalid equinox or epoch string [ERRINEQX] Error in coordinate system (equinox or epoch) supplied [ERRINMURA] Error in proper motion in right ascension [ERRINMUDEC] Error in proper motion in declination [NOMUDEC] Proper motion in declination appears to be missing: u_DEC must appear if u_RA is specified [TOOMANQUO] Object name wrongly delimited: too many characters " or = are present If the offsets specifying the guide object are not valid numeric fields or are not both present, the following string is output: [BEAMOFFSET] Offset specification for beam or guide object is invalid If the keyword guide is present but keyword expose is missing or misplaced, the following string is output: [NEEDEXPOSE] "Expose" parameters must be present in guide specification; command ignored If the keyword guide is present but the ensuing fields do not comply with the required syntax, the following string is output: [ERRINGUIDE] Guide object specification is invalid; command ignored If the supplied value for time is not a valid numeric or is ≤ 0, the following string is output: [XTIMRANGE] Supplied exposure time is invalid or out of range If the supplied value for win is not a valid numeric or is ≤ 0, the following string is output: [WINRANGE] Supplied guide window size is invalid or out of range If the supplied value for bin is not a valid numeric or is ≤ 0, the following string is output: [BINRANGE] Supplied binning factor is invalid or out of range

beam clear (priv = observer) Synopsis beam clear A|B|C beam clear all Description Deletes an individual beam from the current beam table. (The beam_defined flag for that beam is set to FALSE.) The command beam clear all is used to clear out the entire beam table. The command operates only upon the beam table entries; if the currently selected beam is cleared, the telescope will keep tracking normally until the next track command is implemented.

Parameters The qualifier clear must appear as the first field. The beam name A, B or C must follow as the second field; it is not case sensitive. It may be replaced by the keyword all which results in the clearing of all three beams.

Standard Response If the command is successful in clearing an individual aperture, the following string is output: [BEAMCLEAR] Beam X cleared If the command is successful in clearing the entire beam table, the following string is output: [BEAMTABCLR] All beams cleared If the beam name is other than A, B or C, the following string is output: [XBEAMNAME] Supplied beam name is not allowed; command ignored If there are fields present other than the allowed keywords and the aperture name, the following string is output: [INVPARAM] Invalid command line parameter; command ignored


guide (priv=observer) Synopsis guide coord coord-spec [on] guide n [on] guide previous|next [n] [on] guide [name] object-name [on] guide on guide off Description Defines a guide object to be used for closed-loop control of the telescope tracking. The guide object is defined by its celestial coordinates or by an index or object name in the currently selected guide coordinate file. Other forms of the command allow guiding to be turned on or off. (For guider configuration see the following command description.)

Parameters Defining a guide object by celestial coordinate specification When the primary qualifier coord is present, the following fields must contain a valid celestial coordinate specification coord-spec conforming to chapter 1. In practice these fields will usually be just the RA, declination and (possibly) equinox fields47. The RSAA equatorial coordinate specification format is described briefly in the track coordinate command below. The coordinate specification incurs a one-time conversion to the guide object position in the tracking coordinate system when guiding is commenced. Selecting a guide object from a guide coordinate file A command of the form guide n sets the guide object to the nth entry in the currently selected guide coordinate file. This form of the command is assumed whenever there is no primary qualifier and the first field is a numeric. The parameter n is interpreted as a decimal integer index to the coordinate file. n must be positive and the first entry of the file is numbered 1. If the primary qualifier previous or next appears, the object is located relative to the last object used in the guide coordinate file. The parameter n is interpreted as an offset from the current guide coordinate file entry and must be a positive decimal integer. Specific instances of the command are: guide previous selects the object prior to the current one in the guide coordinate file, guide previous n selects the (current – n)th object in the guide coordinate file, guide next selects the object after the current one in the guide coordinate file guide next n selects the (current + n)th object in the guide coordinate file. A guide object may be selected by name. The current guide coordinate file is searched for an object whose name matches the supplied string object-name. The object name search is case insensitive and all instances of multiple white-space are collapsed to a single space character in both the template object-name and in the file records before seeking a match. Normally no primary qualifier is required. However, an object name which commences with a numeric will be interpreted as an index to the file. The qualifier name is used to force the system to accept a numeric or similar string as an object name. Starting and stopping guiding The discrete qualifiers on and off enable the observer to start and stop the guiding action from the TCS system; the commands guide on and guide off cause requests to be sent to the A&G system to (re)commence or terminate guiding respectively. If it is desired that guiding commence immediately the guide object is selected, then the keyword on may be appended to the first four of the guide commands given above. The keyword on must be the last field; it must not be inserted in either the coordinate specification or file index data. A guide object may be defined at any time: if the telescope is tracking at the time the command is issued, the guider has immediate access to the new reference position; if it is not tracking, the guide object information will be stored in the database 47 As for all source coordinate specifications, if the equinox field is omitted, the coordinate system defaults to the user's default_coord_system configuration setting.


and will take effect when the next track command (and guide on) command is issued. If the command is used to define a guide object whilst tracking a beam, the new guide object takes effect immediately but only for the duration of the beam command; the new guide object definition does not replace the guide data stored as part of the beam definition.

Standard Response If the guide object definition command is successful, the following string is output: [GUIDEDEF] Guide object defined name RA= hh:mm:ss.s DEC= ±dd:mm:ss.ss Cosys= eqnx If the coordinate specification data for the guide object is in error, one of a number of strings is output: [NORA] No right ascension coordinate has been supplied [NODEC] No declination coordinate has been supplied [ERRINRA] Error in right ascension coordinate supplied [ERRINDEC] Error in declination coordinate supplied [INVEPOCH] Invalid equinox or epoch string [ERRINEQX] Error in coordinate system (equinox or epoch) supplied [ERRINMURA] Error in proper motion in right ascension [ERRINMUDEC] Error in proper motion in declination [NOMUDEC] Proper motion in declination appears to be missing: u_DEC must appear if u_RA is specified [TOOMANQUO] Object name wrongly delimited: too many characters " or = are present When the command refers to a file object but there is no coordinate file selected, the following string is output: [NOCOOGFILE] No coordinate file currently selected; use guide file command If there was an error opening or reading the coordinate file, the following string is output: [COORFILERR] Error opening or reading selected coordinate file filename If the file index supplied is less than 1, the following string is output: [COORFINDEX] Coordinate file index or offset must be greater than zero; command ignored If the index exceeds the number of coordinate records in the file, the following string is output: [COORFILEOF] Coordinate file index out of range; EOF encountered If the named object could not be found in the file, the following string is output: [OBJNOFIND] Coordinate object object-name not found If in general the fields do not comply with the required syntax, the following string is output: [ERRINGUIDE] Guide object specification is invalid; command ignored If the guide on command is successful, the following string is output: [GUIDING] Guiding enabled If the guide off command is successful, the following string is output: [GUIDEOFF] Guiding disabled If the A&G system did not respond to a guide on or guide off command, the following string is output: [AGCONFAIL] Timeout - Autoguider failed to respond to control request

guide (autoguider configuration) (priv=observer) Synopsis guide file file-spec guide expose time win bin guide free|fixstage|fixpixref guide [show] Description This group of commands configures information needed by the autoguiding action such as, guide coordinate file, A&G camera control parameters, the ag_constraint flag, or lists the current guide object and guider state. Other forms of the command allow the guide object to be set or guiding to be turned on or off; these are described in the preceding section.

Parameters The first field must contain one of the qualifiers file, expose, free, fixstage, fixpixref or show.


If the primary qualifier file is present, the command selects a coordinate file to be used for guide objects. The file selected is accessed by all subsequent guide commands of the form guide index, guide next, guide previous and guide name. The parameter file-spec indicates the required coordinate file. If file-spec commences with a leading / character, it is interpreted as a complete path specification and referenced in its entirety; otherwise it is assumed to be only the filename and is prepended with the default data directory so that the file specification becomes $MSOTCS_DATA.file-spec. In both cases, the command attempts to open the file; if the file is not found with the filename/file specification supplied, the suffix .coord is appended and the file open retried. The guide coordinate file stays selected until countermanded by another guide file file-spec command; the coordinate file used for science objects and that for guiding may be one and the same file. The primary qualifier expose configures the camera control data which comprise: time the exposure time in milliseconds; win the guide window48 size in pixels; and bin the camera binning factor in both the xp and yp directions. The three quantities must appear in the order given and must be valid numerics. If fewer than three numeric fields are present, the ones supplied are deemed to apply in the order shown; the omitted parameter(s) retain their current settings. This form of the command must preceed any guide on command49 in order for the camera control data to be valid for the ensuing exposure. The mutually exclusive qualifiers free, fixstage or fixpixref are used to set the value of the database flag ag_constraint; this determines the constraints to which the guider is subject in driving the A&G camera stage and choosing its pixel reference when the TCS issues a new guider reference position. If free is present, the A&G system is free to move both stage and pixel reference to achieve the guider reference position; if fixstage is present, the stage must not be moved and consequently the pixel reference must be changed; if fixpixref is present, the pixel reference must remain fixed and only the stage moved. If the qualifier show is present or if the command is entered without any parameters, the current guide object and guider state are reported50 leaving them unchanged.

Standard Response If the guide file command is successfull, the following string is output: [COORFILSEL] Coordinate file file-spec selected If the command to set the camera control parameters is successful, the following string is output: [EXPOSESET] Autoguider camera set to exp-time xxxxx (millisec) window www binning bb (pixels) If the command to set the ag_constraint flag is successful, the following string is output: [AGFIXSET] Autoguider constraint set to free|fixstage|fixpixref If no file-spec field was supplied, the following string is output: [MISFILSPEC] Missing file specification; command ignored If the file-spec field was not a valid QNX file specification, the following string is output: [INVFILSPEC] Invalid file specification; command ignored If the specified file (with or without the extension .coord) cannot be found, the following string is output: [MISCOORFIL] Coordinate file file-spec missing or cannot be opened If the supplied value for time is not a valid numeric or is ≤ 0, the following string is output: [XTIMRANGE] Supplied exposure time is invalid or out of range If the supplied value for win is not a valid numeric or is ≤ 0, the following string is output: [WINRANGE] Supplied guide window size is invalid or out of range If the supplied value for bin is not a valid numeric or is ≤ 0, the following string is output: [BINRANGE] Supplied binning factor is invalid or out of range

48 The guide window is assumed to be a square of side win pixels. 49 The guide expose... command is not needed where guiding on/off is controlled solely from the A&G system; in this case the A&G will set the camera control parameters itself without regard to data received from the TCS. 50 Note that this may be the guide object defined by the currently selected beam and not the last one entered by the guide command.


If more than one of the keywords free, fixstage or fixpixref are present, the following string is output: [MUTEXPARAM] Parameters encountered in command string are mutually exclusive If additional fields occur in conjunction with one of the keywords free, fixstage or fixpixref, the following string is output: [UNXPARAM] Unexpected or unrecognized parameter encountered in command string If the qualifier show is present or if the command is entered without any parameters, the following string is output: [GUIDEDATA] Current guide object is: \n RA = hh:mm:ss.sss DEC = ±dd mm ss.ss EQNX = APPT \n exp-time = nnnnnnn(msec) window = xxx(pix) binning = 2 \n guider reference position xref = xxx.xx yref = yyy.yy \n guider mode = CLEAR_FIELD \n guider status = GUIDING TCS-guider loop = open \n guide rate (priv=observer) Synopsis guide rate radt decdt [arcsec|ra_time|radian] [sec|min|hour|day] guide rate Description Sets up differential tracking rates in the celestial coordinates right ascension and declination for the guide object. The rates are applied in the current tracking coordinate system51 and to the current guide "base" position. A guide rate command must be issued after the associated command guide (which establishes the guide object base coordinates) to ensure that the rates take effect; a subsequent guide command will clear any guide rates which have been set . If the command is used to set a guide rate whilst tracking a beam, the new guide rate takes effect immediately but only for the duration of the beam command; the new guide rate definition does not replace any guide data stored as part of the beam definition.

Parameters The parameters radt and decdt must be valid numeric quantities representing the angular time derivatives. Both must appear. An optional qualifier specifying the angular units may follow the numeric quantities: if arcsec appears, the angular unit is arcseconds for both coordinates; if ra_time appears, the angular unit is seconds-of-time for right ascension and arcseconds for declination; if radian or rad appears, the angular unit is radian for both coordinates. If the qualifier is absent, the angular units default to arcseconds. An optional qualifier specifying the time unit may follow the numeric quantities: if sec appears, the unit of time is per second; if min, per minute; if hour, per hour; if day, per day. If the qualifier is absent, the unit of time defaults to per second. The qualifier wait is accepted in the command line but is not acted upon. If no qualifiers appear the rates in both coordinates are interpreted in units of arcsecond/second. The command guide rate alone (without any parameters or qualifiers) simply re-establishes the rates for the guide object which were last entered.

Standard Response As soon as the command is accepted, the following string is output: [GUIDERATE] Differential rates applied to guide object RA ±xxxx.xxxx, DEC ±yyyy.yyyy (arcsec/sec) If either radt or decdt is not a valid numeric, the following string is output: [ERRINRATE] Invalid rate supplied; command ignored

51 The rates apply to the coordinate angles as distinct from local coordinates in the projection plane. MSOTCS does not support rates in coordinate directions other than in the tracking coordinate axes; this feature of the existing VAX/VMS TCS has been abandoned because it was not implemented rigorously and was confusing to use.


If one of radt or decdt is missing, the following string is output: [NEEDBOTH] Both RA and dec rates must be specified If an unrecognized qualifier is present, the following string is output: [INVPARAM] Invalid command line parameter; command ignored If conflicting qualifiers are present, the following string is output: [MUTEXPARAM] Parameters encountered in command string are mutually exclusive halt (priv = observer) Synopsis halt Description Decelerates the telescope axes and rotator servomechanisms to zero speed, interrupting any other motion which was requested. The command takes effect immediately and is always "successful"; actual motion may persist for a short while after it is issued. The telescope is left in the motion state STATIONARY. Because the building rotation drive and windscreens are slaved to the telescope mount, they also will cease moving, but mechanisms such as the focuser and primary mirror cover will continue any motion which they have commenced 52. The 2.3m TCS does not test whether a servomechanism fails to stop; however the control system will electrically trip a servo which exceeds its outer limits; this will create a hard fault requiring a reset or other user intervention. This command pre-empts any other motion control command even if that command has the wait qualifier appended. Control is returned to the user only after all three servo demands have decayed to zero, which (unless there is a serious hardware fault) means that the telescope and rotator are stationary.

Parameters None required. (The qualifier wait is implicit; control is returned to the user only after the telescope and rotator are stationary.)

Standard Response As soon as the command is accepted, the following string is output: [HALTING] Halting telescope axes and rotator... When the motion of all servos has come to a standstill, the motion state is set to STATIONARY and the following string is output: [HALTED] Telescope now stationary at azimuth = aaaaa.aaaa, altitude = aaaa.aaaa horizon (priv = observer) Synopsis horizon [wait] Description Slews the telescope in altitude to the horizon limit53; the azimuth axis, instrument rotator and building are not moved. Normally control is returned immediately leaving the telescope in motion. The telescope is left in the motion state STATIONARY.

Parameters If the qualifier wait is present, control is returned to the user only after the altitude motion has ceased and the telescope is stationary at the horizon limit.

Standard Response As soon as the command is accepted, the following string is output: [SLEWINGH] Slewing telescope to horizon limit...

52 The 2.3m control circuitry does not provide for the computer to arbitrarily halt the primary mirror cover or the tertiary mirror drive except by means of the computer-activated trip signal; this would generate an emergency stop situation which could not be reset from the computer. The focuser is completely enclosed and, in any case, can be halted using the focus halt command 53 The horizon limit is set by the database parameter alt_horizon_limit.


If an axis servo fault exists the following string is output: [PRECLUDE] Telescope fault precludes proper control of motion If the qualifier wait is present, then the following string is output after the motion has successfully completed: [HALTEDH] Telescope now stationary at horizon limit offset (priv=observer) Synopsis offset ∆x ∆y [coordinates] [units] [base] [wait] offset stepsize step-size offset [show] Description Offsets the telescope on the celestial sphere. The telescope tracking coordinates are changed appropriately. The angular units of the discrete offsets, and the coordinate system in which they are applied are determined by the qualifiers coordinates and units. The offsets can be applied with respect to the telescope base position, or may be applied incrementally to the current tracking position. An offset command is normally issued after the telescope is already tracking an object and takes effect immediately. A track command normally sets the observer specified offsets to zero but this action may be overridden: if the qualifier offset is appended to the track command, the existing offsets are retained and applied to the new source coordinates.

Parameters The parameters ∆x and ∆y must be valid numeric quantities representing angular offsets in an orthogonal coordinate system. Both must appear. Optional qualifiers may follow the numeric quantities in any order as described below. An optional qualifier coordinates may appear; this may take the values coord, radec, altaz, xy, tv, slit or ipd and specifies the coordinate directions in which the offsets are applied54: if radec appears, the offsets are applied in right ascension and declination; if azalt appears, the offsets are applied in topocentric azimuth and altitude; if xy appears, the offsets are applied in the instrument focal plane55 directions x and y; if tv appears, the offsets are applied in the instrument focal plane and oriented so that ∆x and ∆y coincide with observer's view of the acquistion display; slit or ipd are synonyms, if either appear, the offsets are in the instrument focal plane and oriented so that the offset ∆x lies in the positive direction of the instrument principal direction56. For all the above cases, the offsets are taken to be orthogonal movements in the tangent plane57. If the qualifier has the value coord, the offsets are applied directly to the right ascension and declination angles (ie. the angular coordinates are augmented by exactly the offset values); If the coordinates qualifier is absent, it defaults to radec. An optional qualifier units may appear; this may take the values ra_time, arcsec or radian and specifies the angular units: if ra_time appears, the angular unit is seconds-of-time for right ascension but arcseconds for declination; if arcsec appears, the angular unit is arcseconds for both coordinates; if radian or rad appears, the angular unit is radian for both coordinates. If the qualifier is absent, it defaults to arcsec.

54 Note that no matter which coordinates option is specified, the movement is applied to the celestial position α, δ in the tracking coordinate system not to the pointing origin in the instrument focal plane. The transformations from the desired axes into the angles α and δ and the tangent-plane projection is calculated completely rigorously. 55 The instrument focal plane rotates with the instrument rotator; the direction +y is called the instrument fiducial. 56 This permits the +x, –x directions to correspond to up and down a spectrograph slit. 57 To first order approximation this means that an RA offset would be scaled by secδ before being added to the RA angle.


If the qualifier base appears, the offsets are applied to the telescope base position; if it is absent, the offsets are applied to the current tracking position and so consecutive offset commands are cumulative in their effect. If the qualifier wait is present in the command line, control is withheld from the observer until the telescope has acquired the new position. If not present, control is returned immediately the command is accepted, leaving the telescope in motion. If the qualifier stepsize appears as the first parameter field, the next field is taken to be the stepsize in units of arcseconds used by the console or handset rosette pushbuttons when they are in offset mode (as opposed to jog mode). This form of the command merely changes the value of a configuration variable and is functionally similar to the command configure offset_stepsize step-size. The telescope is not moved. The qualifier show (or the bare command offset without any other fields) causes the system to report the current values of the accumulated offsets from the base position. The telescope is not moved.

Standard Response As soon as the command is accepted, the following string is output: [OFFSET] Celestial offset entered ±xxx.xx, ±yyy.yy; tracking RA offset ±aaa.aa, DEC ±ddd.dd (arcsec) If the tracking coordinate system is set to AZEL_TOPO, the following string is output: [NOTAZEL] Tracking system is set to AZEL_TOPO; celestial offset command cannot be implemented If either ∆x or ∆y is not a valid numeric, the following string is output: [ERRINOFFST] Invalid offset supplied; command ignored If one of ∆x or ∆y is missing, the following string is output: [NEEDBOTHOF] Both coordinate offsets must be specified If an unrecognized qualifier is present, the following string is output: [INVPARAM] Invalid command line parameter; command ignored If conflicting qualifiers are present, the following string is output: [MUTEXPARAM] Parameters encountered in command string are mutually exclusive If the telescope is not tracking, the following string is output: [NOTYETRACK] CAUTION: telescope is not yet tracking; offset/rate may not be applied If the offset stepsize form of the command is successful, the following string is output: [OFFSTPSIZE] Offset step-size (for pushbuttons) set to xxx.xx (arcsec) If the parameter show was present or implied, the following string is output: [OFFSETDATA] Current accumulated offsets: RA ±aaa.aa, DEC ±ddd.dd, pushbutton step-size %step-size% (arcsec) park (priv = observer) Synopsis park [wait] Description Slews both axes of the telescope to the preset park position which is stored in the TCS database. The instrument rotator, focuser and other mechanisms are not moved. Because the 2.3m building is slaved to the azimuth axis, parking usually involves motion of the building. Normally control is returned immediately, leaving the telescope in motion.

Parameters If the qualifier wait is present, control is returned to the user only after the motion has ceased and the telescope is stationary at the park position.


Standard Response As soon as the command is accepted, the following string is output: [SLEWINGP] Slewing telescope to park position... If an axis servo fault exists the following string is output: [PRECLUDE] Telescope fault precludes proper control of motion If the qualifier wait is present, then the following string is output after the motion has successfully completed: [HALTEDP] Telescope now stationary at park position azimuth=233.8, altitude=89.0 rate (priv=observer) Synopsis rate radt decdt [arcsec|ra_time|radian] [sec|min|hour|day] rate Description Sets up differential tracking rates in the celestial coordinates right ascension and declination which are superimposed on the normal diurnal tracking rate. The rates are applied in the current tracking coordinate system58 and augment any rates set by a track ephemeris, track orbit or track planet command. A rate command is normally issued after the telescope is already tracking the object, in which case the rates take effect immediately. A track command normally sets the rates to zero but this action may be overridden: If the qualifier rate is appended to the track command, the predefined tracking rates are applied at the time at which the track rate command is accepted.

Parameters The parameters radt and decdt must be valid numeric quantities representing the angular time derivatives. Both must appear. An optional qualifier specifying the angular units may follow the numeric quantities: if arcsec appears, the angular unit is arcseconds for both coordinates; if ra_time appears, the angular unit is seconds-of-time for right ascension and arcseconds for declination; if radian or rad appears, the angular unit is radian for both coordinates. If the qualifier is absent, the angular units default to arcseconds. An optional qualifier specifying the time unit may follow the numeric quantities: if sec appears, the unit of time is per second; if min, per minute; if hour, per hour; if day, per day. If the qualifier is absent, the unit of time defaults to per second. The qualifier wait is accepted in the command line but is not acted upon. If no qualifiers appear the rates in both coodinates are interpreted in units of arcsecond/second. The command rate alone (without any parameters or qualifiers) simply re-establishes the tracking rates which were last entered.

Standard Response As soon as the command is accepted, the following string is output: [RATE] Differential tracking rates in RA ±xxxx.xxxx, DEC ±yyyy.yyyy (arcsec/sec) If either radt or decdt is not a valid numeric, the following string is output: [ERRINRATE] Invalid rate supplied; command ignored If one of radt or decdt is missing, the following string is output: [NEEDBOTH] Both RA and dec rates must be specified If an unrecognized qualifier is present, the following string is output: [INVPARAM] Invalid command line parameter; command ignored 58 The rates apply to the coordinate angles as distinct from local coordinates in the projection plane. MSOTCS does not support rates in coordinate directions other than in the tracking coordinate axes; this feature of the existing VAX/VMS TCS has been abandoned because it was not implemented rigorously and was confusing to use.


If conflicting qualifiers are present, the following string is output: [MUTEXPARAM] Parameters encountered in command string are mutually exclusive If the telescope is not tracking, the following string is output: [NOTYETRACK] CAUTION: telescope is not yet tracking; offset/rate may not be applied

rotator (priv=observer) Synopsis rotator θ [cw|ccw] [wait] rotator offset ∆θ [wait] rotator [show] Description The rotator command gives the observer control of the instrument rotator system and so facilitates the orientation of the focal plane field on the celestial sphere. The rotator is controlled by means of a reference angle θ which (depending on the mode) may be position angle, vertical angle or rotator angle59. A command of the form rotator θ drives the rotator so as to realize the value of the reference angle supplied and the observer has the option of forcing the rotator to drive in a specified direction to achieve that angle. Note that position angle and vertical angle are always entered and displayed in the range 0 to 360 degrees whereas the rotator angle ranges over the entire extended range of the mechanism (–1440 to +1440 degrees). Instead of supplying an absolute value for the reference angle, the rotator can be controlled by incremental offsets as in the command rotator offset ∆θ . The (necessarily) complex behaviour of the rotator is treated in chapter 1 of this manual but may be summarized thus: rotator not in use (rot_reference = NOT_IN_USE) In this mode the rotator is not controllable from the computer, neither by command nor the console/handset pushbuttons. However the computer still reads the encoder for the selected rotator, so the physical rotator position is available for display and is incorporated in the focal plane calculations: the telescope pointing at points distant from the rotator centre is not affected. stationary mode (rot_reference = STATIONARY) In this mode the rotator is servoed to a stationary position unaffected by the motion of the azimuth and altitude axes. The rotator command sets the reference angle rotator_angle to any value in the extended range of the drive (-1440º to +1440º) and so the rotator can be driven anywhere within the software limits which have been set. The rotator moves immediately irrespective of the motion state of the telescope. The console/handset pushbuttons jog the value of the reference angle rotator_angle. position angle or vertical angle mode (rot_reference = POSITION_ANGLE or VERTICAL_ANGLE) In these modes the rotator is servoed so that the angle on the sky between the instrument principal direction and north60 or the upward vertical respectively is kept constant. The rotator command immediately sets the reference angles position_angle or vertical_angle and the console/handset pushbuttons jog that reference angle. If the telescope is acquiring or tracking a celestial object, the rotator motion ocurrs immediately. Conversely if the telescope has halted or is being slewed, the rotator does not move until a subsequent track command is issued.

Parameters The parameter θ must be a valid numeric value representing the reference angle in degrees. The permissable range for θ is [0, 360) when it represents position angle or vertical angle, but (–1440, +1440) for the physical rotator angle. The qualifier cw or ccw may be present anywhere in the command line. It forces the rotator to turn clockwise or counter-clockwise respectively in order to acquire the reference angle61; The qualifiers are mutually exclusive and, if neither is present, the rotator will take the shortest arc to a rotator angle which realizes the supplied reference angle.

59 The rotator angle is the physical angle of the rotator mechanism; it can be read directly from the engraved scale on the rotator flange and has the same interpretation and sense for each of the foci. It is zero in the position where the instrument fiducial (fixed in the instrument) coincides with the rotator fiducial (fixed to the fork or primary cell). See chapter 1 for a description of the rotator and focal plane geometries. 60 North with respect to the current tracking coordinate system. 61 The directions always apply to the physical rotator angle; the directional sense of position angle or vertical angle may be reversed depending on the focal station.


If the qualifier offset appears, the angular value is taken to be an offset to the current reference angle. In this case the parameter ∆θ must be a valid numeric specifying the (algebraic) offset in degrees. The offset is not checked for range (since the resultant rotator angle is managed for wrapping and limits). The qualifiers cw and ccw are not accepted for offset control of the rotator. As with other motion control commands, the user may append the qualifier wait to defer return of control until the rotator has acquired the new reference position. However, for some combinations of rotator mode and telescope state, rotator motion does not ocurr until a subsequent track command is issued; (see above). In these cases control is returned immediately notwithstanding the wait qualifier. The command rotator show simply lists the current rotator system data: configuration settings, the reference angle and the current encoded rotator position. Likewise the bare command rotator (without any parameters or qualifiers). The current operational state and motion of the rotator is unaffected.

Standard Response As soon as the command is accepted, one of the following strings is output: [ROTREFANGL] Rotator reference angle set to xxxx.xxx (degrees) [ROTOFFSET] Rotator reference angle offset to xxxx.xxx (degrees) If a field cannot be recognized as a valid qualifier, or if θ or ∆θ is not a valid numeric, the following string is output: [INVPARAM] Invalid command line parameter; command ignored If both the cw and ccw secondary qualifiers are present, the following string is output: [MUTEXPARAM] Parameters encountered in command string are mutually exclusive If the parameter θ is out of range62, the following string is output: [ROTRANGE] Rotator reference angle is out of range; command ignored If the keyword show is followed by additional fields, the following string is output: [UNXPARAM] Unexpected or unrecognized parameter encountered in command string If the parameter show was present or implied, the following rotator system data is output: [ROTDATA] Current rotator state for focal_station \n rot_reference(mode)=POSITION_ANGLE reference angle = ±xxxx.xxx (deg)\n iaa_source = SLIT aper1=aperonename aper2=apertwoname iaa_obsvr=ddd.dd (deg) \n rotator wavelength = 550 nm optimisation = FIELD \n rotator position(encoded)= ±xxxx.xxx ccw_limit= ±aaaa.aaa cw_limit = ±cccc.ccc ( deg) \n rotator RMS error = xxxx.xx arcmin \n (Note that fields indicated with shading may be individually supressed with blanks if they are not relevant to the current setting of iaa_source.)

rotator (definition) (priv=observer) Synopsis rotator cw_limit|ccw_limit θlimit rotator [reference] rot_in_use|stationary|position_angle|vertical_angle rotator iaa_source aper rotator iaa_source slit aper_1 rotator iaa_source radial aper_1 rotator iaa_source aper_pair aper_1 aper_2 rotator iaa_source angle φ rotator wavelength λ rotator optimization field|slit Description

62 The permissable range of θ depends on rot_reference; if rot_reference = STATIONARY, the range is (–1440, +1440); otherwise it is [0, 360).


The rotator definition group of commands permits configuration of the rotator system. The user may set the clockwise and counterclockwise limits, the rotator reference (rotator mode) and the group of variables which determine the instrument alignment angle (orientation of the IPD in the instrument focal plane). rotator limits (rot_cw_limit, rot_ccw_limit) The observer configures the operational clockwise and counter-clockwise limits for the rotator which are used to constrain rotator motion63. When these inner limits are configured, two outer limits rot_cw_xlimit and rot_ccw_xlimit are automatically generated approximately 3° beyond them. The outer limits serve to protect the instrument cables and rotator system should a serious fault occur in the rotator drive system. Should a rotator angle beyond the outer limits be encountered, the rotator servo is immediately tripped. rotator reference ("rotator mode") (rot_reference) The basic function of the rotator is to relate a defined direction in the instrument focal plane (the instrument principle direction) to a given orientation on the celestial sphere. The nature of this relationship is determined by the rotator reference which may be set to the following values: NOT_IN_USE the rotator is not controlled at all and is kept stationary; STATIONARY the rotator is stationary but can be driven to a specified mechanical rotator angle; POSITION_ANGLE the rotator is controlled so as to maintain a specified position angle with respect to north in the current tracking coordinate system; VERTICAL_ANGLE the rotator is controlled so as to maintain a specified vertical angle with respect to the vertical circle; source of instrument alignment angle (iaa_source, iaa_aper1, iaa_aper2, iaa_obsvr) The instrument principle direction is defined by its orientation (the instrument alignment angle φ ) with respect to the y-axis in the instrument focal plane64. The configuration variable iaa_source determines where the TCS obtains this information and may be set to the following values: APER the IPD is determined from the instrument alignment angle φ associated with the currently selected aperture; when a different aperture is selected, the rotator moves to use the angle φ associated with the new aperture; SLIT the IPD is determined from the angle φ associated with the aperture named iaa_aper1; RADIAL the IPD is determined to be the radial line from the rotator centre to the aperture named iaa_aper1; APER_PAIR the IPD is determined to be the line joining the two apertures named iaa_aper1 and iaa_aper2; ANGLE the IPD is determined directly from the numerical angle φ set by the observer as iaa_obsvr.

Parameters The first parameter must indicate the primary configuration variable and so must be one of the keywords cw_limit, ccw_limit, reference, iaa_source, wavelength, optimization; suitably unique abbreviations are accepted. For setting rotator limits, parameter θlimit must be a valid numeric value representing the mechanical rotator angle at the appropriate limit. The limit angle must be in degrees in the range –1440° to +1440°. When setting the rotator reference, the keyword reference must be followed by one of the keywords not_in_use, stationary, position_angle or vertical_angle or a suitable abbreviation. For this particular form of the command, the keyword reference is not mandatory; the the command is unambiguous if it is omitted65. Setting the instrument alignment angle with the keyword iaa_source requires adherence to one of the five forms above in order that the parameters be mutually consistent: the parameter aper_1 (which follows the keywords aper or slit) must be the name of a currently defined aperture; likewise aper_2 which is needed when the keyword aper_pair is present; the parameter φ which follows the keyword angle must be a valid numeric specifying the required value of the instrument alignment angle in degrees in the range 0 to 360°. When setting the rotator wavelength, the keyword wavelength must be followed by a valid numeric representing the effective wavelength for rotator control purposes. The value λ must lie in the range 0.1 to 10000; if λ < 10 it is assumed to be in micron units, otherwise in nanometres. When setting the rotator control optimization, the keyword optimization must be followed by one of the keywords field or slit.

63 The observer can also set the rotator limits interactively by manually driving the rotator from the handset located at the respective focal station. See §1. 64 The y-axis direction in the instrument focal plane is called the instrument fiducial. 65 When combined with the ability to abbreviate, this means that the rotator "mode" may be set by commands as succinct as rot pos (sets rotator reference to position_angle).


Standard Response As soon as the command is accepted, an appropriate success string is output: [ROTCWLSET] Rotator clockwise limit set to xxxx.xxx (degrees) [ROTCCWLSET] Rotator counter-clockwise limit set to xxxx.xxx (degrees) [ROTREFSET] Rotator reference set to XXXXXXXX_XXXXX [ROTIAASET] IAA source set to XXXXXX aper1=aper1name aper2=aper2name iaa_obsvr=ddd.dd (deg) (Note that fields indicated with shading may be individually supressed with blanks if they are not relevant to the current setting of iaa_source.) [ROTWAVSET] Rotator wavelength set to xxxxx.x (nm) [ROTOPTSET] Rotator control optimization set to XXXX If the keyword in the first field is not one of cw_limit, ccw_limit, reference, iaa_source, wavelength or optimization, the following string is output: [INVROTDEFN] Rotator definition not recognized; command ignored If the field following parameter reference is not one of not_in_use, stationary, position_angle or vertical_angle, the following string is output: [INVROTREF] Invalid specification for rotator reference; command ignored If the field(s) following parameter iaa_source do not comply with the syntax defined above, the following string is output: [INVIAASRC] Invalid specification for instrument alignment angle; command ignored If a field cannot be recognized as a valid keyword, or if numerical fields are invalid, the following string is output: [INVPARAM] Invalid command line parameter; command ignored If unexpected fields are present, the following string is output: [UNXPARAM] Unexpected or unrecognized parameter encountered in command string If both the cw_limit and ccw_limit keywords are present, the following string is output: [MUTEXPARAM] Parameters encountered in command string are mutually exclusive If the parameter θlimit is not in the range (–1440, +1440), the following string is output: [ROLIMRANGE] Rotator limit is out of range; limit not changed If the parameter φ is not in the range [0, 360), the following string is output: [IAARANGE] Supplied instrument alignment angle (IAA) is out of range If the parameter λ is not in the range (0.1, 10000), the following string is output: [WAVLRANGE] Supplied wavelength is out of range; command ignored If the parameter aper_1 or aper_2 is not defined in the aperture table, the following string is output: [APNOTDEF] Nominated aperture is not defined If the parameters aper_1 and aper_2 refer to the same aperture, the following string is output: [APERNOTDIF] APER_1 and APER_2 must refer to different apertures If the field following parameter optimization is neither slit nor field, the following string is output: [INVROTOPT] Invalid rotator control option; command ignored servo (priv=engineering) Synopsis servo azvel altvel [rotvel] [noramp] Description Drives the telescope axes and rotator at constant speed with the velocities supplied. Unless the noramp option is specified, the motion ramps smoothly up or down to the supplied values. No check is made on axis or rotator limits and consequently any motion will only be arrested by limit switch activation or other “outer-level” protection. This could result in a recovery operation or manual intervention being needed! Particular care should be taken if a rotator velocity is supplied. The command is strictly only for engineering purposes.

Parameters The parameter azvel is a free-field floating point number giving the required azimuth velocity and is mandatory.


The parameter altvel is a free-field floating point number giving the required altitude velocity and is mandatory. The parameter rotvel is a free-field floating point number giving the required instrument rotator velocity; it may be omitted, in which case it defaults to zero. Only the rotator for the selected focal station can be driven. All velocities are specified as percentage of full speed (%FS). A velocity value should be set to zero if that axis/drive is to remain stationary. Any or all of the velocity values may be replaced with a minus character (–), in which case the existing velocity of that axis/drive is not changed. Any sign prefixing a velocity value is interpreted according to the axis conventions for the particular telescope. For the 2.3metre these are: azimuth positive clockwise (north through east), altitude positive upwards (horizon towards zenith) and rotator positive clockwise (viewed facing the instrument mounting flange). A positive sign is optional. If the option noramp is present, the supplied velocities are delivered immediately to the telescope servos and the usual ramp filter is bypassed. In this case however, the step-change in each velocity demand is limited to 10% of full speed for that axis or drive to avoid dangerous transients.

Standard Response Immediately the command is accepted, the following string is output: [VELOCITY] Axes/rotator set to constant speed, azvel = ±xxx.xx% altvel = ±xxx.xx% rotvel = ±xxx.xx% Note that no indication is given when the drives attain their velocity set-points. If a fault prevents motion in any or all of the drives, the following string is output: [PRECLUDE] Telescope fault precludes proper control of motion If a missing or invalid user argument has been supplied, one of the following strings is output: [VELRANGE] Supplied velocity value is out of range; command ignored [MISSPARAM] Missing command line parameter; command ignored slew (priv = observer) Synopsis slew azimuth altitude [wait] slew Description Slews the telescope to the specified topocentric alt-azimuth coordinates and leaves it stationary. (This command is used for engineering purposes or to manoeuver the telescope to a particular quadrant or region of the sky; it is not normally used as a prelude to tracking, the command track is used to acquire and track a celestial object.) Whether building motion occurs depends on the type of building/dome and how it is configured. The 2.3metre building will always move if there is telescope azimuth motion. The instrument rotator and other mechanisms are not moved. Normally control is returned immediately leaving the telescope in motion. Both angle arguments may extend to the full range of the relevant axis. This accommodates particular axis excursion or cable-wrap limits. For example the 2.3metre altitude axis is restricted to the limits alt_horizon_limit and alt_zenith_limit (nominally 20° to 89.6°) whilst the azimuth has a range of az_ccw_limit to az_cw_limit (nominally –160° to +340°). If the command verb slew appears without any parameters, no change to the telescope motion state is made (ie it continues to slew or track or remains stationary) but the current telescope axis angles and motion state are reported.

Parameters The parameter azimuth is a free-field floating point number giving the required azimuth in degrees (north through east) in the range az_ccw_limit to az_cw_limit. The parameter altitude is a free-field floating point number giving the required altitude in degrees (positive above horizon) in the range alt_horizon_limit to alt_zenith_limit.


Either or both angle parameters may be replaced with a minus character (–) in which case that telescope axis is not moved and the corresponding telescope axis coordinate does not change. If the flag wait is present, control is returned to the user only after the motion has ceased and the telescope is stationary at the specified position.

Standard Response As soon as the command is accepted, the following string is output: [SLEWING] Slewing telescope to azimuth = aaaaa.aaaa, altitude = aaaa.aaaa ... If an axis servo fault exists the following string is output: [PRECLUDE] Telescope fault precludes proper control of motion If a user argument is missing or invalid, one of the following strings is output: [AZRANGE] Azimuth value is out of range; command ignored [ALTRANGE] Altitude value is out of range; command ignored [MISSPARAM] Missing command line parameter; command ignored If the command was entered without any arguments, the following string is output: [ALTAZ] Current telescope azimuth= aaaaa.aaaa altitude= aaaaa.aaaa motion state = motion_state If the qualifier wait is present, then the following string is output after the motion has successfully completed: [HALTED] Telescope now stationary at azimuth = aaaaa.aaaa altitude = aaaa.aaaa

stow (priv=engineering) Synopsis stow Description Slews the telescope in azimuth to the value given by the database parameter park_azimuth and in altitude to the altitude stow position given by stow_altitude. In the case of the 2.3metre, the stow altitude is just beyond (above) the altitude zenith limit but before the point at which the altitude limit switches activate. This command is used to position the telescope so that (a) the altitude axis stow pin may be engaged and (b) the building is in a position permitting access to the front double doors. The instrument rotator, focuser and other mechanisms are not moved. Control is returned only after the stow position is acquired.

Parameters None 66

Standard Response As soon as the command is accepted, the following string is output: [STOWING] Telescope stow sequence commenced... If an axis servo fault exists the following string is output: [PRECLUDE] Telescope fault precludes proper control of motion When the motion completes successfully, the following string is output: [STOWED] Telescope now stationary at stow position; INSERT ALTITUDE LOCKING PIN track (overview) (priv=observer) Synopsis track [Q] [coordinates | object-name | index | filename] [q|...q] track Description

66 Because the purpose of the stow command is to facilitate engineering operations the wait option is implicit.


This command is used to cause the telescope to acquire and track a celestial object. It is the motion-control command most needed by observers and performs two functions: • it drives the telescope to the required celestial coordinates and commences tracking there, or • it sets parameters such as the coordinate file name or the tracking coordinate system which may be needed to

define the track command environment. The track command can accept celestial coordinates typed into the command line or read from a coordinate file; alternatively the required position can be generated from an ephemeris file or a file of orbital elements. In the case of the major planets or the moon, they can be tracked simply by name. The command halt will override any variant of the track command (even if that command has wait appended) and stop the telescope on the sky; in most cases, the tracking session can be resumed simply by issuing the bare command track.

Parameters The parameter Q is called the primary qualifier; if present, it must appear first and be one of coord, ephem, orbit, planet, moon, here, base, zero, source, next, previous, name, equinox, cosys or file. The variants of the track command are described separately for each primary qualifier. If no primary qualifier is present, the command attempts to track an object in the currently selected coordinate file: if the first data field commences with an alphabetic character, it is interpreted as the name of the object for which the file is to be searched; if instead the field is a valid numeric, then that number is used as the index to the file. Some variants of the track command require specific data: in-line coordinate specifications as described in chapter 1, the name of an object to be found in a file or one of the reserved names for the planets, an index or offset to the selected coordinate file, or a filename to be selected as such. The precise behaviour of the tracking session is determined also by secondary qualifiers. These are shown as optional parameters q in the synopsis and may be inserted anywhere after the primary qualifier but are conventionally appended at the end of the command string. The valid secondary qualifiers comprise cw, ccw, rising, rate, offset, wait and show; more than one may be present. Each of these is explained below. cw and ccw force the telescope azimuth axis to turn clockwise or counter-clockwise respectively in order to acquire the object; if neither is present, the telescope will take the shortest arc to the object. rising causes the telescope to set to the horizon limit and await the rise of an object which is below the horizon whereon normal trackng is commenced. If it is not present, an error message is issued for an object below the horizon or beyond a limit and the telescope does not move. This qualifier can also be used to set the telescope to the zenithal circle of avoidance and await the exit of an object which is inside it. rate leaves the differential tracking rates (previously established by a rate command) in operation. If not present, a track command which results in a new position being selected will cancel any existing rates67. offset leaves the the observer's celestial offsets (previously established by an offset command) in operation. If not present, a track command which results in a new position being selected will cancel these offsets. wait withholds control from the observer until the telescope has acquired the object and is tracking normally68. If not present, control is returned immediately the command is accepted, leaving the telescope slewing towards acquisition. show causes an information message to be issued. The track command is implemented up until the point at which it would normally be acted upon by the control loop. No motion is initiated and if the telescope is currently tracking or slewing to track, that motion proceeds undisturbed. Indeed, the track ... show command may be used advantageously to explore the behaviour of objects other than the one being currently tracked or which is selected in the coordinate file. The data output is a subset of the "current object data" and is listed below in the message [TRACKDATA].

Standard Response In general, a successful command which results in motion causes the following string to be output: [ACQUIRING] Slewing to acquire object name RA= hh:mm:ss.s DEC= ±dd:mm:ss.ss Cosys= eqnx

67 Note that all track commands which result in telescope motion cancel and clear any scan which is in progress. 68 The qualifier wait has particular importance when the command is issued from a script; it will prevent subsequent script commands being executed before the telescope is in position.


And when the telescope has acquired the object and is tracking, the following string is added: [TRACKING] Now tracking object name RA= hh:mm:ss.s DEC= ±dd:mm:ss.ss Cosys= eqnx If a telescope fault precludes acquisition of the object, the following string is output: [PRECLUDE] Telescope fault precludes proper control of motion The successful use of the qualifier show results in the output of the following string: [TRACKDATA] Object = object-name \n FK5 J2000 coordinates RA = hh:mm:ss.sss DEC = ±dd mm ss.ss Object never rises or Object never sets or Object currently set, will rise at hh:mm UT, culminate at hh:mm UT and set at hh:mm UT or Object currently above horizon, rose at hh:mm UT, culminates at hh:mm UT and will set at hh:mm UT Distance from sun ddd.d, from moon ddd.d, from avoidance object ddd.d (degrees) Apparent coordinates RA = hh:mm:ss.sss DEC = ±dd mm ss.ss HA = ±hh.hhhhh (hours), Parallactic angle = ddd.ddddd (degrees) Observed Azimuth = ddd.dddddd, Altitude = dd.dddddd, Zenith distance = dd.dddddd (degrees) Airmass = xx.xxxx Component of Earth's barycentric position towards object = x.xxxxxxx (AU) Component of Earth's barycentric velocity towards object = 0.xxxxxxx (AU/day) Time to limits horizon = mmm, zenith = mmm, ccw = mmm, cw: mmm (minutes) Time to acquire object = mmm (minutes), if azimuth direction XCW. Alternatively: [TRACKDATA] Object = object-name: NO DATA AVAILABLE If a field cannot be recognized as a valid primary or secondary qualifier, the following string is output: [INVPARAM] Invalid command line parameter; command ignored If both the cw and ccw secondary qualifiers are present, the following string is output: [MUTEXPARAM] Parameters encountered in command string are mutually exclusive If the qualifier show has been appended to a form of the track command for which it is innappropriate, the following string is output: [NOSHOW] The qualifier show cannot be appended to this particular command; command ignored Other output messages which are issued in response to user input errors or events are listed below under the command variant for which they have particular significance. track (priv=observer) Synopsis track Description The telescope resumes tracking using the data for the last object tracked. Any observer entered rates and offsets are preserved but any scan in progress is halted and cleared. This command can be used to recommence tracking after a halt has been issued. In situations where other track or motion control commands have been issued in the meantime, this command may have unexpected results.

Parameters None

Standard Response The string returned upon successful implementation depends upon the previous track command. track coordinates (priv=observer) Synopsis


track coordinates coordinate-specification [q|...q] Description Slews the telescope to the celestial object whose coordinates have been supplied in the command string and commences tracking.

Parameters The primary qualifier must be coordinate (which can be abbreviated to as little as coord or coo) and must be the first field. The supplied coordinates must be a FK4 or FK5 mean place or an apparent place69 and must conform to the specifications in chapter 1. A summary of the required format appears below: The equatorial coordinate format is specified completely in chapter 1 which reproduces the document: RSAA Standard Format for Equatorial Polar Coordinates. Except for the object name which may appear anywhere in the string, the order of the parameters is fixed but the format is extremely flexible: for example, most sub-fields may be omitted or decimalised. In summary the format is: [=object_name=] α δ [equinox [(epoch)]] [µα µδ [ π [Vr ]]] [# comment] To provide backward compatibility, coordinate files may contain records which have the object name enclosed in double quote characters or which have comments denoted by the ! character thus: ["object_name"] α δ [equinox [(epoch)]] [µα µδ [ π [Vr ]]] [! comment] Note, however, if an coordinate specification is typed directly into the track command (as distinct from being read from a coordinate file), the object name must be enclosed by equal-signs; this is dictated by the shell used by the QNX RTOS. One or more of the secondary qualifiers cw, ccw, rising, rate, offset, wait or show may follow the coordinate specification; their effects are described above.

Standard Response If the command is successfull, the following string is output: [ACQUIRING] Slewing to acquire object name RA= hh:mm:ss.s DEC= ±dd:mm:ss.ss Cosys= eqnx When the telescope has acquired the object and is tracking, the following string is output: [TRACKING] Now tracking object name RA= hh:mm:ss.s DEC= ±dd:mm:ss.ss Cosys= eqnx If a telescope fault precludes acquisition of the object, the following string is output: [PRECLUDE] Telescope fault precludes proper control of motion If the coordinate data input by the observer is in error, one of a number of strings is output: [NORA] No right ascension coordinate has been supplied [NODEC] No declination coordinate has been supplied [ERRINRA] Error in right ascension coordinate supplied [ERRINDEC] Error in declination coordinate supplied [INVEPOCH] Invalid equinox or epoch string [ERRINEQX] Error in coordinate system (equinox or epoch) supplied [ERRINMURA] Error in proper motion in right ascension [ERRINMUDEC] Error in proper motion in declination [NOMUDEC] Proper motion in declination appears to be missing: u_DEC must appear if u_RA is specified [TOOMANQUO] Object name wrongly delimited: too many characters " or = are present track ephemeris (priv=observer) Synopsis track ephemeris file-spec [q|...q] Description Tracks an object whose celestial coordinates are tabulated for discrete epochs in an ephemeris file. The format of ephemeris files is defined in §1 but basically consists of records containing a time, right ascension and declination for the object. The time is interpreted as a JD or MJD in a timescale which may be specified by the observer but which defaults to Terrestrial Time (TT); the coordinates are assumed to be in the user's default coordinate system unless explicit equinox/cosys fields are included in the record. The ephemerides need not be equally spaced in time. 69 The track coordinate command will actually accept altazimuth coordinates if the "equinox" specification is set to AZEL_TOPO. Whilst the telescope will track this position, many display variables become meaningless or wrongly labelled and this facility is not yet fully characterized.


Parameters The primary qualifier must be ephemeris (which can be abbreviated to as little as eph) and must be the first field. The parameter file-spec indicates the required ephemeris file. If file-spec commences with a leading / character, it is interpreted as a complete path specification and referenced in its entirety; otherwise it is assumed to be only the filename and is prepended with the default data directory so that the file specification becomes $MSOTCS_DATA.file-spec. The ephemeris file is not read by the main control loop but by a separate process ephem_reader. This process attempts to open the file; if the file is not found with the filename/file specification supplied, the suffix .ephem is appended and the file open retried. One or more of the secondary qualifiers cw, ccw, rising, rate, offset, wait or show may follow the file specification; their effects are described above.

Standard Response If the command is successfull, the following string is output: [ACQUIRING] Slewing to acquire object name RA= hh:mm:ss.s DEC= ±dd:mm:ss.ss Cosys= eqnx When the telescope has acquired the object and is tracking, the following string is output: [TRACKING] Now tracking object name RA= hh:mm:ss.s DEC= ±dd:mm:ss.ss Cosys= eqnx If a telescope fault precludes acquisition of the object, the following string is output: [PRECLUDE] Telescope fault precludes proper control of motion If no file-spec is present or if it is not a valid QNX filename, the following string is output: [NOEPHFILE] Missing or invalid ephemeris filename If an error ocurrs on opening or reading the ephemeris file, the following string is output: [EPHREADERR] Error opening or reading ephemeris file filename If the ephemeris file contains no data records, the following string is output: [NOEPHDATA] Ephemeris file contains no data records If invalid data is encountered in an ehemeris file record, the following string is output: [BADEPHEM] Bad data encountered in ephemeris file If the ephemeris file times do not bracket the present epoch, the following string is output: [EPHEMRANGE] Ephemeris time problem: earliest ephemeris time is still in future If ephemeris data has expired or could not be accessed promptly, the following string is output: [EPHEMNORDY] Ephemeris data is not available for the present instant or could not be accessed in time track orbit (priv=observer) Synopsis track orbit file-spec [q|...q] Description Tracks a solar-system object whose orbital elements are read from an orbit file. An orbit file specifies the osculating heliocentric elements for the object in one of three forms according to the source of the data and whether the object is a major planet (jform=1), minor planet (jform=2) or comet (jform=3). Two important sources for such orbital elements are Horizons, operated by the Jet Propulsion Laboratory, Pasadena, and the Minor Planet Center, operated by the Center for Astrophysics, Harvard. The orbital element names vary and incommensurate units are used for angle variables and epochs. The command extracts these orbital element data, rationalizes them to a consistent set and calculates the FK5 J2000 tracking position and rate at date70. The data is reduced to the set of elements tabulated below:

variable datatype description epoch_oscul double epoch of osculation (TT MJD) jform int flag giving choice of element set (j = 1,2 or 3) epoch double epoch of osculation (j=1,2) or perihelion passage (j=3) (TT MJD) 70 This command does not change the observer's selected tracking coordinate system but temporarily overrides it with FK5 J2000.0 for the duration of the tracking session.


orbinc double inclination (radian) anode double longitude of the ascending node (radian) perih double longitude (j=1) or argument (j=2,3) of perihelion (radian) aorq double semimajor axis (j=1,2) or perihelion distance (j=3) (AU) e double eccentricity aorl double mean anomaly or longitude (radians) needed only for j=1,2 dm double daily motion (radian) needed only for j=1

The format of orbit files is defined in §1.

Parameters The primary qualifier must be orbit and must be the first field. The parameter file-spec indicates the required orbit file. If file-spec commences with a leading / character, it is interpreted as a complete path specification and referenced in its entirety; otherwise it is assumed to be only the filename and is prepended with the default data directory so that the file specification becomes $MSOTCS_DATA.file-spec. The command attempts to open the orbit file; if the file is not found with the filename/file specification supplied, the suffix .orbit is appended and the file open retried. One or more of the secondary qualifiers cw, ccw, rising, rate, offset, wait or show may follow the file specification; their effects are described above.

Standard Response If the command is successfull, the following two strings are output: [NEWTRKSYS] CAUTION: tracking coordinate system has been temporarily set to FK5 J2000 [ACQUIRING] Slewing to acquire object name RA= hh:mm:ss.s DEC= ±dd:mm:ss.ss Cosys= eqnx When the telescope has acquired the object and is tracking, the following string is output: [TRACKING] Now tracking object name RA= hh:mm:ss.s DEC= ±dd:mm:ss.ss Cosys= eqnx If a telescope fault precludes acquisition of the object, the following string is output: [PRECLUDE] Telescope fault precludes proper control of motion If no file-spec is present or if it is not a valid QNX filename, the following string is output: [NOORBFILE] Missing orbit file or invalid filename If an error ocurrs on opening or reading the ephemeris file, the following string is output: [ORBREADERR] Error opening or reading orbit file filename If the orbit file contains no data records, the following string is output: [NOEPHDATA] Orbit file contains no data records If invalid data is encountered or an orbital element is missing, the following string is output: [ORBDATABAD] Invalid data in file or a required orbital element is missing If errors in particular elements or numerical problems are detected, or if the orbit has zero radius, one of the following strings is output: [ORBITBADJ] Invalid value for orbit flag jform [ORBITBADE] Invalid value for orbit eccentricity [ORBBADAORQ] Invalid value for orbit semimajor axis/perihelion distance [ORBITBADDM] Invalid value for orbit daily motion [ORBITEL2UE] Numerical error in orbit calculation routine slaEl2ue [ORBITUE2PV] Numerical error in orbit calculation: routine slaUe2pv failed to converge [ORBITZERO] Orbit radius is zero track planet (priv=observer) Synopsis track planet name [q|...q] Description


Tracks the designated solar-system object by generating the J2000 topocentric position and rate of a solar system object and using this data as tracking coordinates71. The basis of the routine is the SLAlib routine slaPlanet which employs the algorithms and data of J.L. Simon, P. Bretagnon, J. Chapront, M. Chapront-Touze, G. Francou and J. Laskarrom (Bureau des Longitudes, Paris) for the mean elements of the planets Mercury to Neptune and a (completely different) algorithm by Meeus to calculate the ecliptic coordinates of Pluto.

Parameters The primary qualifier must be planet and must be the first field. The parameter name indicates the required planet and must be one of the names: Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune or Pluto. The planet name is not case-sensitive. One or more of the secondary qualifiers cw, ccw, rising, rate, offset, wait or show may follow the file specification; their effects are described above.

Standard Response If the command is successfull, the following two strings are output: [NEWTRKSYS] CAUTION: tracking coordinate system has been temporarily set to FK5 J2000 [ACQUIRING] Slewing to acquire object name RA= hh:mm:ss.s DEC= ±dd:mm:ss.ss Cosys= eqnx When the telescope has acquired the object and is tracking, the following string is output: [TRACKING] Now tracking object name RA= hh:mm:ss.s DEC= ±dd:mm:ss.ss Cosys= eqnx If a telescope fault precludes acquisition of the object, the following string is output: [PRECLUDE] Telescope fault precludes proper control of motion If an invalid planet name is supplied, the following string is output: [INVPLANET] Invalid planet or object name In the unlikely case of a numerical convergence failure, the following string is output: [SLAPLANET] Numerical error in calculation: routine slaPlanet failed to converge

track moon (priv=observer) Synopsis track moon [q|...q] Description Tracks the moon by generating its J2000 topocentric position and rate and using this data as tracking coordinates72. The routine derives the lunar position from the less accurate of the two available SLAlib routines (slaMoon) which is a relaxed accuracy implementation of an algorithm by Meeus. The telescope will set to the approximate centre of the lunar disc but, because the lunar rate is not continually recalculated, the longer term tracking will be degraded and the command may need to be re-entered.)

Parameters The primary qualifier must be moon and is not case-sensitive. One or more of the secondary qualifiers cw, ccw, rising, rate, offset, wait or show may follow the file specification; their effects are described above.

Standard Response

71 This command does not change the observer's selected tracking coordinate system but temporarily overrides it with FK5 J2000.0 for the duration of the tracking session. 72 This command does not change the observer's selected tracking coordinate system but temporarily overrides it with FK5 J2000.0 for the duration of the tracking session.


If the command is successfull, the following two strings are output: [NEWTRKSYS] CAUTION: tracking coordinate system has been temporarily set to FK5 J2000 [ACQUIRING] Slewing to acquire object moon RA= hh:mm:ss.s DEC= ±dd:mm:ss.ss Cosys= eqnx When the telescope has acquired the object and is tracking, the following string is output: [TRACKING] Now tracking object moon RA= hh:mm:ss.s DEC= ±dd:mm:ss.ss Cosys= eqnx If a telescope fault precludes acquisition of the object, the following string is output: [PRECLUDE] Telescope fault precludes proper control of motion

track here (priv=observer) Synopsis track here [wait] Description Commences tracking wherever the telescope axes happen to be pointing on the sky. This command is primarily intended for engineering purposes but may be useful for observers when setting up. Note that it may initiate motion of the instrument rotator if the rotator is configured other than NOT_IN USE.

Parameters The primary qualifier here must appear. The only valid secondary qualifier is wait.

Standard Response If the command is successfull, the following string is output: [ACQUIRING] Slewing to acquire object ???? RA= hh:mm:ss.s DEC= ±dd:mm:ss.ss Cosys= APPT When the telescope has acquired the object and is tracking, the following string is output: [TRACKING] Now tracking object ???? RA= hh:mm:ss.s DEC= ±dd:mm:ss.ss Cosys= APPT If a telescope fault precludes acquisition of the object, the following string is output: [PRECLUDE] Telescope fault precludes proper control of motion If the command string contains any data or qualifiers other than wait, the following string is output: [INVPARAM] Invalid command line parameter; command ignored track base (priv=observer) Synopsis track base [rate] [wait] Description The telescope is moved to track the current base coordinates by zeroing any celestial offsets. Any rate entered by the observer is also zeroed unless the rate qualifier is present. Any scan in progress is stopped and reset. Note that if the track zero command has been used to change the base coordinates since the commmencement of tracking, the telescope will move to the new base coordinates not the original source coordinates of the object.

Parameters The primary qualifier base must appear. The only valid secondary qualifiers are rate and wait. If the rate qualifier is present, a differential track rate previously entered by the observer is permitted to persist; otherwise all rates and offsets are cleared.

Standard Response If the command is successfull, the following string is output: [ACQUIRING] Slewing to acquire object name RA= hh:mm:ss.s DEC= ±dd:mm:ss.ss Cosys= eqnx When the telescope has acquired the object and is tracking, the following string is output: [TRACKING] Now tracking object name RA= hh:mm:ss.s DEC= ±dd:mm:ss.ss Cosys= eqnx


If a telescope fault precludes acquisition of the object, the following string is output: [PRECLUDE] Telescope fault precludes proper control of motion If the command string contains any data or qualifiers other than rate or wait, the following string is output: [INVPARAM] Invalid command line parameter; command ignored track zero (priv=observer) Synopsis track zero [rate] [wait] Description The base coordinates are replaced by the current tracking coordinates and the accumulated offsets zeroed. The telescope is not moved and the effect is to redefine the current tracking position as a new base position.

Parameters The primary qualifier zero must appear. The only valid secondary qualifiers are rate and wait. If the rate qualifier is present, a differential track rate previously entered by the observer is permitted to persist; it is applied to the current position commencing at the time the command is entered.

Standard Response If the command is successfull, the following string is output: [ACQUIRING] Slewing to acquire object name RA= hh:mm:ss.s DEC= ±dd:mm:ss.ss Cosys= eqnx When the telescope has acquired the object and is tracking, the following string is output: [TRACKING] Now tracking object name RA= hh:mm:ss.s DEC= ±dd:mm:ss.ss Cosys= eqnx If a telescope fault precludes acquisition of the object, the following string is output: [PRECLUDE] Telescope fault precludes proper control of motion If the command string contains any data or qualifiers other than rate or wait, the following string is output: [INVPARAM] Invalid command line parameter; command ignored track source (priv=observer) Synopsis track source [q|..q] Description Recommences tracking the last object whose coordinates were specified in the command line or read from a coordinate file. The source coordinates for the object are processed afresh. The command is rejected if the last object was a planet or the moon, or was specified using an ephemeris or orbit file.

Parameters The primary qualifier source must appear. Any of the secondary qualifiers are valid and take effect as described above.

Standard Response If the command is successfull, the following string is output: [ACQUIRING] Slewing to acquire object name RA= hh:mm:ss.s DEC= ±dd:mm:ss.ss Cosys= eqnx When the telescope has acquired the object and is tracking, the following string is output: [TRACKING] Now tracking object name RA= hh:mm:ss.s DEC= ±dd:mm:ss.ss Cosys= eqnx If a telescope fault precludes acquisition of the object, the following string is output: [PRECLUDE] Telescope fault precludes proper control of motion If the last object tracked was not specified using explicit coordinates, the following string is output: [NEEDSCB] Track source cannot be used subsequent to tracking orbit, ephemeris, planet or moon; command ignored


track n (priv=observer) Synopsis track n [q|..q] Description Tracks the nth entry in the currently selected coordinate file. This form of the command is assumed whenever there is no primary qualifier and the first field is a numeric.

Parameters The parameter n is interpreted as a decimal integer index to the coordinate file. n must be positive and the first entry of the file is numbered 1. Any of the secondary qualifiers are valid and take effect as described above.

Standard Response If the command is successfull, the following string is output: [ACQUIRING] Slewing to acquire object name RA= hh:mm:ss.s DEC= ±dd:mm:ss.ss Cosys= eqnx When the telescope has acquired the object and is tracking, the following string is output: [TRACKING] Now tracking object name RA= hh:mm:ss.s DEC= ±dd:mm:ss.ss Cosys= eqnx If a telescope fault precludes acquisition of the object, the following string is output: [PRECLUDE] Telescope fault precludes proper control of motion If there is no coordinate file selected, the following string is output: [NOCOORFILE] No coordinate file currently selected; use track file command If there was an error opening or reading the coordinate file, the following string is output: [COORFILERR] Error opening or reading selected coordinate file filename If the file index supplied is less than 1, the following string is output: [COORFINDEX] Coordinate file index or offset must be greater than zero; command ignored If the index exceeds the number of coordinate records in the file, the following string is output: [COORFILEOF] Coordinate file index out of range; EOF encountered

track previous/next (priv=observer) Synopsis track [previous|next] [n] [q|..q] Description Tracks an entry in the currently selected coordinate file. The object is located relative to the last object tracked in the file (which may be the object which the telescope is currently tracking).

Parameters The primary qualifier previous or next must appear. The offset n is interpreted as an offset from the current coordinate file entry and must be a positive decimal integer. Specific instances of the command are: track previous tracks the object prior to the current one in the coordinate file, track previous n tracks the (current – n)th object in the coordinate file, track next tracks the object after the current one in the coordinate file track next n tracks the (current + n)th object in the coordinate file. Any of the secondary qualifiers are valid and take effect as described above.

Standard Response The responses are identical to those for the command track n above. track object-name (priv=observer)


Synopsis track [name] object-name Description Searches the currently open coordinate file for an object whose name matches the supplied string object-name. The object name search is case insensitive and all instances of multiple white-space are collapsed to a single space character in both the template object-name and in the file records before seeking a match.

Parameters Normally no primary qualifier is required. However, an object name which commences with a numeric will be interpreted as an index to the file. The qualifier name may be used to force the system to accept a numeric or similar string as an object name. Any of the secondary qualifiers are valid and take effect as described above.

Standard Response The responses are identical to those for the command track n above except that if the named object could not be found in the file, the following string is output: [OBJNOFIND] Coordinate object object-name not found track equinox (priv=observer) Synopsis track equinox cosys-specn track cosys cosys-specn Description This command sets the coordinate system in which the telescope tracks or is manouvered around the sky. It is functionally similar to the command configure tracking_coord_system cosys-specn. It does not move the telescope or interrupt its motion and takes effect only when a subsequent track is initiated.

Parameters One of the two primary qualifiers equinox or cosys (which are interchangeable) must appear. The coordinate system cosys-specn specifies both the coordinate system and (for mean places) the epoch of the equinox and takes the one of the forms Jyyyy.yy (for an FK5 mean place system), Byyyy.yy (for an FK4 mean place system), APPT or APPT_TOPO (for an apparent place) or AZEL_TOPO. The format is flexible (with sensible defaults for the coordinate system FK4 or FK5 according to year) and must comply with the specifications in chapter 1.

Standard Response If the command is successfull, the following string is output: [TRACKCOSYS] Tracking coordinate system set to tracking-coord-system If no cosys field was supplied, the following string is output: [MISSCOSYS] Coordinate system specification (cosys) missing If there is a format or other error in the supplied cosys field, the following string is output: [ERRINEQX] Error in coordinate system (equinox or epoch) supplied

track file (priv=observer) Synopsis track file file-spec Description This command selects a coordinate file to be used as a source of celestial objects to be tracked. It does not move the telescope or interrupt its motion. The file selected is accessed by all subsequent track commands of the form track index, track next, track previous and track name.

Parameters The primary qualifier file must appear. The parameter file-spec indicates the required coordinate file. If file-spec commences with a leading / character, it is interpreted as a complete path specification and referenced in its entirety; otherwise it is assumed to be only the filename and is prepended with the default data directory so that the file specification becomes $MSOTCS_DATA.file-spec. In both cases, the command attempts to open the file; if


the file is not found with the filename/file specification supplied, the suffix .coord is appended and the file open retried.

Standard Response If the command is successfull, the following string is output: [COORFILSEL] Coordinate file file-spec selected If no file-spec field was supplied, the following string is output: [MISFILSPEC] Missing file specification; command ignored If the field was not a valid QNX file specification, the following string is output: [INVFILSPEC] Invalid file specification; command ignored If the specified file (with or without the extension .coord) cannot be found, the following string is output: [MISCOORFIL] Coordinate file file-spec missing or cannot be opened

zenith (priv = observer) Synopsis zenith [wait] Description Slews the telescope in altitude to the zenithal limit;73 the azimuth axis, instrument rotator and building are not moved. Normally control is returned immediately leaving the telescope in motion. The telescope is left in the motion state STATIONARY.

Parameters If the flag wait is present, control is returned to the user only after the altitude motion has ceased and the telescope is stationary at the zenithal cone of avoidance.

Standard Response As soon as the command is accepted, the following string is output: [SLEWINGZ] Slewing telescope to zenith limit... If an axis servo fault exists the following string is output: [PRECLUDE] Telescope fault precludes proper control of motion If the qualifier wait is present, then the following string is output after the motion has successfully completed: [HALTEDZ] Telescope is stationary at zenith limit

1.5 Auxiliary subsystem commands The commands below are used to control, activate or reset various auxiliary subsystems or plant. set controls a telescope sub-system or mechanism open opens the building shutter or mirror cover close closes the building shutter or mirror cover reset resets a tripped servomechanism or subsytem focus drives the focuser or sets the focuser control mode

set system state (priv = observer) 74 Synopsis set system state [wait] for example: set telescope_systems on set shutter open set mirror_cover open wait 73 The zenith limit is set by the database parameter alt_zenith_limit. 74 The command set lighting unsafe has engineering (as distinct from observer) privilege to avoid it being inadvertently used by remote observers.


set flatfield on 45% Description Controls a subsystem or mechanism by setting it to the state specified or initiating the action specified. The action is initiated as soon as the command is accepted with control returned immediately or withheld (wait option) until the action has been completed. The table in §1.5.1 below gives the various subsystems for the 2.3m telescope and the states or actions which are appropriate. The master command sequence: set console on set telescope_systems on is used to switch on the entire telescope and plant control electronics. See also the commands open and close which provide synonyms for some operations which may be preferred for semantic reasons.

Parameters The parameter system must be one of the subsystem names from the table at §1.5.1 The parameter state must be one of the states, actions or options associated with that subsystem. If the flag wait is present, control is returned to the user only after the requested action has completed or the state has been acheived. If it is not present, control is returned immediately but the action is still monitored for completion; a timeout error message may result if the requested action fails.

Standard Response As soon as the command has been validated the system initiates the action and responds immediately with the message: [SETTINGSYS] Setting subsystem-name to state Some operations are instantaneous or take only a few milliseconds to complete; other control actions such as opening the shutter or moving the tertiary mirror take tens of seconds. For both cases, successful completion of the action causes a message to be output which is specific to the subsystem; for example: [COVCLOSED] Primary mirror cover has closed If the wait option is appended to the set command, the first response [SETTINGSYS] is never issued and the system returns control only upon completion of the action. If the command cannot be executed because of user input error, one of the following messages is output: [MISSPARAM] Missing command line parameter; command ignored [INVPARAM] Invalid command line parameter; command ignored [INVSTATE] Missing or invalid subsystem state If the command fails because a subsystem is in a faulty or indeterminate state, a message is output which is specific to the subsystem; for example: [SHTNOCTL] Building shutter not controllable; command ignored set flatfield_illumination state brightness (priv = observer) Synopsis set flatfield_illumination state [brightness][%] [wait] for example: set flatfield_illumination on 45% Description For the special case of flatfield illumination control, the desired brightness of the illumination may be included as an additional parameter. The flatfield illumination supply voltage is set according to the %FS value supplied independently of the control state on or off.

Parameters The parameter state must be one of on or off. If the flag wait is present, control is returned to the user only the state has been acheived or the brightness changed. If it is not present, control is returned immediately but the action is still monitored for completion; a timeout error message may result if the requested action fails. The optional parameter brightness is an integer giving the percentage of full brightness; a "%" symbol may be appended if desired but is ignored. If no state parameter is present, the brightness is changed but flatfield


illumination activation is unchanged; if the state parameter is off, then flatfield illumination is turned off and any brightness supplied is ignored. open system (priv = observer) Synopsis open system [wait] for example: open mirror_cover wait (equivalent to set mirror_cover open wait ) Description This command provides a synonym for a command of the form set system open which may be preferable in syntax.

Parameters The parameter system must be one of building_shutter or primary_mirror_cover. If the flag wait is present, control is returned to the user only the state has been acheived or the brightness changed. If it is not present, control is returned immediately but the action is still monitored for completion; a timeout error message may result if the requested action fails. close system (priv = observer) Synopsis close system [wait] for example: close building_shutter (equivalent to set building_shutter closed ) Description This command provides a synonym for a command of the form set system closed which may be preferable in syntax.

Parameters The parameter system must be one of building_shutter or primary_mirror_cover. If the flag wait is present, control is returned to the user only the state has been acheived or the brightness changed. If it is not present, control is returned immediately but the action is still monitored for completion; a timeout error message may result if the requested action fails. reset system (priv = observer)

Synopsis reset system Description Resets telescope or associated plant control electronics after a fault has tripped one or more subsystems. Control is returned immediately leaving the reset action in progress. The 2.3metre TCS permits certain subsystems or grouped facilities to be reset on an individual basis. (The command reset without any options initiates an intelligent sequence which determines which subsystems have tripped and executes the appropriate actions to reset them in the correct sequence.) For the 2.3m telescope, some individual reset options are provided but their effective use requires an understanding of the hardware and its possible states. For this reason it is advised that observers should only use the general form of the command reset described below. Note that an individual subsystem which is currently “switched off” (as distinct from “tripped”) cannot be switched on by the command reset system.

Parameters The optional parameter system must denote a subsystem or item of plant which can be separately reset. For the 2.3m the following items are separately resettable: servos, building_drive, scbr (shutter-closed-by-rain latch).

Standard Response As soon as the command has been accepted, following message is output: [RESETTING] Reset issued to system-name


where system-name is one of the strings: telescope_systems, servos, building_drive or scbr as appropriate. Control is returned to the user immediately leaving the reset action in progress reset (priv = observer)

Synopsis reset Description Resets all telescope control electronics after a fault has tripped one or more subsystems. Control is returned only after the reset action is complete. The command reset without any options initiates an intelligent sequence which determines which subsystems have tripped and executes the appropriate actions to reset them in the correct sequence. This form of the command is preferred for observer use. The command reset will fail if the telescope systems are off; the appropriate command to turn all telescope systems on is set telescope_systems on.

Parameters none

Standard Response As soon as the command has been accepted, following message is output: [RESETTING] Reset issued to telescope_systems Control is returned to the user only after successful completion of the reset action with the following message: [TELPWRON] Telescope systems power on If telescope systems are off, the command will fail with the following message: [TELOFFOK] telescope systems are OFF; reset inappropriate, use command: set telescope on

focus position (priv = observer) Synopsis focus position [wait] focus [show] Description Drives the telescope focuser mechanism to the set-point position supplied. The focuser is implemented as an absolute position servo. The focuser must be configured to automatic or compensated for this command to work.

Parameters The parameter position is interpreted as a distance in the focal plane measured positively outwards from the instrument mounting flange of the relevant focal station. The units and range are telescope specific; for the 2.3m telescope the units are millimetres, the range is approximately ±700mm and the nominal focus is at a point 500mm from the mounting flange of the instrument rotator. Normally control is returned to the user immediately, leaving the focuser in motion. However, if the wait flag is present, control is returned only after the setpoint has been reached and the mechanism is stationary. If the keyword show is present, or if only the command verb focus appears, the focus is not moved; instead the current status, configuration and position of the focuser is reported to the user. When the focuser is configured to compensated, the encoded focus position is first corrected for tube temperature:

{ }021 2/)( tttKFF Tencodeddcompensate −++= before the servo loop is closed. KT and t0 are telescope database parameters and t1, t2 are secondary truss temperatures.

Standard Response The standard response to the command depends on whether the wait option is present: If wait is not present, control is returned and an immediate response is issued with the message; [FOCSET] Focuser in motion; reference set to ±xxx.xx mm


If the focuser configuration is incorrect, the following message is output: [FOCAUTO] Focuser must be in automatic or compensated mode; command ignored If the supplied set-point was out of range, the following message is output: [NUMRANGE] Numeric parameter out of range; command ignored If an extraneous parameter was supplied, the following message is output: [INVPARAM] Invalid command line parameter; command ignored If wait is present, control is with-held until the focuser arrives at the setpoint whereon a message is output: [FOCUSTOP] Focus position achieved ±xxx.xx mm There is no time-out monitor on the focus servo but a suitable message is issued whenever the focus mechanism trangresses the software limits: [FOCINLIM] Focuser has exceeded inner limit [FOCOUTLIM] Focuser has exceeded outer limit If the focuser is faulty or disabled, the command is ignored with the message; [FOCNOCTL] Focuser faulty or not controllable; command ignored Either of the commands focus or focus show cause an informational message to be issued: [FOCINFO] Focuser state, configured mode, current position ±xxx.xx mm focus in/out/halt (priv = observer) Synopsis focus action Description Jogs the telescope focuser mechanism (at full speed) until countermanded by a related command. The onus is on the observer to issue a command focus halt to terminate the action. The focuser must be configured to manual for this command to work.

Parameters The parameter action must take one of the values in, out or halt.

Standard Response For focus in or focus out, control is returned immediately leaving the focuser in motion. An appropriate message is issued: [FOCINWD] Jogging focus inwards; focuser in motion; [FOCOUTWD] Jogging focus outwards; focuser in motion; For focus halt, control is returned immediately leaving the focuser stationary and a message is issued: [FOCHALT] Focuser halted at position ±xxx.xx mm If an extraneous or unrecognizable parameter was supplied, the following message is output: [INVPARAM] Invalid command line parameter; command ignored If the focuser configuration is incorrect, the following message is output: [FOCMAN] Focuser must be in manual mode; command ignored If the focuser is faulty or disabled, the command is ignored with the message; [FOCNOCTL] Focuser faulty or not controllable; command ignored

focus mode (priv = observer) Synopsis focus manual|automatic|compensated Description Sets the operating mode of the telescope focuser mechanism. This command is formally equivalent to the command configure focus_control mode and is implemented immediately.


Parameters The mode parameter must be one of the keywords manual, automatic or compensated. manual mode (focus_control = MANUAL) The focuser can be jogged by the commands focus in or focus out or by using the focus pushbuttons on the console or handset. In manual mode the focuser mechanism runs at full speed whilst a pushbutton is depressed or a command in force. automatic mode (focus_control = AUTOMATIC) The focuser is implemented as an absolute position servo and the setpoint entered using the focus position form of the command. The focus pushbuttons on the console or handset increment or decrement the setpoint and the focus position is continuously servoed to that value. compensated mode (focus_control = COMPENSATED) The compensated mode is identical to automatic mode except that the encoded focus position is first corrected for tube temperature using the law { }021 2/)( tttKFF Tencodeddcompensate −++= before the servo loop is closed.

KT and t0 are telescope database parameters and t1, t2 are the telescope secondary truss temperatures.

Standard Response Where the command is successful, the folowing message is output: [FOCCTL] Focuser set to mode If an invalid or extraneous parameter was supplied, the following message is output: [INVPARAM] Invalid command line parameter; command ignored If the mode parameter is missing, the system simply issues the informational message: [FOCINFO] Focuser state, configured mode, current position ±xxx.xx mm

1.5.1 List of telescope subsystems The separate subsystems and plant which comprise the 2.3metre telescope are tabulated below with their respective states or control values. Subsystems which are not integral to the main telescope axis servos or rotator drive are conventionally described as auxiliary systems. The subsystem name telescope_systems is used to facilitate overall control of the telescope and plant control electrics/electronics and is the means of switching on and off and resetting the entire telescope control system.

subsystem permissable state or option parameter for set command reset command console on off telescope_systems on off yes * building_drive yes servos yes scbr 75 yes ventilation_fans on off lighting safe unsafe mirror_cover open closed building_shutter open closed tertiary_mirror_drive nasmyth_a nasmyth_b stowed rotator_selection nasmyth_a nasmyth_b cassegrain

on off flatfield_illumination

brightness (percentage of full-brightness required)

* A telescope_systems reset operation involves a complex sequence of timed operations.

1.5.2 Abbreviation of subsystem names The abbreviation rule for subsystem names is more relaxed than for other command elements: any of the subsystem names used in the set, open, close or reset commands may be abbreviated by any n ≥ 2 characters

75 The shutter-closed-by-rain signal is latched at the 2.3m console and must be cleared explicitly by the observer.


which uniquely match a string of n consecutive characters anywhere in the subsystem name. Thus mirror_cover may be abbreviated to cover or cov. The state or option parameters may be abbreviated by any unique string of two or more characters from the start of the option string (eg cassegrain may be shortened to cass or ca)

1.6 Commands for information/status retrieval daylight selects whether daylight saving is applied to the local timezone diagnose runs a diagnostic program to test all telescope system hardware display controls the console display in the 2.3m control room help provides help information for TCS commands iers retrieves IERS bulletin-A containing earth rotation parameters view lists the value of a display variable or database quantity daylight (priv=engineering) Synopsis daylight_saving [on|off] Description The telescope system sets the local timezone according to whether the file $MSOTCS_CONFIG/DAYLIGHT_SAVING exists. The presence of the file is used during startup to set the daylight_saving flag and the time zone data time_zone_name and zonal_correction in the database. The command daylight_saving on creates a file of that name if it does not already exist. The command daylight_saving off deletes the file $MSOTCS_CONFIG/DAYLIGHT_SAVING. The command verb may be substantially abbreviated if desired and (if syntactically correct) always succeeds. The setting will not take effect until the next time the TCS is started up.

Parameters The optional parameter may take the value on or off. If it is omitted, no change is made to the DAYLIGHT_SAVING file but the current timezone information is reported.

Standard Response If the parameter on was present, the following string is output: [DAYLIGHT] Daylight-saving set, new timezone will be XXXX If the parameter off was present, the following string is output: [NODAYLIGHT] Daylight-saving turned off; new timezone will be XXXX If the bare command is entered with neither parameter on or off present, the following string is output: [TIMEZONE] Daylight-saving = TRALSE timezone = XXXX zonal-correction =±XX hours If there are parameters present other than, or in addition to, on or off, the following string is output: [INVPARAM] Invalid command line parameter; command ignored diagnose (priv = observer) Synopsis diagnose Description Invokes a telescope system test procedure to fully test the telescope “hardware”. The procedure reports on any faults or abnormalities in the telescope and plant. It outputs messages which may `include suggestions of actions the user can take to correct any problems; finally it writes a single summary message as described below.

Parameters


None. As soon as the command is accepted, the system silently calls exec_diagnostic_test to test all of the telescope hardware. If, in the process of testing the various telescope and plant subsystems, it detects malfunctions or faults, the system issues individual diagnostic messages; these are not specified here. At the end of the procedure a final summary message is output which is one of the following: [TELSYSOK] TELESCOPE SYSTEMS FUNCTIONING AND READY FOR OBSERVING. [TELMTNPOSS]Test completed – telescope systems abnormal but observing may be possible, see diagnostic messages. [TELSYSFAIL] Test sequence failed – TELESCOPE SYSTEM UNUSEABLE. display (priv=observer) Synopsis display screen display hide display show Description Selects the screen to be displayed on the console display monitor in the control room of the 2.3metre telescope. The QNX6 TCS control computer maintains a number of screens of telescope information which can be selected either from the command line (using this command) or by using the mouse or pointing device to select the appropriate tab. The display is updated every 500ms synchronized to the UTC second and the screen displayed may be chosen from:

1 main primary screen used by observers; telescope state and tracking object data 2 object data for the current science object 3 config observer's configuration settings 4 aper/beam/ppb aperture, beam and programmable pushbutton configuration 5 status telescope and subsystem status 6 guide autoguider state and control data 7 metsys current meteorological data 8 error_graphs stripchart graph of telescope RMS tracking errors in realtime 9 messages TCS system messages 10 timing engineering screen with process and task execution times 11 axes engineering screen with tracking, motion control and servo data 12 files user file directory ($MSOTCS_DATA) listing and file listing utility 13 privilege utility to allow change of user privilege (observer/engineering) from a QNX login

Unlike the existing VAX/VMS display, the display screen contents are not programmable but contain a static group of variables. As far as an observer is concerned, this command is useful only when observing at a terminal physically located in the telescope control room on level 4. Its purpose is to manage the native TCS display or to allow the console functionality to be set from a script; the command cannot be used to configure the user's TCS GUI at the TAROS level. The contents and format of the display screens is not specified here.

Parameters The parameter screen takes one of the screen labels given above; alternatively it may be an integer in the range 1 to 13. No error message is issued if an integer outside this range is input – the screen simply defaults to main. Two additional keywords allow an engineering user to manage the QNX console environment: If the keyword hide is present, the system banishes the TCS display window to permit access to a login or other dialogue box (which will have been obscured by the TCS display starting up). This allows an engineer with the appropriate password to log into the TCS QNX machine. The keyword show restores the TCS display with the currently active tab. When the display is banished, a small minimized icon remains in the top lefthand corner of the screen; the TCS display can also be restored by using the mouse to select this Restore TCS Display icon.

Standard Response The following string is output: [DISPLAY] Telescope console display set to screen


If an invalid screen designator is supplied or an index which is out of range, the following string is output: [DISPLAYERR] Selected console display screen is invalid or does not exist

help (priv=observer) Synopsis help [command] Description The command help returns a simple list of telescope command verbs. Alternatively it may be used to obtain a synopsis of a specific command.

Parameters The optional parameter command may be any of the available MSOTCS command verbs. The command verb may be abbreviated to any contraction which is unique with respect to the command set. If the parameter is omitted, a list of all available MSOTCS commands is output.

Standard Response If a valid parameter command was present, a string giving the synopsis for that command is output; for example: [HELPCMD] beam (privilege = observer) beam A|B|C [guide|noguide] [wait] beam show beam beam define A|B|C coord-spec [guide coord-specg expose time win bin] beam define A|B|C offset ∆ra ∆dec [guide ∆rag ∆decg expose time win bin] beam clear A|B|C beam clear all Standard Response If command does not match any available MSOTCS command, the following string is output: [CMDUNKNOWN] Supplied verb is not a valid telescope command If the parameter command is not unique, the following string is output: [CMDAMBIG] Supplied command verb is not unique If no parameter was present, a list of available MSOTCS commands is output; [CMDDATA] The following MSOTCS commands are available: ... (This command list is not specified here) iers (priv=engineering) Synopsis iers [show] Description Engineering personnel are responsible for ensuring that a current IERS bulletin-A76 file exists in the system. This is used to maintain data for polar motion, ∆UT1 and ∆AT needed for telescope pointing. The command iers performs the following sequence of operations: (i) An attempt is made to access the site maia.usno.navy.mil; (ii) the file $MSOTCS_CONFIG/IERS_bulletin_A.txt is renamed to IERS_bulletin_A.old; (iii) the required file is retrieved by htttp: http://maia.usno.navy.mil/ser7/ser7.dat; (iv) if the file is transfered succesfully, it is renamed to $MSOTCS_CONFIG/IERS_bulletin_A.txt.

Parameters If the qualifier show is present, no attempt is made to access the site; instead the date of any existing IERS bulletin-A file is returned.

Standard Response 76 The International Earth Rotation Service publishes Bulletin-A weekly.


Upon successful return, the following string is output: [NEWIERS] IERS bulletin-A downloaded: dd MONTH yyyy If the site cannot be reached the following string is output: [IERSSITE] IERS data site URL not reachable, IERS file not changed If there is an error in transfering the file, the following string is output: [IERSFTP] HTTP error in transferring file full-path, IERS file not changed If the qualifier show was present, the following string is output: [CURRIERS] Current IERS bulletin-A file is dd MONTH yyyy If for any reason the file cannot be transfered successfully, the saved text file is retored to its original name. view (priv = observer) Synopsis view variable-name [continuous] Description Lists the value of a scalar variable or parameter in the TCS database. Not all of the TCS data are accessible by this command. The data type, which may be enumerated type, boolean, double or integer, is automatically recognized by the system and formatted appropriately. Numeric variables are output in "engineering" format.

Parameters The qualifier variable-name is interpreted generously; if it is does not uniquely specify a database variable, then all variables which commence with the string or which contain the string as a morpheme are listed. If the qualifier continuous is present, the same variable is repeatedly accessed and listed at intervals of one second.

Standard Response Upon successful return, the following string is output: [VIEWDATA] variable-name = value If the variable cannot be recognized or is not one which is accessible, the following string is output: [XVIEWVAR] This database variable does not exist or cannot be viewed ____________________________________________________________________________________________


2.

rsaa 2.3 metre telescope observer's manual a preliminary...

Documents