# IBM Visualization Data Explorer Programmer's Reference

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

## 3.7 Worker Routine

At the end of the C-code framework file created by the Data Explorer Module Builder is a "worker routine" that serves as an interface to the user's application code. The entry point to this routine (i.e., its name) consists of the module name affixed to "_worker" (e.g., the name of the worker routine for the `X` module is `X_worker`).

The Module Builder prepares a parameter list for the worker routine that contains information from the module input parameters, along with pointers to memory for module results. Three examples appear in "Worker Routine Examples". In each example, the Module Builder creates a module with two inputs (the first a Field/Group, and the second a Value) and one output (a Field/Group Object).

### Positions Specification

If the worker routine needs information about the positions component of the first input parameter, it will use one of two sets of arguments to define that information, depending on whether the request is for regular or irregular positions:

    Regular positions arguments:
    int      p_knt           Total number of positions
    int      p_dim           Dimensionality of positions
    int     *p_counts        Count of positions along each dimension
    float   *p_origin        Origin of regular grid
    float   *p_deltas        Delta vectors, p_dim x p_dim
    Irregular positions arguments:
    int      p_knt           Total number of positions
    int      p_dim           Dimensionality of positions
    float   *p_positions     Explicit list of positions

### Connections Specification

If the worker routine needs information about the connections component of the first input parameter, it will use one of two sets of arguments for defining that information, depending on whether the request is for regular or irregular positions:

    Regular connections arguments:
    int      c_knt           Total number of connections elements
    int      c_nv            Number of vertices per element
    int     *c_counts        Count of vertices along each dimension

    Irregular connections arguments:
    int      c_knt           Total number of connections elements
    int      c_nv            Number of vertices per element
    int     *c_connections   Explicit list of connections elements

### Input Data

For each input to the module, a count value and a pointer are sent to the worker routine. These arguments are named by appending `_knt` and `_data` respectively to the parameter name given in the `Individual Parameter Information` section of the Module Builder interface. Thus, for an input parameter named `param1`, the worker routine would add the following to its argument list:

    int param1_knt     The number of elements in the parameter.
    type *param1_data  A pointer to the data associated with the parameter.
                       The pointer type is that specified in the Data type
                       field of the Individual Parameter
                       Information section of the
                       Module Builder.

For a Field/Group input, these arguments reflect the contents of the "data" component of the leaf. For a Value input (which must be a Data Explorer Array), they reflect the contents of the parameter. Because the parameters are inputs to the module, the arguments are read-only.

### Output Data

For each output of the module, a counts value and a pointer are sent to the worker routine. These arguments are named by appending `_knt` and `_data` respectively to the parameter name given in the `Individual Parameter Information` section of the Module Builder dialog box. Thus, for an input parameter named `param2`, the worker routine would add the following to its argument list:

    int param2_knt     The number of elements in the parameter.
    type *param2_data  A pointer to the data associated with the parameter.
                       The pointer type is that specified in the Data type
                       field of the Individual Parameter
                       Information section of the
                       Module Builder.

For a Field/Group output, these arguments reflect the contents of the "data" component of the leaf (if the leaf is a Data Explorer Field) or of the array itself (if the leaf is a Data Explorer Array). For a Value input (which must be a Data Explorer Array), they reflect the contents of the parameter. The memory associated with these parameters is not initialized.

### Implementing Default Input Parameters

If an input parameter is not provided, the corresponding counts argument of the worker routine for that parameter is zero (0). Implementing the default for the input parameter is the function of the worker routine.

### Worker Routine Examples

Figure 5. Worker Routine: Example1_worker. This routine requests no positions or connections.

    int
    Example1_worker(
         int inputObject_knt, float *inputObject_data,
         int inputArgument_knt, float *inputArgument_data,
         int outputObject_knt, float *outputObject_data)

    {
     /*
      * The arguments to this routine are:
      *

      * The following are inputs and therefore read-only.  The default
      * values are given and should be used if knt is 0.
      *
      * inputObject_knt, inputObject_data: count and pointer for input "inputObject"
      *                   no default value given.
      * inputArgument_knt, inputArgument_data: count and pointer for input "inputArgument"
      *                   nondescriptive default value is "1.0"
      *
      *  The following are outputs and therefore writable.
      *
      * outputObject_knt, outputObject_data: count and pointer for output "outputObject"
      */
     /*
      * User's code goes here.
      */
    }

Figure 6. Worker Routine. Example2_worker. This routine requests regular positions and connections.

    int
    Example2_worker(
     int p_knt, int p_dim, int *p_counts, float *p_origin, float *p_deltas,
     int c_knt, int c_nv, int *c_counts,
     int inputObject_knt, float *inputObject_data,
     int inputArgument_knt, float *inputArgument_data,
     int outputObject_knt, float *outputObject_data)

    {
     /*
      * The arguments to this routine are:
      *
      *  p_knt:           total count of input positions
      *  p_dim:           dimensionality of input positions
      *  p_counts:        count along each axis of regular positions grid
      *  p_origin:        origin of regular positions grid
      *  p_deltas:        regular positions delta vectors
      *  c_knt:           total count of input connections elements
      *  c_nv:            number of vertices per element
      *  c_counts:        vertex count along each axis of regular positions grid
      *

      * The following are inputs and therefore read-only.  The default
      * values are given and should be used if knt is 0.
      *
      * inputObject_knt, inputObject_data: count and pointer for input "inputObject"
      *                   no default value given.
      * inputArgument_knt, inputArgument_data: count and pointer for input "inputArgument"
      *                   nondescriptive default value is "1.0"
      *
      *  The following are outputs and therefore writable.
      *
      * outputObject_knt, outputObject_data: count and pointer for output "outputObject"
      */
     /*
      * User's code goes here.
      */
    }

Figure 7. Worker Routine. Example3_worker. This routine requests irregular positions and connections.

    int
    Example3_worker(
     int p_knt, int p_dim, float *p_positions,
     int c_knt, int c_nv, int *c_connections,
     int inputObject_knt, float *inputObject_data,
     int inputArgument_knt, float *inputArgument_data,
     int outputObject_knt, float *outputObject_data)

    {
     /*
      * The arguments to this routine are:
      *
      *  p_knt:           total count of input positions
      *  p_dim:           dimensionality of input positions
      *  p_positions:     pointer to positions list
      *  c_knt:           total count of input connections elements
      *  c_nv:            number of vertices per element
      *  c_connections:   pointer to connections list
      *
      * The following are inputs and therefore read-only. The default
      * values are given and should be used if knt is 0.
      *
      * inputObject_knt, inputObject_data: count and pointer for input "inputObject"
      *                   no default value given
      * inputArgument_knt, inputArgument_data: count and pointer for input "inputArgument"
      *                   nondescriptive default value is "1.0"
      *

      *  The following are outputs and therefore writable.
      *
      * outputObject_knt, outputObject_data: count and pointer for output "outputObject"
      */
     /*
      * User's code goes here.
      */
    }

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