5 Basic Routines

5.1 Getting a Parameter’s Value

The way an application obtains a value from a parameter is to get the value. In simple terms, a get operation is the equivalent of a Fortran read, though it can do much more. In this example,

gets a logical value from the parameter FLAG and stores it in the logical variable VALUE. The data type is logical because of the L suffix in the routine’s name. If VALUE were a character variable, you would use a similar routine, but this time with a C suffix as shown below.

There are similar routines for the other primitive data types, each with an appropriate suffix: D for double precision, I for integer and R for real. By convention where a routine has variants for different data types it has an “x” suffix, so in this case the routines are known collectively as PAR_GET0x. Note that there are no routines for obtaining byte and word values. These must be obtained using the integer version of the routine. The variable STATUS is the inherited status value adhering to the rules in SUN/104, and summarised in Section 4. The 0 in the routine name indicates that the routine passes a scalar (zero dimensions). Likewise a routine with a 1 in its name passes a vector, and with an N it passes an $n$-dimensional array.

There is a maximum length for the parameter name (set by ADAM) of fifteen characters, but this is quite adequate except perhaps for lexicographers.

The actual value of the parameter supplied to the application at run time need not necessarily have the same data type as you have requested in your application. The parameter system will handle conversions between the type of the value and the type required by the application. So you only need to concern yourself with what your application requires.

What does the user see? This will depend on the implementation, but suppose the user is prompted for a value. If you had in your code

The user might see

with the parameter name first, followed by a prompt string briefly describing the function of the parameter. (In the ADAM implementation this string is usually defined within the interface file, but there is a PAR routine for setting it within the application itself.) Suppose the user enters 32768 in response to the above prompt. The next time the user ran the application there could be a suggested default of the last-used value like this,

which could be accepted merely by pressing the return key.

In the ADAM implementation the PAR_GET calls will (re-)prompt whenever the user gives too many values or an invalid value. Invalid values include supplying a character string where a number is required, and being outside the interface file range or in constraints.

5.2 Getting an Array of Values

In addition to obtaining a scalar value, there are routines for getting arrays of values. At this point it is appropriate to say a few words about the shape of a parameter. A parameter’s shape may be scalar, vector, or $n$-dimensional. When you get values from a parameter, the parameter acquires the shape of the values supplied by the user. Therefore, you could use the same parameter to obtain a scalar and a cube. How much is the user restricted by the parameter shape? When getting an array the application specifies the maximum number of dimensions and the maximum sizes along each dimension; the values supplied must not exceed these maxima, but there may be fewer. Now we return to the descriptions of the basic PAR_ routines.

Here is an example to get a vector of real values.

It enables all or part of a four-element array to be obtained and stored in the real variable VALUES. ACTVAL is the actual number of values obtained from parameter HEIGHTS. Again there are versions of this routine for the different data types listed earlier.

In the above example the user might enter

where the brackets indicate an array and the commas separate the values.² For this input, ACTVAL becomes 3.

A parameter’s values may be stored as an $n$-dimensional array. The following example shows a three-dimensional mask of integers being obtained from parameter MASK and being stored in an array called VALUES. MAXD gives the maximum dimensions of the array. The array itself must be large enough to hold the values. ACTD receives the actual dimensions of the array as specified by the user.

This routine is unlikely to be in common usage because of the impracticality of the user of your application entering more than the smallest $n$-dimensional arrays of parameters, and having to know the parameter’s shape. To illustrate the former point, in the above example the user might enter

where the nested brackets delimit the dimensions, and the commas separate the values within a dimension. Thus there are three values along the first dimension; each of these triples is bracketed in pairs along the second dimension; and this is repeated for each element along the third dimension, within the outermost brackets. In other words the first dimension increases fastest, followed by the second, and so on – the Fortran order. Thus, in the example, VALUES(3,1,2) is 9.

Usually, it will suffice to get a vector of values disregarding the dimensionality of the parameter.

This has the same arguments as PAR_GET1x we saw above, though the actual number of array dimensions of the parameter need not be one.

There may be occasions when you want an exact number of values. Below, we obtain two character variables from parameter ’CONSTELLATION’. When too few values are supplied to the parameter, PAR_EXACx prompts for the remainder of the values.

An example of what the user sees is given in Section 7.2.

5.3 Putting a Parameter’s Value

The opposite to get is put. Using traditional Fortran input-output, the equivalent of putting a value is to write the value to a file. In addition to getting parameter values, PAR can also put values into parameters. Suppose we have an application that computes statistical parameters for a data array. We should like to store these statistics in parameters, so that they may be passed to a later application. Thus we could have a number of puts – one per statistic. Here we just put the standard deviation value in the parameter SIGMA.

The value is written to a parameter file associated with the application. This file contains not only any values you have put there, but also the last-used values of all the parameters of that application.³

If we had the values corresponding to the quartiles and median of a data array we could use a routine that handles a one-dimensional array.

When you put an array, the subroutine arguments specify both the dimensionality and size of that array, and the size of an ‘object’ into which the array is to be put.⁴

Analogous to the PAR_GETNx and PAR_GETVx routines for getting arrays of values, there are equivalent generic routines, PAR_PUTNx and PAR_PUTVx, for putting values in parameters. Using PAR_PUTNx in one application and accessing the array via PAR_GETNx without prompting is the most likely way to handle $n$-dimensional arrays of parameter values.

See SUN/115 Appendix C for details of the specifications needed within the interface file to deal with scalar and array output parameters.

5.4 Cancelling a Parameter

Cancelling a parameter means that values associated with it are lost. It is most-commonly used for processing in a loop.

If we have a loop in which we wish to get new values for a parameter and do some calculations in each iteration, we must cancel any parameters obtained in the loop, otherwise the first value will be used repeatedly, since the parameter is in the active state.

Here is an illustration. ITER calculations are performed, using the value of parameter REJECT.

5.5 Setting the Dynamic Prompt

In the ADAM implementation, the prompt a user of an application sees usually originates from the interface file, and hence is fixed. However, it is possible to create a prompt string dynamically from within the application. For example,

will change the prompt string for parameter OK, so that the named file given by the variable NAME, may be substituted at run time.

5.6 Setting the Dynamic Default

When the parameter system prompts for a parameter, there is usually a suggested default given between / / delimiters, so that the user can just press <CR> to use the suggestion, or edit the suggestion. The suggested value can originate from a number of places. This includes from within an application, by setting a dynamic default.

In the following example the dynamic default for the scalar parameter SHADE depends on the value of variable COLOUR. If COLOUR is one, the dynamic default for parameter SHADE will be $-$1.0, and 0.0 otherwise.

Note that in ADAM applications the ppath in the interface file must begin DYNAMIC to ensure that the user of your application will be prompted with the dynamic default (see SUN/115).

The ADAM parameter system also allows the dynamic default to be used as the parameter value without prompting, through the interface file vpath (see SUN/115).

There are also routines that set the dynamic default for a vector parameter (PAR_DEF1x) and an array parameter (PAR_DEFNx). Again there are versions of this routine for the different data types listed earlier.

5.7 Setting Lower and Upper Limits

It is a common requirement to restrict a parameter’s value to a specific range, or to be above some lower limit or less than some upper limit. For example, the order of a polynomial would have to be positive, but less than some maximum value that the polynomial-fitting software can handle. Whilst this can be done using the range field in the interface file, PAR offers dynamic control through two routines – PAR_MAXx to set the maximum value, and PAR_MINx to set the minimum value for the parameter. Note that there are no logical-type versions of these routines.

Here is an example of setting the minimum value.

We can set an upper limit too.

If the user gives a value outside the legitimate range, an error report appears, and the user is prompted for an acceptable value. In the case of character parameters, the parameter’s value follows the minimum value and precedes the maximum value in the ASCII collating list. ⁵

If the minimum value is greater than the maximum at the time you get a parameter value, this instructs PAR not to permit values between the minimum and maximum. So the maximum is always the value immediately below the range to be excluded, and the minimum is the value immediately above. In case that is not clear here is an illustration.

5.8 Cancelling Dynamic Values

5.8.1 Range

Having set a minimum or a maximum value, you can alter its value by a further call to PAR_MINx or PAR_MAXx. Like a parameter itself, these control values remain in effect until the end of an application, or until they are cancelled. Therefore, should you no longer want either or both of the maximum and minimum limits, you must cancel them with PAR_UNSET. This routine’s second argument is a comma-separated list which selects the values to reset.

In the following example parameter NX is obtained twice, first using a range, and then with no maximum limit and a different minimum.

See Appendix G for details of the options for the second argument.

5.8.2 Dynamic Defaults

PAR_UNSET need not be called to change the value of a default; a call to one of the PAR_DEF routines will suffice. However, if you wish to no longer have a dynamic default for parameter NX say, you will need to make the following call.

5.9 Inquiring the State of a Parameter

PAR provides a routine for inquiring the state of a parameter. One practical use for this is to determine whether a parameter is specified on the command line or not, and hence to affect the behaviour of the application. For example, you have an application that loops for efficient and easy interactive use, but in a procedure or batch mode you want the application to process just one set of data.

INIT is a parameter required for each calculation. It is obtained within a code loop. If INIT is specified on the command-line, INIT is in the active state before the call to PAR_GET0R. So a logical expression involving the state decides whether there is but one cycle around the loop or many. The include file PAR_PAR contains the definitions of each of the states returned by PAR_STATE. The next section describes how we might end the loop in the interactive case.