NIRC-2: How to Add New Keywords

This "how-to" guide explains how to add new keywords that do not have any functionality beyond being accessible for "show," "modify," and related commands. In other words, this will not cover how to create a new keyword that drives a filter wheel, for example.

Note that there are already some placeholders for "user variables": USERVAR1 through USERVAR10, USERFLT0 through USERFLT2, USERINT0 through USERINT2, USERSTR0 through USERSTR2, and USERAVAR, USERDVAR, and USERMVAR. However, long term solutions may require creation of keywords with more descriptive names.

Add the new keyword

Select a reasonable, at least somewhat intuitive name for the keyword. Since FITS headers can generally only accept keywords of 8 characters or less, you might want to restrict the keyword name to this length. As an example, we want to create a keyword that will let us tell the filter scripts to close the shutter before moving the filter wheels, and then restore it to its original state once the filter move is done. We will keep to eight letters and call the new keyword "SHTRFILT."

To add this new keyword, log onto waikoko as nirc2eng, and edit

/home/nirc2eng/motor_config/nirc2_config_file

It may help to expand the width of your screen, since the lines in this file are typically longer than 80 characters. In this file you will see a list of keywords, descriptions, etc. You will create a new entry for SHTRFILT. Generally you will try to find an appropriate set of related keywords and place the new keyword near them, in order to maintain some sense of order in the file. In our case, since this is a filter-related keyword, we will search for other filter-related keywords. In fact, we choose to put the new keyword just above the "Inner filter wheel keyword" block, below the wavelength-related filter keywords such as EFFWAVE.

We will add the following lines below the "EFFWAVE" line:

#
# The SHTRFILT keyword allows the "filter" script to close the shutter while changing filters.
#
SHTRFILT        Close_shutter_during_filt_moves F       #       #       integer Motor   rw

This tab-delimited line contains the following elements:

SHTRFILT
The keyword name.
Close_shutter_during_filt_moves
A description (no spaces allowed).
F
A "save flag".
#
A flag that indicates whether to include the keyword in the image headers. We have chosen not to include this keyword. If we wanted to include it we would have typed an H (for "header") here.
#
A units string. A # here indicates that there are no units. You will notice that the EFFWAVE keyword above this has "microns" as its units. Again, no spaces allowed.
integer
The type of the keyword, in this case an integer. (We expect to set the SHTRFILT keyword to either "0" or "1" in practice.)
Motor
The "class" of the keyword. For general, nonfunctional keywords like we are creating we use Motor here to tell the keyword library that this is a general keyword stored in the "motor" daemon.
rw
This tells the keyword library that this keyword is both readable and writable.

Test the new keyword

Hard to believe, but that is all that is required! Test out the new keyword by first modifying it. (A "show" command at this point will fail, because the variable has not been initialized yet. We will fix that in a minute.)

modify -s nirc2 shtrfilt = 0

Now read back the keyword:

show -s nirc2 shtrfilt

Add an initialization value

Because you need to set the variable before you can read it back, you will want to add an entry into another file so that SHTRFILT will have a default value upon startup. That way a "show" command will not crash, it will simply return the default value.

Think a bit about what default value you should use. In our case the standard operating practice for NIRC-2 is to not close the shutter when changing filters. If this practice changes in the future, it is easy to return to the initialization file and change the default value. We will use "0" to represent this state of not closing the shutter during a filter change, and "1" to represent the state of closing the shutter during such moves. So our default value should be "0".

On waikoko as nirc2dev (not nirc2eng, now), edit the file:

/kroot/kss/nirc2/mech/keyword/nirc2_motor_defaults_script

This consists of a series of lines containing default values for a large number of keywords. Since we placed SHTRFILT just after EFFWAVE in the original file, we will add its default value after EFFWAVE's in this file. Find the line containing EFFWAVE, and add a new line below it:

set_prop_string SHTRFILT 0

This sets the default value of SHTRFILT to 0. Whenever the "motors" daemon is started anew, SHTRFILT will have this value.

You are now done creating a new NIRC-2 keyword! It remains to you to create the new script(s), GUI(s), or other device that will give this keyword some value to the observer, technician, or engineer.

Go To:
Instruments Home Page		Keck Home Page		Observer's Reference Shelf

NIRC2 Master
20 August 2002