7 Using the Parameter Data Type

7 Using the Parameter Data Type

This chapter describes the cxParameter data type and how it is used in the IRIS Explorer environment. It defines the data type and lists the API (Application Programming Interface) routines available for manipulating it. Code examples are also included.

7.1 Understanding Parameters

The cxParameter data type is a simple data type that holds a single scalar value. Its purpose is to pass scalar values between modules in one of three forms, or primitive types. You can use the cxParameter API routines to extract the data values to be passed.

For example, a module that computes the minimum and maximum of a lattice may produce two cxParameter outputs, one containing the lattice minimum value and the other containing the lattice maximum value. The API routines also do automatic type coercion to one of the permissible types (if possible).

This is the type definition:

root typedef struct {
    cxParamType   type              "Type";
    switch (type) {
          case cx_param_long:
                  long    val       "Value";
          case cx_param_double:
                  double  val       "Value";
          case cx_param_string:
                  string str        "Value";
    } p;
} cxParameter;

These are the variables:


The primitive data type: one of long integer, double-precision floating point, or character string (null-terminated).


The value of the primitive data type.

Figure 7-1 depicts the structure of the cxParameter data type.

Schematic Structure of the Parameter Type

Figure 7-1 Schematic Structure of the Parameter Type

7.1.1 Control Panel Widgets

It is easy to confuse the cxParameter data type, which is a root data type and operates just like cxLattice or cxPyramid, with the parameter values that are passed by widgets on the module control panels. The widget happens to use the parameter data type to pass new values, but modules can also pass parameters without using widgets. The widget is merely a way of making the system more flexible in passing changes to parameter values.

7.2 The Data Type Declaration

The cxParameter data type, though defined in the IRIS Explorer typing language, can be considered as a C structure. Fortran users need to pass a pointer to the data structure if they use it. The type declaration is contained in the header file $EXPLORERHOME/include/cx/cxParameter.h.

This is the cxParameter data type declaration:

typedef enum {
} cxParamType;

typedef struct cxParameter {
    cxDataCtlr       ctlr;
    cxParamType       type;
    union {
        struct {
            long              val;
        } cx_param_long;
        struct {
            double            val;
        } cx_param_double;
        struct {
            char             *str;
        } cx_param_string;
    } p;
} cxParameter;

7.2.1 Fortran Type Enumeration

These are the Fortran type enumerations for the parameter type. They are listed in the file $EXPLORERHOME/include/cx/cxParameter.inc.

INTEGER cx_param_long
INTEGER cx_param_double
INTEGER cx_param_string

PARAMETER (cx_param_long                   = 0)
PARAMETER (cx_param_double                 = 1)
PARAMETER (cx_param_string                 = 2)

7.3 Using the Parameter API

This section lists the API (Application Programming Interface) routines for cxParameter, which are described in detail in the IRIS Explorer Reference Pages. They allow you to:

  • create new cxParameter data structures

  • create different types of parameters

  • set scalar and string parameters

  • duplicate parameters

  • extract parameter values

Table 7-1 lists the subroutines and briefly describes the purpose of each one.

Table 7-1 Parameter Subroutines

Subroutine Purpose
cxParamNew Creates a new cxParameter data structure
cxParamDoubleNew Creates a parameter of type double
cxParamLongNew Creates a parameter of type long
cxParamStrNew Creates a character string parameter
cxParamTypeSet Sets the parameter type
cxParamLongSet Sets the parameter to an integer value
cxParamDblSet Sets the parameter to a double value
cxParamStrSet Sets the parameter to a string value
cxParamDup Creates a duplicate of the parameter
cxParamDblGet Returns the parameter value as a double
cxParamPathnameGet Expands a parameter string value into a pathname
cxParamLongGet Returns a parameter value as a long
cxParamStrGet Returns a parameter value as a string
cxParamTypeGet Returns a parameter type

7.4 Code Example

Here is an example of how to use the cxParameter data type. This fragment shows how to define each of the three primitive types.

cxParameter *p;
  p = cxParamNew ( );

   cxParamDblSet  (p, 3.1415926);
   cxParamLongSet (p, 17);
   cxParamStrSet  (p, "Hello, world.");