Chapter 7. Using the Parameter Data Type
Prev |  | Next

## Chapter 7. Using the Parameter Data Type

This chapter describes the cxParameter data type and how it is used in the 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. 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 (32-bit), double-precision floating point (64-bit), 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 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 /usr/explorer/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 /usr/explorer/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 structures
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 UNIX 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.”);

Prev | Table of Contents | Next
Chapter 6. Using the Pick Data Type |  | Chapter 8. Creating User-defined Data Types