The software for NIRC2 is for the most part a command-line interface (CLI). Commands are wrappers for keywords (described below), and the facility scripts provide for basic functionality of the instrument, and some level of interaction with the telescope and AO systems. The CLI is designed to allow relatively easy creation of user scripts, to accomodate observers' unforeseen needs.
Keywords are essentially external hooks into the functionality of the instrument software, the latter generally written in C. At the very basic level, there are three commands that allow access to keywords. Show will return a keyword value, modify will change it, and xshow will monitor it. tshow is a graphical version of xshow, plotting the changes in keyword value as a function of time.
Some examples will show how these commands are used:
| show -s nirc2 camera | Shows the current value of the CAMERA keyword. The "-s nirc2" specifies the "service" name, or the keyword library in which the requested keyword exists. In this case the service name is nirc2, which is where the CAMERA keyword lives. |
| modify -s alad itime=10 | Sets the current value of the ITIME keyword to 10. In thijs case the keyword lives in the alad keyword library. |
| xshow -s nirc2 camera filter slitname | Creates a text "GUI" with three entries for the CAMERA, FILTER, and SLITNAME keywords (all in the nirc2 keyword library). |
| tshow -s dcs raoff | Produces a graphical display showing the value of the DCS keyword RAOFF. |
| show -s nirc2 -terse camera | Returns only the camera name, rather than "camera = " followed by the camera name. This is a useful form in scripts, so that you do not have to extract the value from the line returned by a "show" command without "-terse". |
There are other options with these commands, especially xshow. We will not go into detail on these; see documentation elsewhere.
Note that in NIRC2 there are three separate keyword libraries for the instrument: alad, nirc2, and pmr. The alad keywords handle interaction with the detector, including setting detector parameters and taking images. The nirc2 keywords handle communications with the motors and temperature sensors. The pmr keywords interact with the pupil rotator.
Three other keyword libraries are important: the dcs keywords control telescope functions, acs keywords control the primary mirror, and ao keywords control functions within adaptive optics.
As mentioned, the simplest user script is a file containing a list of commands that the user would normally type on the command line. For instance:
filt k
tint 10
goi
filt h
tint 8
goi
will insert the K filter, change the integration time to 10 seconds, and take an exposure. It then changes to the H filter, changes the integration time to 8 seconds, and takes a second exposure. This is the exact sequence of commands that the user would have entered on the command line to do the same functions. Note that this script does not have an initial:
#!/bin/csh -f
line. It will run in whatever shell is currently being run by the
user (usually tcsh). It is often best to explicitly define the
shell in the first line, however, in case you have changed your
environment in some way that will cause your script to fail.
More complex scripts may include looping, decision-making, and branching, logging to a file, and so on. Users are also encouraged to include comment lines in their code, and even syntax checking using syncheck. See the facility scripts section for examples of how to do this.
Users should keep their scripts in their own subdirectory within
~nirc2/vis
Get to this directory using:
cd ~nirc2/vis
mkdir your_name
cd your_name
You should be able to edit your script in that directory. Note
that you will have a numbered account assigned to you when you come
to observe, and the files you create will be owned by that
account. When you return for a second NIRC2 run you may have a
different numbered account assigned. However the files you create
should still be editable as the new user. If not, you can log in as
your old user name, cd to the appropriate subdirectory, and type:
chmod a+rwx *
to give read, write, and execute permissions to all
other users. Then exit as that old user and you should now be able
to edit your files.
To add your personal scripts to the default path and make them easily accessible, type:
user your_name
where your_name is your subdirectory name. This will
add ~nirc2/vis/your_name to the PATH environment
variable, and does a UNIX
rehash
command to make sure they are visible. Note that if you type in a
directory that does not exist, the script will ask whether you want
to create it. Make sure you have not made a typo; otherwise feel
free to create your directory initially using this technique. If you
ever want to remove your subdirectory from the PATH, type:
user -d your_name
where again your_name is your subdirectory name.
If you add new scripts you may need to type:
rehash
in your command window. This tells UNIX to search its PATH again
for executables; otherwise it uses a cached list from either the
last rehash command, the last user command, or the point
at which you created the command window.
You can script in any language you want, but the csh shell is powerful, and you have many examples of scripts in the facility scripts. Some tips for writing in the csh shell are provided in the following, but you may also want to keep a UNIX or csh manual handy for detailed questions.
Following the generic help block comes the functional part of the code. In general variables used in the script are set near the top. Usually there is an if block that checks for the correct number of parameters. Often the number of parameters can be variable, with missing parameters set to some default value. Also, in general if the command sets a single parameter, or sometimes a number of parameters, if the command is typed with no arguments the current settings of those parameters is printed. Hence typing:
tint 1
will set the exposure time to 1 second, while typing:
tint
will return the current value. Typing:
offset 3000 3200 3120 3030
will set the four offsets for the four quadrants of the detector,
while:
offsets
with no arguments returns the current values.
Math in the shell is painful. To make it somewhat easier, a command called:
math
has been written as a wrapper around the bc math
command. bc does floating point math, although often if
integers are used as arguments, integers are returned. For purely
integer arithmetic:
expr
can be used.
The math command replaces all x characters with *, which means multiplication to the bc'' command. This allows the use of constructs like:
math 2 x 3
to be used for multiplication, rather than:
echo 2 \* 3 | bc
Note that in the latter representation the asterisk must be
escaped as it is a special shell character.
Other special shell characters can be problematic, but many of these (including *) can be protected by placing double quotes, "", around the expression. Hence:
math "(2*7 + 3 x 4)/0.123"
will protect both the asterisk and the parantheses, which
are special shell characters. Note that the spacing around
charecters is relatively arbitrary.
Of course, variables can be passed by reference as well:
math $deltaX x 3
will return three times the
variable deltaX. Taking negative numbers is
straightforward:
math - $deltaX
will return the opposite
of deltaX. Transcendental functions are also
possible. See the man page on bc for details.
Generally the facility scripts use IDL to perform array manipulation. Arguments are passed through environment variables, including file names. The IDL scripts which are called then use:
getenv
to read these parameters. See one of the scripts in
$FAC_SCRIPTS/pro for an example.
Doing repetitive tasks, such as looping through a dither script or running through a list of parameters, usually involves setting up a list variable. This list can be contained within a foreach command:
foreach keyword ("object" "observer" "itime" "coadds")
or within a variable:
set list = ("object" "observer" "itime" "coadds")
In the latter case items can be easily appended to the list:
set list = ($list "frameno" "camname" "filter")
and the list can be used in a foreach statement:
foreach key ($list)
Dither scripts, in particular, use a repetition of mov and goi commands. The facility scripts usually set a single parameter to be the step size, in arcsec. Then a list containing multipliers for the step size determines the positions on the sky for each dither:
set dX = $1
set dY = $2
set xoff = ( 1 -2 0 2 -1)
set yoff = (-1 0 2 0 -1)
foreach i (1 2 3 4 5)
echo ""
echo Position $i of 5...
goi
xy `math $xoff[$i] x $dX` `math $yoff[$i] x $dY`
end
Sometimes you need to protect something against a premature end of the script by a Ctrl-C. Use the:
onintr
command for this.
onintr label
sends the script to the specified label if a Ctrl-C is
typed any time after the onintr statement. Following this label is
generally some type of cleanup operation: returning the telescope
to the starting point of a dither pattern, resetting keywords that
have been changed by the script and must be changed back before
the script exits, etc. Sometimes the script during normal
execution will fall through this same code, and sometimes it will
exit before it gets to the label.
Note that if you Ctrl-C in a script called by a higher-level script, the low-level one will trap it, respond if necessary, then send that Ctrl-C back up to the higher level script. So if you write a user script that calls the goi script to take images, if you Ctrl-C during an exposure the goi script will ask whether you want to abort the current exposure or not. Then once the goi script has completed, it will pass the Ctrl-C up to your script. If your script does not have a Ctrl-C trap in it, it will continue executing the next line of the script. Otherwise it will branch to the label defined in your:
onintr label
command.
Typically you would set the interrupt control before changing anything that needs to be changed back, be it telescope position or keyword values.
One important tip; it is generally easiest in the shell to build up commands by starting with the core of a command and adding filters and other bells and whistles one by one, testing that you get the desired output at each step. For example, if I wanted to find the size of the most recent image taken in the current directory, I would start with the command ls -l. Then I might add the flags that tell the command to order the output by time: ls -lt. Next add the commands to only keep the second line:
ls -lt | head -2 | tail -1
Add the command to pull out the size from that line:
ls -lt | head -2 | tail -1 | awk '{print $4}'
and so on.
Provided as the main user interface is a set of scripts, predominantly csh shell scripts, that are another layer on top of the keywords. They range from scripts that control one keyword, to complex scripts that control much higher level functions like setting up for spectroscopy. Scripts which require image math call IDL to do the array arithmetic.
For a shell script it is good practice to specify the shell or other program that is meant to run the script. This is done in the very first line, which starts with a "#" sign, a "!" sign, and then the path to the shell or program, plus any options. For the facility scripts, which are predominantly designed for the csh shell, the first line looks like:
#!/bin/csh -f
The -f option simply tells the csh shell not to
rerun the user's .cshrc file, and speeds up the script
somewhat.
It is useful to document your script, so that you will understand what it is used for when you come back to observe later on. We suggest that you insert a header which contains a description of the program's usage and functionality. For example:
#+
#
# camera [text]
#
# sets the camera to "text". If no argument is specified, the current camera is returned.
#
#-
The # sign is used as the first character of each
line so that the shell does not try to interpret this header as
shell commands. The first line of this block is normally
#+, which is used by the help command to
define the comments which should be printed out by:
help
command. #- defines the end of this help block. If the
help command does not see a #+ line, it will print out
all comment lines contained in the script.
Next follows a line containing the command and its arguments. Square brackets usually mean optional arguments; in this example you do not need to specify a camera name. After the usage line follows a description of the command and its options. Finally comes the #- line signalling an end to the help block.
In most facility scripts there follows some boiler plate to allow
command -h
to invoke the help command script. So typing:
camera -h
has the same effect as typing:
help camera
namely to print out the initial help block of comments.
Next follows some boiler plate that uses the syncheck syntax checker. The syncheck call is of the form:
set CheckStatus = `syncheck -command $0 $* -pattern {text}`
The -command $0 $* part passes the command typed by the
user. This gets compared to the pattern, which will vary from
script to script. In the example shown the script expects either
no arguments or a single optional text argument. The curly
brackets around text in the syncheck line tell syncheck
that the text is optional. If syncheck detects a syntax error it
will print out what it thinks is wrong, plus the pattern it
expects to find. The boiler plate in the script generates
a help command to aid the user in understanding what was
typed incorrectly.
Note that the boiler plate for the command -h and syncheck is located in a file:
/kroot/kss/nirc2/scripts/info/help.inc
The command -h boiler plate is generic and should not
need to be changed. The syncheck boiler plate allows for any
number or types of arguments to be passed, making it transparent
to any script in which it is pasted. However, to make use of the
syntax checking you will want to define the "pattern"
that the script requires.
After the initial comment lines and boiler plate lies the body of the script, containing shell commands, other NIRC2 scripts, calls to IDL, or any of a variety of other commands.
A brief introduction to the "vi" (pronounced vee-eye) editor (which gets invoked when you compose a mail message in elm.
The central idea of vi is to never have to remove your fingers from the keyboard, not even to move them to the keypad. \There are basically two modes of operation: command mode (where you startup) and insert-text mode. You type "i" to go to insert mode. In this mode you type text until you have finished then press the escape key to go back into command mode. In insert mode, you can only type text and backspace over what you have typed. You cannot move the cursor around, etc. You have to go to command mode to do that. When in insert mode, it is best to end each line with a carriage return. Line wrapping is a function of the terminal and will be different on every terminal your message is read on. Your message will not print correctly also if you don't terminate each line with a carriage return.
Here are a few commands that work in command mode. (Note, commands are case sensitive):
i - go to insert mode.
a - append. go to insert mode but after the character immediately
to the right of the cursor.
A - append to the end of the line. Moves the cursor to the end
of the current line and enters insert mode.
ESC - leave insert mode and return to command mode or abort a command.
h - moves the cursor one character to the left
l - moves the cursor one character to the right
SPC - same as l
j - move the cursor one line down
k - moves the cursor one line up
RET - moves the cursor to the beginning of the text on the next line.
w - moves the cursor forward one word
b - moves the cursor back one word
control-f - page forward
control-b - page back
control-d - scroll down 1/2 page
control-u - scroll up 1/2 page
/ - search for text string. You type the text at the bottom
of your display. When you press return the text search
begins, the cursor will move to the first instance
of the search text *from the current cursor location*
or you will get a message saying "text not found."
If the current position of the cursor is near the end
of the file, the search will wrap back to the beginning
of the file.
n - move the cursor to the next instance of the search text.
x - delete a character
dd - delete a line
dw - delete a word
d$ - delete to the end of a line
cw - change a word (press the escape key to end the change)
c$ - change to the end of a line
yy - yank text. This copies a line of text to a buffer for
later use. This command is canceled by entering insert mode.
p - put text. This command inserts text that you've previously
deleted (with x or dd) or "yanked" with the yy command.
J - concatenates the next line of text to the current line of text.
. - Repeat the last command, or insertion.
ZZ - write the file to disk and quit.
Typing a number before you type the command will cause the command to execute that many times. Example: "20dd" will delete 20 lines of text. "20yy" will copy 20 lines of text to a buffer. The next "p" command will. insert those 20 lines of text beneath the cursor's current position.
There is another mode of operation I conveniently did not tell you about. If you type a ":" in command mode, the cursor will go to the bottom of your display, a ":" will be displayed and vi will wait for you to type a "command-line mode" command. After you type the command and a return, you will end up back where you were before you typed the colon. Here are a few command-line commands:
q - quit
q! - quit and do not save any changes
w - write the file to disk
nnn - typing any number will put the cursor on that line number
in the file.
$ - moves the cursor to the end of the file.
n - next file. If you are editing multiple files, typing "n"
loads the next file.
When you log into a Unix system you will be running a command-line user interface called a shell. Usually this is the C-shell (csh). There are others: the Bourne Shell and the Korn shell are common also.
On Unix files are organized in hierarchal directories. Each level of the hierarchy is separated by a forward slash. The very top level directory is called the "root" directory and is designated with a forward slash only. Examples:
/ The root directory
/usr The /usr directory
/usr/local/bin You get the picture.
/home/phobos/hlp hlp's home directory.
. Your current directory
.. Your current parent directory
You have a home directory which becomes your current working directory when you log in. You "own" this directory so you can create files inside of it. On most Astronomy computers, you also own a directory on the scratch disk, for example, /scr/hlp might be your directory on the scratch disk. Usually there is much more space on these disks than on the normal working disks and they are automatically cleaned. Files 6 days or older are automatically purged.
Putting a slash before a directory name tells the system to use absolute addressing, ie to search for the directory starting with the top-level root directory. Omitting the slash before a directory name tells the system to use relative addressing, or to search for the directory starting with your current directory. For example, using the "cd" command to change directories:
cd /usr sets your current directory to /usr, located in the root
directory.
cd usr sets your current directory to a directory named "usr"
located in your current directory.
The tilde, ~, is used to indicate a home directory, for example, the command, "cd ~rjb", would change your current working directory to the home directory of user rjb.
A file whose name begins with a period (.cshrc, .month, etc.) is called hidden file and does not show up in a "ls"-directory listing unless the -a option is used with ls.
The file .cshrc (pronounced dot-see-shrink) is your shell startup file and contains all the commands you wish to execute when you log in. Usually this means setting up your executable PATH and other environmental variables and defining your "aliases."
Wildcards:
* is a general wildcard expansion.
Characters in brackets [] are subsituted individually in a wildcard
expansion.
Characters in braces, {}, are subsituted in comma-separated pairs
in a wildcard expansion.
* [] and {} are use in wildcard expansions as illustrated
below:
ls * lists all files in a directory (except hidden files)
ls [cbvy]* lists all files which start with either c b v or y.
ls {ab,dv,qu}* lists all files which start with either ab dv or qu.
Command history: In the C-shell, previously-typed commands can be executed again using a command-history mechanism. The command "history" lists previous commands. Typing an "!" then the number of the command will execute that command again. Typing "!!" executes the previous command. again. Typing "!v" executes the most recent command that began with a "v." Etc.
The previous command can be changed by a substitution mechanism. It works like this:
^previous text^new text^
For example:
man abc The original command.
^abc^xyz^ Executes "man xyz"
Common Unix C-shell (csh) commands (Actually most of these commands are common to all Unix shells) (Type "man command_name" to get the full explanation for each command below):
cd change directory
ex: cd .. (change current working directory to the parent
directory 1 level up.)
cd ../../.. (change current working directory to the
parent directory 3 levels up.)
cd (change current directory to your home directory)
cd ~ (same as above)
cd ~cro (change current directory to cro's home directory)
mkdir create a directory
ls list the contents of a directory
ex: ls -a (lists all files including "hidden" files)
ls -l (long listing)
ls -F (show file types -- directory or executable)
ls -alF (all of the above)
ls -R (recursively list contents of a directory tree)
df display file systems -- reports free disk space and number of files
on each file system.
pwd print working directory
finger Display information about a user or users on local or
remote systems.
ex: finger (shows users on login system)
finger @mosfet (shows users on the system mosfet)
finger hlp@deimos (shows user hlp on the system deimos)
w what. Display information about other users on the system.
Similar to finger except only works on the system you're
logged into.
cp copy file
mv move file (rename)
rm remove file (delete)
cat concatenate a file and display (Same as "type" on other systems.)
ex: cat filename (lists the contents of the file on the terminal)
cat *.c > master.c (list the contents of all files in the
directory whose names end in ".c" into a new file called
"master.c")
more display a file's contents one page at a time. Can scroll up
and down.
tail display the last part of a file.
ex: tail filename (displays the last 10 lines of filename)
tail -20 filename (displays the last 20 lines of filename)
tail +20 filename (displays the last N-20+1 lines of filename,
ie start at line 20 and list the file. N
is the total number of lines in the file.)
spell check a file's contents for spelling (very basic -- just shows
you the incorrectly spelled word. Doesn't correct or suggest.)
look lookup words containing a character sequence (can help spelling)
man display complete description of a Unix command or name
diff display differences in the contents of two files
grep search file(s) for instances of a character string. Warning:
case sensitive.
ex: grep xyz *.c (search for "xyz" in all files whose name ends
in ".c")
grep "howdy pardner" * (search for the phrase "howdy pardner"
in all files in the directory.)
grep -i xyz *.c (same as first example but don't pay
any attention to case)
find search a directory path for a file
ex: find . -name filename -print (prints the full pathname of the
file named filename if it is found in the current path)
date display the system date and time
quota check a user's disk quota and status.
ex: quota -v hlp (displays the usage and quota for user hlp)
setenv set the value of an environmental variable.
ex: setenv PATH /bin:/usr/bin (sets the path that is searched when
you type a program name)
setenv PRINTER ps (sets your default printer name to ps)
printenv display values of environmental variables.
alias substitute another name for a command name.
ex: alias dir ls
alias type cat (RESIST the urge to use alias to make Unix
look like VMS or some other red-headed
stepchild of an operating system. You
chmod Change the permissions on a file.
ex: chmod 755 filename (makes filename an file executable by anyone)
chmod 400 filename (makes filename readable only by the owner)
chmod 600 filename (makes filename read/write only by owner)
chmod 666 filename (makes filename read/write by everyone)
Ok, ok -- it works like this: the number is an octal number
constructed from the OR of the following modes:
400 Read by owner.
200 Write by owner.
100 Execute (search in directory) by owner.
040 Read by group.
020 Write by group.
010 Execute (search) by group.
004 Read by others.
002 Write by others.
001 Execute (search) by others.
4000 Set user ID on execution.
2000 Set group ID on execution (this bit is ignored if
the file is a directory; it may be set or cleared
only using symbolic mode).
1000 Sticky bit, (see chmod(2V) for more information).
lpr queue file for printing (must be a postscript file)
lpr -s queue BIG file for printing (This version uses a symbolic link
to the file rather than copying the file to the spooler, so
do not modify the file while it is printing!)
enscript or
menscript queue a (text) file for printing.
ex: menscript -d ps -2r filename (prints filename in landscape mode
in 2 columns on printer ps. You have to use the
"-d printername" option in Solaris.)
In any program, typing a CONTROL-Z, puts the program in "background" mode, stops its execution and returns you to the Unix C-shell.
Typing "fg" at the C-shell prompt will put you back into the background program and resume its execution.
The command "jobs" lists the current background jobs.
Typing "fg %n" where n is the number of the job (from the "jobs" listing) will bring that program to the foreground, resume its execution and put you intoq it. (If it is interactive.)
Typing a command (or program name) with an "&" at the end of the command line will cause the command to be executed as a separate task. You will be returned to the C-shell prompt immediately while the program
It is possible to maintain a "stack" of working directories, using the commands "pushd" and "popd."
pushd pushes a directory onto the stack and puts you in that directory
pushd without any parameters will send you back to the original
directory.
pushd can be used to quickly switch back and forth between two
directories.
popd pops the top directory off the stack and puts you in the next
directory down.
Analyze the log file after a motor test. To find all the raw positions:
grep "RAW" /var/log/nirc2log
To save the result in a file:
grep "RAW" /var/log/nirc2log >~nirc2eng/data/test7
To print the file you saved:
mp ~nirc2eng/data/test7 | lpr
To find all the stall faults and all the raw positions::
egrep "STALL|RAW" /var/log/nirc2log