# IBM Visualization Data Explorer Programmer's Reference

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

## 2.2 Adding the Hello Module

The procedure in this example follows the 4-step sequence outlined above.

#### (1) Define the module's function, inputs, and outputs

The Hello module appends an input string to "hello." The resulting combination is the module's output. If the input string is `NULL`, the default output is `"hello world."`

#### (2) Create a module description file

Data Explorer's graphical user interface and executive access the module description file to determine the names of the modules and their inputs and outputs.

Note: | This type of file is commonly referred to as an "mdf" file (because of its file extension) and is created automatically from user input to the Module Builder, as described in Chapter 3. "Module Builder". However, for very simple modules like the one in this example, it is usually easier and quicker to create the file with a text editor.

Parameter names are a part of the module interface that can be seen by the user. In the graphical user interface, parameter names appear in the configuration dialog box and also serve as default names for interactors. In the scripting language, module parameters can be specified by name.

A new module cannot have the name of an existing Data Explorer module (see IBM Visualization Data Explorer User's Reference for a complete list). You should also be aware of the following requirements:

- A Data Explorer module name must be a single alphanumeric string and its first character must be a letter. (Standard Data Explorer module names capitalize the first character of each "word" in a name, as in Attribute and AutoAxes. You may observe this convention or not, as you wish, for the modules you create.)
- The module must be assigned to a tool category--in a `CATEGORY` statement in the module description file. The category can be any of those listed in the Category palette of the VPE window or a new one that you create by naming it in the statement.

In the following example, the mdf file consists of five statements:

        MODULE Hello
        CATEGORY Greetings
        DESCRIPTION  Prefixes "hello" to the input string
        INPUT value; string; "world"; input string
        OUTPUT greeting; string; prefixed string

`MODULE` | Specifies the module name as Hello.
`CATEGORY` | Assigns the module to a new, user-specified category (Greetings).
`DESCRIPTION` | Describes Hello's purpose: to affix "hello" to the input string.
`INPUT` | Assigns the name `value` to the input parameter; specifies its parameter type as `string`; specifies its default value as "world"; and describes it as an input string.
`OUTPUT` | Assigns the name `greeting` to the output parameter; specifies its parameter type as `string`; and describes it as a prefixed string.

For details, see 11.1 , "Module Description Files".

#### (3) Write the module

Having defined the module in a description file, you can now implement the module with a C-language function like the one shown here.

    01   #include <dx/dx.h>
    02
    03
    04   Error m_Hello(Object *in, Object *out)
    05   {
    06     char message[30], *greeting;
    07
    08     if (!in[0])
    09       sprintf(message, "hello world");
    10     else {
    11       DXExtractString(in[0], &greeting);
    12       sprintf(message, "%s %s", "hello", greeting);
    13     }
    14
    15     out[0] = DXNewString(message);
    16     return OK;
    17   }

The `dx.h` file "included" in line 01 contains the definitions of all the Data Explorer library routines. The name of the function that implements a module must consist of the module name (specified in the `MODULE` statement of the description file) prefixed by `m_`. In this case, the function name is `m_Hello`.

When Data Explorer invokes a module, it passes the module two pointers: the first to an array containing the inputs, the second to an array containing the outputs. (See 4.3 , "Data Explorer Execution Model" for details of parameter passing.)

Because the input parameter of this module is passed to `m_Hello` as an array of pointers, `in[0]` is the `value` parameter. If no argument is specified for `value`, `in[0]` is `NULL`, and the default output ("hello world") is placed in `message`. If you do specify an argument, a library routine (`DXExtractString`) extracts it from `in[0]`, and `greeting` becomes a pointer to that string. In line 12, `greeting` is appended to "hello," creating `message`.

Once `message` has been created, the `DXNewString` library routine creates a String Object for the output `out[0]`.

Note: The output of any Data Explorer module must be a Data Explorer Object (such as an Array, Field, or Group). See Table 1 for a complete list of Data Explorer Objects.

#### (4) Compiling and Linking Hello...

##### ...as an inboard module

Copy the following files to the directory you want to work in:

    /usr/share/dx/samples/program_guide/Makefile_workstation
    /usr/share/dx/samples/program_guide/hello.c
    /usr/share/dx/samples/program_guide/hello.mdf

Now rename the makefile to `Makefile` (the name of the default makefile) and enter: `make hello`. This command creates an executable that contains the Hello module.

To invoke this executable (from the directory to which the files were copied), enter:

    dx  -mdf ./hello.mdf -exec ./dxexec.

This command starts Data Explorer (the `hello.mdf` file tells the graphical user interface about Hello and its inputs and outputs).

You can now run any visual program that uses the Hello module. One such program is `hello.net` in the directory `/usr/share/dx/samples/program_guide`.

##### ...as an outboard module

Copy the following files to the directory you want to work in:

    /usr/share/dx/samples/program_guide/Makefile_workstation
    /usr/share/dx/samples/program_guide/hello.c
    /usr/share/dx/samples/program_guide/hello_outboard.mdf

Now rename the makefile to `Makefile` (the name of the default makefile) and enter: `make hello_outboard`. This command creates the executable `hello_outboard`.

To invoke the executable (from the directory to which the files were copied), enter:

    dx  -mdf ./hello_outboard.mdf

This command starts Data Explorer (the `hello_outboard.mdf` file tells the graphical user interface about Hello and its inputs and outputs).

You can now run any visual program that uses the Hello module. One such program is `hello.net` in the directory `/usr/share/dx/samples/program_guide`.

Note: The mdf file of the outboard module contains one additional statement, `OUTBOARD`, which specifies the executable (`hello_outboard`; see 11.1 , "Module Description Files"). This statement may also specify the name of a host on which to run the executable.

        MODULE Hello
        CATEGORY Greetings
        DESCRIPTION  Prefixes "hello" to the input string
        OUTBOARD hello_outboard
        INPUT value; string; "world"; input string
        OUTPUT greeting; string; prefixed string

##### ...as a runtime-loadable module

Copy the following files to the directory you want to work in:

    /usr/share/dx/samples/program_guide/Makefile_workstation
    /usr/share/dx/samples/program_guide/hello.c
    /usr/share/dx/samples/program_guide/hello_loadable.mdf

Now rename the makefile to `Makefile` (the name of the default makefile) and enter: `make hello_loadable`. This command creates the executable `hello_loadable`.

Note: Runtime-loadable modules are not available for SunOS 4.1 or Data General AViiON.

To invoke the executable (from the directory to which the files were copied), enter:

    dx  -mdf ./hello_loadable.mdf

This command starts Data Explorer (the `hello_loadable.mdf` file tells the graphical user interface about Hello and its inputs and outputs).

You can now run any visual program that uses the Hello module. One such program is `hello.net` in the directory `/usr/share/dx/samples/program_guide`.

Note: The mdf file of the runtime-loadable module contains one additional statement, `LOADABLE`, which specifies the executable (`hello_loadable`; see 11.1 , "Module Description Files").

        MODULE Hello
        CATEGORY Greetings
        DESCRIPTION  Prefixes "hello" to the input string
        LOADABLE hello_loadable
        INPUT value; string; "world"; input string
        OUTPUT greeting; string; prefixed string

#### Including Hello in a Visual Program

In this example (Figure 2), the Hello module is not given an input value and therefore uses its default string ("hello world") as output. The Echo module sends the string to Data Explorer's Message window.

Figure 2. The Hello Module in a Visual Program. The protrusion of the upper tab indicates that the Hello module is using default input. When input is supplied through a connecting "arc," as it is to the Echo module, the input tab folds in.

A visual program that produces the string "hello, how are you?" can be created by:

- Using the visual program in Figure 2 and entering the string ", how are you?" as the argument of the `value` input parameter of the Hello module's configuration dialog box, or
- Creating a visual program (Figure 3) in which a string interactor stand-in provides the input (previously entered in the interactor by the user).

Figure 3. The Hello Module with a String Interactor in a Visual Program. Note that both input tabs are folded in (compare Figure 2).

#### Using Hello in a Script

In the following example, no input to Hello is provided, so the module produces its default output:

     a = Hello();
     Echo(a);

In the next three examples, the user provides input to the Hello module. All three produce the output "hello, how are you?"

Example 1

     b = Hello(", how are you?");
     Echo(b);

Example 2

     b = Hello(value = ", how are you?");
     Echo(b);

Example 3

     a = ", how are you?";
     b = Hello(a);
     Echo(b);

### Hello Module with Error Checking

The definition of the Hello module (see 2.2 , "Adding the Hello Module") contains no error checking code. This omission, of course, is not a recommended practice. In the following version, the Data Explorer routine `DXSetError` reports errors to the user.

    01   #include <dx/dx.h>
    02
    03
    04   m_HelloErrorChecking(Object *in, Object *out)
    05   {
    06     char message[30], *greeting, longmessage=NULL;
    07
    08     if (!in[0])  {
    09       sprintf(message, "hello world");
    10       out[0] = DXNewString(message);
    11     }

    12     else {
    13       if (!DXExtractString(in[0], &greeting)) {
    14          DXSetError(ERROR_BAD_PARAMETER, "value must be a string");
    15          goto error;
    16       }
    17       if (strlen(greeting)<=(28-strlen("hello")) {
    18         sprintf(message, "%s %s", "hello", greeting);
    19         out[0] = DXNewString(message);
    20       }

    21       else {
    22         longmessage = DXAllocate((strlen("hello")+strlen(greeting)+2)
                                        * sizeof(char));
    23         if (!longmessage)
    24            goto error;
    25         sprintf(longmessage, "%s %s", "hello", greeting);
    26         out[0] = DXNewString(longmessage);
    27         DXFree((Pointer)longmessage);
    28       }
    29     }

    30     return OK;
    31
    32   error:
    33     DXFree((Pointer)longmessage);
    34     return ERROR;
    35   }

In this example, the return from `DXExtractString` (line 13) is checked. If the routine returns `ERROR`, the error message "value must be a string" is generated and Hello returns `ERROR`.

The combined length of the user-supplied parameter string and "hello" is checked against the length of the buffer. If it exceeds the length, a new buffer is allocated for the output message (and freed before returning). Because `longmessage` is initialized to `NULL`, it can safely be freed on error, even if it has not yet been allocated.

Note: The `m_`module function should return an error code according to the Data Explorer library standard: `ERROR` for error and `OK` for successful completion. Thus the module entry point would typically be declared by:

        Error m_module(Object *in, Object *out);

To create a version of Data Explorer that includes the HelloErrorChecking module, copy the following files to the directory you want to work in:

    /usr/share/dx/samples/program_guide/Makefile_workstation
    /usr/share/dx/samples/program_guide/hello_errorchecking.c
    /usr/share/dx/samples/program_guide/helloerr.mdf

Now rename the makefile to `Makefile` (the name of the default makefile) and enter: `make helloerr`. This command creates an executable that contains the HelloErrorChecking module.

To invoke this executable (from the directory to which the files were copied), enter:

    dx  -mdf ./helloerr.mdf -exec ./dxexec.

This command starts Data Explorer (the `helloerr.mdf` file tells the graphical user interface about HelloErrorChecking and its inputs and outputs).

You can now run any visual program that uses the HelloErrorChecking module. One such program is `hello_errorchecking.net` in the `/usr/share/dx/samples/program_guide` directory.

[ 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 ]