Processing math: 100%

5 Basic Routines

 5.1 Getting a Parameter’s Value
 5.2 Getting an Array of Values
 5.3 Putting a Parameter’s Value
 5.4 Cancelling a Parameter
 5.5 Setting the Dynamic Prompt
 5.6 Setting the Dynamic Default
 5.7 Setting Lower and Upper Limits
 5.8 Cancelling Dynamic Values
 5.9 Inquiring the State of a Parameter

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,

        CALL PAR_GET0L( ’FLAG’, VALUE, STATUS )

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.

        CALL PAR_GET0C( ’STRING’, VALUE, STATUS )

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

        CALL PAR_GET0R( ’THRESHOLD’, THRESH, STATUS )

The user might see

  THRESHOLD - Give the intensity threshold >

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,

  THRESHOLD - Give the intensity threshold /32768/ >

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.

        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.2 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.

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

        CALL PAR_PUT0D( ’SIGMA’, STDDEV, STATUS )

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.3

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.

        DOUBLE PRECISION QRTILE( 3 )
  
            :       :       :
  
        CALL PAR_PUT1D( ’QUARTILES’, 3, QRTILE, STATUS )

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.4

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.

        DO I = 1, ITER
           CALL PAR_GET0D( ’REJECT’, ABC, STATUS )
  
              < perform calculation involving variable ABC >
  
           CALL PAR_CANCL( ’REJECT’, STATUS )
        END DO

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,

         CALL PAR_PROMT( ’OK’, ’The file ’// NAME( :NC ) /
        :                / ’ is to be erased. OK ?’, STATUS )

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.

  *  Set the default shading (parameter SHADE) depending on the colour.
        IF ( COLOUR .EQ. 1 ) THEN
           CALL PAR_DEF0R( ’SHADE’, -1.0, STATUS )
        ELSE
           CALL PAR_DEF0R( ’SHADE’, 0.0, STATUS )
        END IF
  
  *  Obtain the shading.
        CALL PAR_GET0R( ’SHADE’, SHADE, STATUS )

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.

  *  The number of histogram bins must be positive.
        CALL PAR_MINI( ’NBINS’, 1, STATUS )
        CALL PAR_GET0I( ’NBINS’, NBINS, STATUS )

We can set an upper limit too.

  *  The number of histogram bins must be in the range 10 to 1000
  *  inclusive.
        CALL PAR_MINI( ’NBINS’, 10, STATUS )
        CALL PAR_MAXI( ’NBINS’, 1000, STATUS )
        CALL PAR_GET0I( ’NBINS’, NBINS, STATUS )

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. 5

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.

  *  Choose an integer excluding -1, 0, 1, and 2.
        CALL PAR_MINI( ’IVALUE’, 3, STATUS )
        CALL PAR_MAXI( ’IVALUE’, -2, STATUS )
        CALL PAR_GET0I( ’IVALUE’, NUMBER, STATUS )

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.

  *  Get the integer value between 1 and 360.
        CALL PAR_MINI( ’NX’, 1, STATUS )
        CALL PAR_MAXI( ’NX’, 360, STATUS )
        CALL PAR_GET0I( ’NX’, NX, STATUS )
  
  *  Cancel the parameter, as a minimum or maximum value cannot be set
  *  when the parameter is active, and because we want to obtain
  *  another value.
        CALL PAR_CANCL( ’NX’, STATUS )
  
  *  Set a new minimum value.
        CALL PAR_MINI( ’NX’, NX, STATUS )
  
  *  Cancel the maximum value.
        CALL PAR_UNSET( ’NX’, ’MAX’, STATUS )
  
  *  Obtain a new value, with a new minimum and no maximum.
        CALL PAR_GET0I( ’NX’, NX2, STATUS )

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.

  CALL PAR_UNSET( ’NX’, ’DEFAULT’, STATUS )

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.

        INCLUDE ’PAR_PAR’        ! PAR constants
        INTEGER STATE
  
            :       :       :
  
        CALL PAR_STATE( ’INIT’, STATE, STATUS )
  
        LOOP = .TRUE.
        DO WHILE ( LOOP .AND STATUS .EQ. SAI__OK )
           CALL PAR_GET0R( ’INIT’, START, STATUS )
  
              < perform calculation >
  
           LOOP = STATE .NE. PAR__ACTIVE
           IF ( LOOP ) CALL PAR_CANCL( ’INIT’, STATUS )
        END DO

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.

2In the ADAM implementation the user can omit the brackets in response to a prompt.

3A parameter file is implementation specific, however it is expected to be part of any implementation. In the ADAM parameter system the parameter file is an HDS file named after the application and located in the ADAM_USER directory. So for an application called STATISTICS, the above parameter value could be ‘read’ by a parameter in a different application by the user giving the HDS object name with an @ prefix, namely @ADAM_USER:STATISTICS.SIGMA for VMS and @$ADAM_USER/statistics.SIGMA for UNIX.

4In the ADAM implementation this is usually a component of the parameter file – in this case an object of the required size will be created. However, if indirection to a named HDS file is used the shape specified in the PAR routine must match the object’s shape.

5In the ADAM implementation the dynamic minimum and maximum must lie within the limits set by the range field in the interface file. If not, the get routine returns with an error status. The allowed values reside in the intersection set of the two ranges. Users can also specify MIN or MAX for a parameter value to assign the minimum or maximum value to that parameter.