1. Introduction
  2. Show, modify, xshow and tshow
  3. Observer scripts
  4. Facility scripts

1. Introduction

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.

2. Show, modify, xshow, and tshow

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.

3. Observer scripts

3.1 The list of commands

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
    filt h
    tint 8

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.

3.2 Accessing your scripts

Users should keep their scripts in their own subdirectory within

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
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:

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.

3.3 Scripting tips

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:
will return the current value. Typing:
      offset 3000 3200 3120 3030
will set the four offsets for the four quadrants of the detector, while:
with no arguments returns the current values.


Math in the shell is painful. To make it somewhat easier, a command called:

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:
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.

Image math

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:

to read these parameters. See one of the scripts in $FAC_SCRIPTS/pro for an example.

Repetitive tasks

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...
      xy `math $xoff[$i] x $dX` `math $yoff[$i] x $dY`

Interrupt control

Sometimes you need to protect something against a premature end of the script by a Ctrl-C. Use the:

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

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.

4. Facility scripts

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.

4.1 Script outline

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:
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:

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.

4.2 Introduction to vi

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.

4.3 Introduction to Unix


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

      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."


      * is a general wildcard expansion.

      Characters in brackets [] are subsituted individually in a wildcard

      Characters in braces, {}, are subsituted in comma-separated pairs
      in a wildcard expansion.
      * [] and {} are use in wildcard expansions as illustrated

      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

      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.)

Baackground and foreground tasks

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

Quick directory changes

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

              pushd can be used to quickly switch back and forth between two

      popd    pops the top directory off the stack and puts you in the next
              directory down.

4.4 Checking logs

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