diff options
Diffstat (limited to 'pkg/language/doc/params.hlp')
| -rw-r--r-- | pkg/language/doc/params.hlp | 288 |
1 files changed, 288 insertions, 0 deletions
diff --git a/pkg/language/doc/params.hlp b/pkg/language/doc/params.hlp new file mode 100644 index 00000000..d0ebed8d --- /dev/null +++ b/pkg/language/doc/params.hlp @@ -0,0 +1,288 @@ +.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 |