IBM Visualization Data Explorer Programmer's Reference

3.3 Using the Module Builder: A Quick Walk Through

In this example, you will use the Module Builder to create a simple module that adds a single number to each data value of a set.

Note: This function is supplied with Data Explorer as part of the Compute module and is used here only for purposes of illustration.

1. Start the Module Builder with the command dx -builder. The Module Builder dialog box appears.
2. Fill in the Overall Module Description section as follows:

   Name	Type in a name for the module (for this example, use "Add.")
   Category	Select a category for the new module, either by clicking on one of the entries in the Existing pull-down menu or by typing in a menu name or a name of your choosing.
   Description	Type in a short description of the module. This description will appear in the module's configuration dialog box (in the VPE window).
   Number of inputs	Use the stepper buttons to set the value to "2." The two inputs of the new module will be a data Field and the number to be added to each data value.
   Number of outputs	The module generates a single output. Use the stepper buttons to set the value to "1" if that is not already the value. The output is the new Field (i.e., the data value plus the added value).
   Outboard	Activate the outboard toggle button and type in "Add" in the Executable Name field. (Leave the other toggle buttons and fields as they are.) Note: In this example, the new ("outboard") module is an independent process. In contrast, an "inboard" module is compiled and incorporated as part of the Data Explorer executable; and a runtime-loadable module is compiled independently and loaded into Data Explorer at run time.

3. Fill in the Individual Parameter Information section as follows:

   Input   Number < 1 >	The first input is the data field. Set the button in the top-left corner of the Individual Parameter Information section to Input if that is not already the setting. Use the stepper buttons to set Number to "1" if that is not already the value. Enter a name for this parameter in the Name field (e.g., "data"). Enter a short description in the Description field. Confirm that the Required toggle button for the first input is activated. Confirm that the field object toggle button (below Object Type) is activated. On the right-hand side of the Individual Parameter Information section, select float ("floating point") and Scalar for Data type and Data shape respectively. Set Positions and Connections to Not required (information about these components is not needed). For this example, since the dependency of the data on positions or connections in the output Object will be the same as it was in the input Object, select Positions or Connections.
   Input   Number < 2 >	The second input is the value to be added to each data value. Confirm that the button in the top-left corner of the Individual Parameter Information section is set to Input. Use the stepper buttons to set Number to "2". Enter a name for this parameter in the Name field (e.g., "value"). Enter a short description in the Description field. Confirm that the Required toggle button is deactivated. Specify a default value, such as "0." If the default value is meant to be descriptive, activate the Descriptive toggle button. Under Object Type, activate the simple parameter toggle button. Now activate the Scalar toggle button (below Type on the right-hand side).
   Output   Number < 1 >	Now describe the output of the module. Change Input to Output (top-left corner of the Individual Parameter Information section). The Number setting changes to "1" automatically. Enter a name for this parameter in the Name field (e.g., "result"). Enter a short description in the Description field. Confirm that the field object toggle button (below Object Type) is activated. Confirm that Data type and Data Shape are set to float and Scalar respectively. Confirm that Dependency is set to Positions or connections.

   You can now create the necessary files:

   1. Click on Build in the dialog box menu bar and select Create All in the pull-down menu.

      The Module Builder creates three files for the Add module: Add.c, Add.mdf, and Add.make.

   2. To insert the necessary user-specific code in Add.c, use an editor. Look for the phrase "User's code goes here" at the bottom of the file, and type in the following:

               int i;
               float value;
               if (value_knt==0)
                   value = 0;
               else
                   value = value_data[0];
               for (i=0; i<data_knt; i++) {
                   result_data[i] = data_data[i]+value;
               }
      

      First, variables i and value are declared. Next, the default value of 0 is enforced by checking whether a number has been passed as the value parameter. If value_knt is equal to 0, the user did not pass a number, and value is set to 0. Otherwise, the passed number is used. Finally, the data component of the output is modified by adding value to every data item in the input.

      Alternatively, you could have put this information in a separate file and used the Include File Name option in the Overall Module Description section.

   To create a version of Data Explorer that uses this module, type

            make -f Add.make
   

   To run Data Explorer using this module, type

            dx  -mdf Add.mdf
   

   If you were creating an inboard module instead, the only difference would be in the command to run Data Explorer:

            dx  -mdf Add.mdf -exec ./dxexec
   

[Data Explorer Home Page]