IBM Visualization Data Explorer Programmer's Reference

Chapter 11. Making a Module Work

Partial Table-of-Contents

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: 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. 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. 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). 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: 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. 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. 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.

[Data Explorer Home Page | Contact Data Explorer | Same document on Data Explorer Home Page ]