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.
REAL VALUES( 4 ) : : : CALL PAR_GET1R( 'HEIGHTS', 4, VALUES, ACTVAL, STATUS )
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
[1,2.5D0,3.456]
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 3-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.
INTEGER VALUES( 3, 2, 2 ) : : : MAXD( 1 ) = 3 MAXD( 2 ) = 2 MAXD( 3 ) = 2 CALL PAR_GETNI( 'MASK', 3, MAXD, VALUES, ACTD, STATUS )
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
[[[1,2,3],[4,5,6]],[[7,8,9],[10,11,12]]]
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.
REAL VALUES( 12 ) : : : CALL PAR_GETVR( 'MASK', 12, VALUES, ACTVAL, STATUS )
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.
CHARACTER * ( 3 ) CONSTE( 2 ) : : : CALL PAR_EXACC( 'CONSTELLATION', 2, CONSTE, STATUS )
An example of what the user sees is given in Section .
PAR Interface to the ADAM Parameter System