# IBM Visualization Data Explorer Programmer's Reference

[ Bottom of Page | Previous Page | Next Page | Table of Contents | Partial Table of Contents | Index ]

# Chapter 11. Making a Module Work

Partial Table-of-Contents

- 11.1 Module Description Files
- Examples of Module Description Files
- 11.2 Asynchronous Modules
- 11.3 Inboard, Outboard, and Runtime-loadable Modules
- 11.4 Compiling, Linking, and Debugging an Inboard Module
- 11.5 Compiling, Linking, and Debugging an Outboard Module
- Special Considerations for Outboard Modules
- Asynchronous Outboard Module: An Example
- 11.6 Compiling, Linking, and Debugging a Runtime-loadable Module
- 11.7 Memory Leaks

  This chapter discusses module description files and the compiling, linking, and debugging of modules.

  ## 11.1 Module Description Files

  A module description file (`.mdf` file) contains essential information about Data Explorer modules, including their inputs and outputs. Data Explorer uses this information for various executive and user-interface operations, among them the creation of tool icons.

  A module description file consists of one or more "definition" sections, one section for each module described. Every section must contain the first two statements shown here, along with `INPUT and OUTPUT`:

          MODULE name
          CATEGORY category name
          DESCRIPTION module description
          FLAGS optional flags
          OUTBOARD "executable"; host
          LOADABLE "executable"
          INPUT name [visible]; type; default; description
          OPTIONS option1; option2;...;
          OUTPUT name [cache]; type; description
          REPEAT n

  Note: A module description may contain an `OUTBOARD` or a `LOADABLE` statement, but not both.

  `MODULE` | Is required and must be the first statement in the definition section. It assigns a name to the module being described. name must be a single alphanumeric word, with a letter for the first character.
  `CATEGORY` | Is required. It assigns the module to a Data Explorer or user-defined category. (Categories function as tool menus in the VPE window; see Chapter 6. "Graphical User Interface: Important Windows" in IBM Visualization Data Explorer User's Guide.) category name may contain more than one word (e.g., "Import and Export").
  `DESCRIPTION` | Is optional. It serves as a help function. module description should briefly describe the module function. Brevity is recommended since this description shares limited space with other information (accessed with the `Description...` button in the module's configuration dialog box).

  `FLAGS`

  Is optional. Most modules do not need to set flags.
  - `PIN`: Specifies that a module is always to execute on the same processor. Applicable only to multiprocessor systems.
  - `PERSISTENT`: Specifies that the outboard (Ref #2.) executable is not to be terminated after each execution of the visual program.
  - `ERR_CONT`: Specifies that modules downstream are to continue to execute even when this module returns `ERROR`.
  - `SIDE_EFFECT`: Specifies that the module has side effects and must execute each time the visual program is executed, even if its inputs have not changed.

  - `ASYNC`: Identifies the module as being able to initiate execution in response to an external event. (See also 11.2 , "Asynchronous Modules".)

  `OUTBOARD`

  Is optional. It identifies the module as a separate executable program.

  Note: If this statement is included, the module definition must not have a `LOADABLE` statement (see below).

  "executable" specifies the name of the executable and any arguments to be passed. (Quotation marks are required for executable specifications containing spaces or tabs; otherwise they are optional.)

  Note: If you are running Data Explorer on the IBM POWER Visualization System**, the name of the executable must be preceded by the term "os," and the combination enclosed in quotation marks (e.g., "os executable").

  host is optional and specifies a remote machine on which the executable is to be run. The default host is the one on which the executive runs. (See also "...as an outboard module" and 11.5 , "Compiling, Linking, and Debugging an Outboard Module".)

  `LOADABLE`

  Is optional. It identifies the module as being runtime loadable (i.e., compiled separately and loaded into Data Explorer at run time.

  Note: If this statement is included, the module definition must not have an `OUTBOARD` statement (see above).

  "executable" specifies the name of the executable and any arguments to be passed. (Quotation marks are required for executable specifications containing spaces or tabs; otherwise they are optional.)

  See also "...as a runtime-loadable module" and 11.6 , "Compiling, Linking, and Debugging a Runtime-loadable Module"

  `INPUT`

  Is required for each input parameter (i.e., two input parameters, two statements). A statement consists of four fields separated by semicolons:
  1. name (of a parameter) must be one word and must conform to the executive's lexical conventions (see Chapter 10. "Data Explorer Scripting Language" in IBM Visualization Data Explorer User's Guide).

     [visible] is optional. `visible:`n specifies the accessibility and initial visibility of input tabs:

       0: Not initially visible.
       1: Initially visible (default).
       2: Not available to the user interface.

     A hidden parameter (`visible:0`) can be exposed with the `Expand` button in the module's configuration dialog box. Less commonly used parameters are often hidden by default.

  2. type specifies the type(s) of the input and is used for type matching in the Visual Program Editor. The valid types are:

         camera      integer list     scalar          value
         field       matrix           scalar list     value list
         flag        matrix list      series          vector
         group       object           string          vector list
         integer

     To specify more than one type, use the word `or` as a separator (see, for example, the description file for Filter in "Examples of Module Description Files").

     If the type of the input value is not explicit (e.g., a string without quotation marks or a vector without brackets), the user interface attempts to match the input against the type(s) specified in the `INPUT` statement. It reads from left to right and stops at the first successful match. For this reason, `string` should be specified last, because any series of characters can always be converted to a string by adding double-quotation marks.

  3. default identifies the value to be used if none has been specified.

     Note: | This part of the `INPUT` statement is informational only: it is the module writer's responsibility to implement a default value.

     By convention, parentheses identify a description of default behavior rather than an actual value. If no default is applicable, specify `(no default)`. If the parameter is required, specify `(none)`.
  4. description should contain a short phrase describing the parameter.

  `OPTIONS`

  Is optional. It identifies a list of possible values for the parameter. This list can be accessed by clicking on the `...` button to the right of the `Value` field in the module's configuration dialog box.

  Options in the list are separated by a semicolon (;). If the option itself includes a semicolon, use a back slash (\) to escape it with. To accommodate inputs that have more options than will fit on a single line, use multiple OPTIONS statements. If the REPEAT statement is used, the OPTIONS statement must precede it.

  `OUTPUT`

  Is required for each output parameter (i.e., two output parameters, two statements). A statement consists of three fields separated by semicolons:
  1. name (of a parameter) must be one word and must conform to the executive's lexical conventions (see Chapter 10. "Data Explorer Scripting Language" in IBM Visualization Data Explorer User's Guide).

     [attribute] is optional. `cache:`n specifies the caching to be performed by the executive:

       0: Do not cache the output.
       1: Cache all outputs (default).
       2: Cache the output of the last execution only.

     Output caching is similar to module caching (see "Function Call Attributes" in IBM Visualization Data Explorer User's Guide.) Cache specifications for outputs override those for the module.

  2. type specifies the type of the output and is used for type matching in the Visual Program Editor. The valid types are:

         camera     integer list     scalar         value
         field      matrix           scalar list    value list
         flag       matrix list      series         vector
         group      object           string         vector list
         integer

     To specify more than one type, use the word `or` as a separator.

  3. description should be a short phrase describing the parameter.

  `REPEAT`

  Is optional. It specifies some number of `INPUT` or `OUTPUT` statements to be repeated. The parameter `n` specifies the number of statements (input or output) affected: "1" specifies the first immediately preceding statement; "2", the first and second preceding statements; and so on.

  `REPEAT` must come immediately after `INPUT` (after the last input statement if there are two or more) or after `OPTIONS` if `OPTIONS` is used. The same requirement applies to `OUTPUT`. That is, one `REPEAT` for all inputs and another for all outputs.

  The number of repetitions of a single statement is determined by the number of corresponding tabs on the module icon (up to a maximum of 21). Thus, `REPEAT` makes it possible to add input and output tabs to (or delete them from) a module icon, thereby adding or deleting inputs and outputs.

  ### Examples of Module Description Files

  The following examples illustrate the specification of three modules: Filter, Options, and ShowBox.

  The module description for Filter is:

         MODULE Filter
         CATEGORY Transformation
         DESCRIPTION  applies a filter to a field
         INPUT input;  field;  (none);  data to filter
         INPUT filter;  value or string;  "gaussian";  filter to use
         INPUT component[visible:0];  string;  "data";  component to be operated on
         OPTIONS data; colors
         INPUT mask[visible:0]; value or string; "box"; rank-value filter max
         OUTPUT output;  field;  filtered data

  The Filter module is assigned to the Transformation category. It takes four inputs:

  Module Input | Type | Default | Description
  --- | --- | --- | ---
  `input` | field | none | data to be filtered
  `filter` | value or string | "gaussian" | filter to be used
  `component` | string | "data" | component to be operated on
  `mask` | value or string | "box" | rank-value filter maximum

  All input parameters but `input` are assigned default values. The `component` and `mask` parameters are hidden by default ([visible:0]).

  The OPTIONS line in the module description specifies possible values for the `component` parameter (two in this case). This list of values can be accessed by clicking on the `...` button to the right of the `Value` field in the module's configuration dialog box.

  The module description for the ShowBox module is:

         MODULE ShowBox
         CATEGORY Realization
         DESCRIPTION  draws a bounding box
         INPUT input;  field;  (none);  the field of which to show the bounding box
         OUTPUT box;  field;  renderable bounding box of input field
         OUTPUT center; vector;  center of bounding box

  The ShowBox module is assigned to the Realization category. It takes an input, named `input`, of type `field`. There are two outputs, named `box` and `center`, of type `field` and `vector` respectively.

  The module description for the Options module is:

          MODULE Options
          CATEGORY Structuring
          DESCRIPTION  associates attributes with an object
          INPUT input;  object;  (none); object with attributes to be set
          INPUT attribute;  string;  (no default);  attribute to set
          INPUT value;  object;  (no default);  value of the attribute
          REPEAT 2
          OUTPUT output;  object;  the object with attributes set

  The Options module is assigned to the Structuring category. It has three named parameters, none of which is given defaults. The module may take additional pairs of input parameters, whose types are the same as the last two inputs preceding the `REPEAT` statement.

  [ Top of Page | Previous Page | Next Page | Table of Contents | Partial Table of Contents | Index ]
  [Data Explorer Documentation | QuickStart Guide | User's Guide | User's Reference | Programmer's Reference | Installation and Configuration Guide ]

  [Data Explorer Home Page]

  [IBM Home Page | Order | Search | Contact IBM | Legal ]