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 ]