Libraries and Packages: The VOS Interface

2.1 Interaction with the cl -- clio


The
clio package allows an application to interact with the IRAF command language (cl). This includes mostly reading and writing cl parameters. In addition, there is a set of procedures for handling filename templates, lists of input files, as well as satisfying interactive graphics input (cursor position). Parameters in the cl may have a data type attribute as SPP parameters are typed. The SPP data type need not match the cl parameter's data type, however. The data type is silently converted by clio. The typed procedures returning cl parameter values refer to the data type of the SPP variables accepting the value of the cl parameter.

Ordinary Parameters

There is a separate read (get) and write (put) procedure for each SPP data type. All of the get procedures, except strings, are functions, returning the value of the cl parameter as the function value. Each function takes a single argument of type char, the cl parameter name. When the function is called, the cl will attempt to resolve the value of the parameter from a default in a parameter file or prompt for input from the standard input stream STDIN (see "Formatted I/O -- fmtio" on page 78). If the program is not connected to the cl (i.e., if it is run stand-alone), a prompt will be written to STDOUT and the value of the parameter is read from STDIN. In the case of string parameters, there is a get and put procedure, returning the string value in a calling argument.

Table 2.1: Parameter I/O Functions.

The procedures to read and write numeric parameters are implemented for each SPP data type: bool, char, short, int, long, real, double, and complex. Use the appropriate procedure by replacing T with the first letter of the corresponding data type, clgetr() for type real or clgeti() for type integer, for example. Note that the data type of the returned value need not match the parameter's data type. Implicit type conversion is done by clio.

The parname parameter is a char variable containing the parameter name. This may be a literal string, a predefined string parameter constant, or a character variable containing the desired string (which may also have been read with clgstr()). In the case of clgstr(), the additional parameter maxch specifies the size of the string parameter. The following example illustrates clio by reading several parameters from the cl.



Note the literal string constants for the parameter names and the predefined constant SZ_LINE specifying the size of the returned string. Also, note the distintion between the variable assigned a value in the code and the parameter as defined in the cl. There is no short data type in the cl, only integers. The procedure clgets() reads a cl parameter of any data type into a short variable. The cl parameter shortpar is declared as an integer but the variable sval is declared short.

Such a procedure implemented as part of a task may use a parameter file to specify attributes of parameters. This is a text file with a root name the same as the task name and an extension .par. The above example defines a task readcl whose parameter file would be called readcl.par, containing the lines shown in. See "Parameter Files" on page 171 for a more detailed description of .par files.

The clgwrd() procedure returns the value of an enumerated string parameter. This is a string parameter whose value may take on one of a list of possible values. The list of possibilities is specified in the parameter file in the minimum value field as a quoted string with values delimited by a vertical bar. For example the parameter color might permit the selection of several possible values. The definition in the parameter file might be:

color,s,h,"black","|black|white|red|green|blue|",,"color"
The cl uses minimum matching to determine the desired value from the smallest unique initial characters the user specifies for the string. You must specify the dictionary or the list of possible values to clgwrd() in the dictionary argument returns the full word in the keyword argument.

One pitfall is the potential mismatch between the enumeration string in the parameter file and the dictionary in the source. However, it is possible to read the enumeration string using clgstr() since it is possible to read the individual components of the parameter definition in addition to its value. The following would return the dictionary for the color parameter as defined above:

call clgstr ("color.p_min", colordict, SZ_LINE)
Where colordict is a string variable and would be used in the clgwrd() call:

call clgwrd ("color", color SZ_LINE, colordict,)

pset parameters

Any
cl parameter may be included in a pset. A pset is a set of cl parameters referred to as a group via a single parameter of a task. The pset itself is defined as a task in the cl and is defined by a .par file. In the SPP code, however, pset parameters are accessed identically to any other task parameter. While you may prepend the pset name to the parameter name, this is not necessary and not recommended.

List Structured Parameters

List structured or list-directed parameters permit a number of values to be accessed by an application from a file specified by name. The following procedures get list structured parameters from the cl. The first two return a status value which is EOF on reading at the end of file on the input. The clglpt() procedures return the value of the appropriate data type as the function value.



Table 2.2: List-Structured Parameter Functions.

The procedure represented by clglpT() reads a numeric list structured parameter and is implemented for the usual SPP data types: bool, char, short, int, long, real, double, and complex. It returns the value as the second procedure argument, whose data type should match the procedure. The function return value is an integer status that takes the value EOF upon reading after the last parameter in the list. The other procedure, clglstr() returns the length of the string read as the int function value, or EOF after reading the last string. For example, we may wish to read integer values from a list filename int_file.txt which contains the following:

1 
22 
333 
4444 
55555 
666666 
If we add the following statements to the program readcl in the previous section:

.

. 
while (clglpi ("intval", ival) != EOF) { 
    call printf ("integer value: %d\n") 
       call pargi (ival) 
} 
. 
. 
then the parameter file should have the following line:

intval,*i,a,"int_file.txt",,,"> List of integer elements"
Notice the additional flexibility to input data to a program; changing the input list filename gives you another set of values.

Vector Parameters

It is possible to access a group of parameter values using a single root parameter name. This provides the capability of vectors or arrays in cl parameters. The array structure, default values, ranges, etc. may be specified in the .par file as with scalar parameters. However, the syntax is slightly different. For example, the following declares a singly dimensioned real array having three elements.

vecreal,ar,a,1,3,1,,,"real vector elements", 0.0,1.2,3 
Note that the character a precedes the data type field, the next three fields specify the dimensionality, size, and starting index, and the default values are after the prompt string. The following code (
Example 2.3) will read the above values.

Note that the element number of the cl parameter vector is enclosed in square brackets following the parameter name and is part of the string passed to the clgetT() and clputT() procedures.

Interactive Graphics Cursor

The cl treats an interactive graphics input cursor read similarly to a list structured cl parameter query. When the user asks for a cursor position, either through a cl query or through a task, the cl issues a prompt which the user must satisfy with some action. In the case of a normal cl parameter, the user may type in the value of the parameter. For a cursor read (assuming a graphics terminal with cursor capability) the graphics enters graphics input (GIN) mode. The user may then move the cursor on the screen. To terminate graphics mode, the user types a key on the keyboard. This satisfies the query prompt and the cl returns the cursor position. The clgcur() procedure returns the next cursor value from a list structured cursor type parameter. The format of a cursor value is as follows:

x y wcs key sval
where

All of the fields need not be given, and extra fields may be supplied and will be either ignored or returned in sval. The x y, and wcs fields may be omitted, in which case the input is key sval, causing INDEF INDEF 0 key sval to be returned, exactly as if the INDEF INDEF 0 had been typed in. The number of fields read is returned as the function value; EOF is returned when the end of the cursor list is reached. Since the cl treats a cursor query as a parameter, the clio procedure clgcur() is used to perform interactive graphics input from an SPP task. Its calling sequence is:

call clgcur (param, wx, wy, wcs, key, strval, maxch)
 

Table 2.3: Graphics Cursor Parameters.

Note that the argument key is an int typed variable, not char as might be expected.

There are two flavors of cursor available through the cl: for vector graphics and image display. The cl data type of a cursor parameter may be either *gcur for a graphics cursor parameter or *imcur for an image display cursor parameter.

See "Vector Graphics -- gio" on page 114 for a brief description of the graphics procedures. See the gio reference manual (Graphics I/O Design [Tody84b]) for a more complete description of cursor interaction.

cl Command

A quite general method is available to execute any cl command (task) from an SPP application. The procedures clcmd() and clcmdw() send a string as a command line to the cl. The single argument to both procedures is a string containing the command to execute. The only difference between the two procedures is that clcmdw() waits for the completion of the command before returning to the caller.

Table 2.4: CL Command Execution Procedures.

Sending an explicit command to the cl requires that the task have detailed knowledge of the capabilities of the cl and of the syntax of the command language. This means that the task is very dependent on the cl and may no longer work if the cl is modified, or if there is more than one version of the cl in use in a system. For this reason clcmd() should only be used where it is truly necessary, usually only in system utilities.

Ordinary Parameters
Table 2.1: - Parameter I/O Functions.
pset parameters
List Structured Parameters
Table 2.2: - List-Structured Parameter Functions.
Vector Parameters
Interactive Graphics Cursor
Table 2.3: - Graphics Cursor Parameters.
cl Command
Table 2.4: - CL Command Execution Procedures.

Generated with CERN WebMaker