1. Introduction
Parameters are the primary means of communicating information between the user and IRAF tasks, and between separate IRAF tasks. Each user effectively has their own copy of the parameters for the tasks they run, and by tailoring these as they wish, they may customize the IRAF environment. Here we describe characteristics of IRAF parameters. The syntax of parameter declarations is described elsewhere.
2. Parameter Types
The CL supports a variety of parameter datatypes, from the conventional string, integer, and floating point types, to the exotic struct and cursor types. There is no complex type in the CL.
char
Character parameters are used to store strings of ASCII characters.
By default character parameters have a maximum length of 64 characters,
but this may be extended using the length option when the parameter
is declared. A character parameter consisting of a single character can
usually be treated as an integer, with a value equal to the ASCII value
of the character.
int
Integer parameters are used to store integer information. Integer parameters
are stored internally as a long integer, permitting at least 32 bits of
precision.
real
Real parameters are stored internally as double's.
In general they may be entered with or without a decimal point,
and with or without an exponent. Note that the exponent should be
entered using an E not a D.
bool
Boolean parameters may only have the values yes or no.
file
File parameters are basically character parameters which are required
to be valid file names. All operations legal on characters are legal
on file parameters. Various checks on the accessibility or existence
of a file may be automatically performed when a file type parameter
is used at runtime.
struct
Struct parameters are characters strings which are treated specially by
the scan and fscan functions. Scan and fscan set structs to the
remainder of the line being scanned without further parsing.
gcur, imcur
The cursor parameters have a character string value with a predefined cursor
value format. When a cursor type parameter is read in "query" mode, the
hardware cursor on the graphics terminal or image display is physically read.
If the cursor parameter is list-structured, cursor input may also be taken
from a list (text file). For a more detailed discussion of cursor control
in the CL, type help cursors.
3. List-Directed Parameters
Frequently one may have a list of values, e.g. numbers or file names, which one wishes to analyze in turn. To do this one may use a list-directed parameter. The parameter is defined with its value field set to the name of a file containing the list. The next time it is referenced its value will not be the string containing the file name, but rather the first value in the list. Subsequent calls will return later values in the list until an end-of-file is reached, at which point the parameter will appear to be undefined. The file may be rewound using the p_filename attribute of the parameter. Assigning the null string to a list parameter closes the associated list file.
int *list = "listfile.lis"
int cur_val
for (i=1; i < nlist; i+=1) {
cur_val = list
analyze (cur_val)
}
A common usage of struct list-directed parameters is to read files in conjunction with the fscan function. The following example prints out a file.
struct *slist = "filer.lis" struct line while (fscan (slist, line) != EOF) print (line)
4. Modes
The mode of a parameter determines two qualities: whether the parameter is prompted for when it is accessed, and whether the parameter is "learned", i.e. whether its value is saved between invocations of a task.
A hidden parameter is never prompted for unless it is undefined or has an illegal value. A query parameter is prompted for every time it is referenced, except that a query parameter which is set on a command line is not queried for when it is accessed within that task.
These are the two basic modes, but a parameter may also be defined to be automatic. This means that the parameter will use the mode not of the task, but of the package the task is part of, or by the CL. When an automatic parameter is referenced the CL searches up this hierarchy to find a mode which is not automatic and uses this for the mode. If the mode switch at all levels is automatic then the mode is set to hidden. The mode switch at the task, package and CL levels is determined by the VALUE, not the mode, of the parameter with the name "mode" associated with the task, package or CL.
Query and automatic parameters are learned by default, while hidden parameters are not.
5. Ranges
The CL supports ranges for integer and real variables, and enumeration lists for character strings. A user may specify either or both of a minimum and maximum for numbers, and the CL will reject any values which fall out of this range. Range checking is only performed during querying, or inside eparam, not when a value is assigned directly. For an enumerated string the input string is matched against any of the enumerated possibilities using a minimum-matching technique. A value with no match is rejected.
6. Parameter Attributes
The user may access the different elements of a parameter using the parameter attributes. For some parameters certain of the attributes will be meaningless or undefined.
p_name
The name of the parameter.
p_type
A string indicating the basic type of the parameter:
b -- boolean i -- int r -- real s -- string/char f -- file struct -- struct gcur -- graphics cursor imcur -- image cursor=.le
p_mode
A string indicating the mode of the parameter composed of the characters:
q -- query a -- automatic h -- hidden l -- learned.le
p_length
For string type parameters (i.e. char, struct, file, gcur, imcur),
the maximum length of the string.
p_mimimum
The minimum value for a parameter. Also for enumerated strings
the enumeration list.
p_maximum
The maximum value for a parameter.
p_filename
For list-directed parameters the file name associated with the parameter.
Attributes may appear on either side of an equals sign, e.g.
list.p_filename = "test.fil" = str.p_length range = integ.p_maximum - integ.p_minimum list.p_xtype = = system.page.first_page.p_minimum # Fully qualified.
It is illegal to assign to the p_name, p_type and p_xtype fields. Most of the direct use of the parameter attributes is expected to be in systems level programming.
7. Arrays
The user may define arrays of arbitrary dimensionality within the CL. The arrays are referenced in the conventional fashion with the index list enclosed in square brackets, and the individual elements separated by commas. In their internal representation, arrays are similar to those in Fortran, with the first element changing fastest as one traverses memory. The limits of each index may be specified.
In general the CL can only access one element of the array at a time but there is an automatic looping feature which permits the appearance of array arithmetic. Any executable statement in which an array is referenced but in which the exact element of the array is not defined (an "open" array reference) will cause the CL to implicitly execute that statement within a loop over all the elements of the array. More than one "open" array may appear in the expression but they agree on the limits of the loop. For example,
real x[20,20], y[20], z[10,20], t[20] y = x[1,*] t = log(y) z = x[1:10,*]
8. Scope
A parameter is known via an implicit reference if the task in which it is defined is active. In an implicit reference the parameter name only, without a task or package qualifier, is given. The CL is always active, so that its parameters are always known. In a script, the script itself is active, so its parameters may be used implicitly. If the script calls another task, that sub-task may reference the invoking tasks parameters implicitly.
For an explicit reference, i.e. with task and package qualifiers, the parameter is known if the package in which the task is defined is active. For example, when starting the CL, the "lists" package is not active, thus the parameters of the "sort" task may not be referenced even in the form "lists.sort.param". However since the system package is activated during login to the CL, the parameters of "page" may be referenced by "page.param". In general a package qualifier is used only to remove ambiguity between tasks with the same name in two different packages.
9. Storage
There are several places in which parameters are stored. On disk the CL searches for the parameters for a task in three locations. For a procedure script, the default parameters are found in the script file itself, while other scripts and executables have a parameter file with defaults in the same directory as the script or executable. These default values are used the first time a task is run, or whenever the default values have been updated more recently than the user's copy of the parameters. The user's copy is created when a task terminates, and retains any "learned" changes to the parameters. It is created in a directory pointed to by the IRAF logical "uparm" which is usually a sub-directory of the default IRAF directory for the user.
The user may also use in-core storage for the parameters using the cache command. This keeps parameters for frequently used tasks available without requiring disk access. Cached parameters are copied to disk when the CL exits, or when the update command is used.
lparam, eparam, cache, unlearn, update, cursor,