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

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:

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

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

Figure 7-1 Schematic Structure of the Parameter Type

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.

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 {
    cx_param_long,
    cx_param_double,
    cx_param_string
} 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;

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)

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 `long`
cxParamStrGet	Returns a parameter value as a string
cxParamTypeGet	Returns a parameter type

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.");

Last modified: Feb 23 16:16 1999
[ Documentation Home ]