path: root/pkg/language/doc/params.hlp

.help parameters Feb86 language
.ih
NAME
parameters -- IRAF parameters and their usage
.ih
DISCUSSION

1. \fIIntroduction\fR

    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. \fIParameter Types\fR

    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.

.ls 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 \fIlength\fR 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.
.le
.ls 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.
.le
.ls 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.
.le
.ls bool
Boolean parameters may only have the values \fIyes\fR or \fIno\fR.
.le
.ls 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 \fIfile\fR type parameter
is used at runtime.
.le
.ls 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.
.le
.ls 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 \fIhelp cursors\fR.
.le


3. \fIList-Directed Parameters\fR

    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.

.nf
	int	*list = "listfile.lis"
	int	cur_val

	for (i=1;  i < nlist;  i+=1) {
	    cur_val = list
	    analyze (cur_val)
	}

.fi

A common usage of struct list-directed parameters is to read files in
conjunction with the \fIfscan\fR function.  The following example prints
out a file.

.nf
	struct	*slist = "filer.lis"
	struct	line

	while (fscan (slist, line) != EOF)
	    print (line)
.fi


4. \fIModes\fR

    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. \fIRanges\fR

    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 \fIeparam\fR, 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. \fIParameter Attributes\fR

    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.

.ls p_name
The name of the parameter.
.le
.ls p_type
A string indicating the basic type of the parameter:

.nf
	b	-- boolean
	i	-- int
	r	-- real
	s	-- string/char
	f	-- file
	struct	-- struct
	gcur	-- graphics cursor
	imcur	-- image cursor=
.fi
.le
.ls p_xtype
This is the same as p_type except that the string is prefixed by "*"
if the parameter is list directed.
.le
.ls p_mode
A string indicating the mode of the parameter composed of the characters:

.nf
	q  --  query
	a  --  automatic
	h  --  hidden
	l  --  learned
.fi
.le
.ls p_value
The value of the parameter.  For a list-directed parameter this is a
element in the file, not the file name.  Generally this is what is accessed
when the parameter attribute is not specified.
.le
.ls p_length
For string type parameters (i.e. char, struct, file, gcur, imcur),
the maximum length of the string.
.le
.ls p_mimimum
The minimum value for a parameter.  Also for enumerated strings
the enumeration list.
.le
.ls p_maximum
The maximum value for a parameter.
.le
.ls p_filename
For list-directed parameters the file name associated with the parameter.
.le


Attributes may appear on either side of an equals sign, e.g.

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

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. \fIArrays\fR

    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,

.nf
	real x[20,20], y[20], z[10,20], t[20]

	y = x[1,*]
	t = log(y)
	z = x[1:10,*]
.fi


8. \fIScope\fR

    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. \fIStorage\fR

    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.
.ih
SEE ALSO
lparam, eparam, cache, unlearn, update, cursor
.endhelp