1. Introduction
2. gshow, show, modify, and xshow
3. Observer scripts
   • The list of commands
   • Accessing your scripts
   • Scripting tips
4. Facility scripts
   • Script outline
   • Introduction to vi
   • Introduction to Unix
   • Checking logs

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. gshow, show, modify, and xshow

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:

There are other options with these commands, especially xshow. We will not go into detail on these.

Note that in NIRC2 there are two separate keyword libraries to control the instrument: alad and nirc2. 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.

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 a waikoko-new 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

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

/home/nirc2/vis/your_name

cd /home/nirc2eng/vis
mkdir your_name
cd your_name

chmod a+rwx *

To add your personal scripts to the default path and make them easily accessible, type:

user your_name

rehash

user -d your_name

If you add new scripts you may need to type:

rehash

3.3 Scripting tips

You can script in any language you want, but C-Shell (csh) is powerful, and you have many examples of scripts in the facility scripts. Some general tips for writing csh scripts are provided in the following paragraphs.

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

tint

sampmode 2

sampmode

Math

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

math

expr

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

echo 2 \* 3 | bc

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"

Of course, variables can be passed by reference as well:

math $deltaX x 3

math - $deltaX

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:

getenv()

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

set list = ("object" "observer" "itime" "coadds")

set list = ($list "frameno" "camname" "filter")

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

Interrupt control

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

onintr

onintr 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

ls -lt | head -2 | tail -1 | awk '{print $4}'

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

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

help

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

camera -h

help camera

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

General

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^
    

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

Baackground and foreground tasks

In any program, typing a Ctrl-Z, puts the program in background mode, stops its execution and returns you to the Unix C-shell.

Typing fg at the terminal 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 terminal prompt immediately while the program is running on the background.

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

4.4 Checking logs

Analyze the log file after a motor test. To find all the raw positions:

tail -1000 /sdata900/logs/nirc2log | grep "RAW"

tail -1000 /sdata900/logs/nirc2log | grep "RAW" > /home/nirc2eng/test7.txt

tail -1000 /sdata900/logs/nirc2log | egrep "STALL|RAW"