DataBlade Developers Kit User's Guide Programming DataBlade Module Routines in C

BladeSmith generates code for the following types of routines in the udr.c source code file:

• Most User-Defined Routines, next
• Cast Support Functions
• Aggregate Functions
• Selectivity Functions
• Iterator Functions

Important: Avoid code merge problems by modifying code only in the sections marked with a TO DO: note. If you do modify code outside the designated areas, after you regenerate you may have two copies of the routine: the one you modified and the one BladeSmith generated. Although your changes remain, you must resolve the conflicts in the two pieces of code.

BladeSmith generates only minimal code for most routines you create with the Routine wizard.

BladeSmith generates only templates for most user-defined routines.

The generated routine declares the routine, its return type, and arguments. In addition to the arguments you specified when creating the routine, these functions also have an MI_FPARAM argument. Only generated routines that allow null values have code that uses the MI_FPARAM argument. The generated code in these routines uses MI_FPARAM to set the return value of the routine to NULL.

To complete the code for most user-defined routines, you must:

• add your declarations, if necessary.
• remove the call to mi_db_error_raise(), which raises an error stating that the routine is not implemented.
• compute the return value and store it in the Gen_RetVal argument.
• remove the call to mi_fp_setreturnisnull() that sets the return value of your routine to NULL, if necessary.

For more information on programming routines, see the DataBlade API Programmer's Manual.

The following example DataBlade modules have user-defined routines:

• Business DataBlade module. Provides mathematic functions for calculating loans.
• Circle DataBlade module. Provides distance and containment functions that operate on opaque data types.
• FuzzyMatch DataBlade module. Provides functions for handling row data types and comparing opaque data types.
• Parts Explosion DataBlade module and DataBladeAPI DataBlade module. Provide functions for handling and returning collection data types.
• Strings DataBlade module. Provides character-string manipulation functions.

The Mercury DataBlade module exercise in the tutorial provides examples of cast support functions.

If you specified a cast support function when you created a cast, BladeSmith generates the cast support function in the udr.c file.

BladeSmith generates only templates for cast support functions.

The generated function declares the routine, its return type, and arguments. In addition to the arguments you specified when creating the function, these functions also have an MI_FPARAM argument, which is not used by the generated code.

To complete the code for cast support functions, you must:

• add your declarations, if necessary.
• remove the call to mi_db_error_raise(), which raises an error stating that the routine is not implemented.
• convert one data type to the other.
• store the return value in the Gen_RetVal argument.

In a cast support function, you might convert from one binary representation to another, if the data types involved in the cast have differing binary representations. Alternatively, you might perform a calculation to convert one data type to another.

The Creating Distinct Types and Casts exercise in the tutorial uses cast support functions.

If you created a user-defined aggregate with the Aggregate wizard, BladeSmith generates aggregate functions in the udr.c source code file.

BladeSmith generates only templates for aggregate functions.

The generated function declares the function, its return type, and arguments. In addition to the arguments you specified when creating the function, these functions also have an MI_FPARAM argument. Only generated functions that allow null values have code that uses the MI_FPARAM argument. The generated code in these functions use the MI_FPARAM to set the return value of the function to NULL.

To complete the code for aggregate functions, you must:

• add your declarations, if necessary.
• remove the call to mi_db_error_raise(), which raises an error stating that the routine is not implemented.
• compute the return value and store it in the Gen_RetVal argument.
• remove the call to mi_fp_setreturnisnull() that sets the return value of your routine to NULL, if necessary.

For more information on programming aggregate functions, see the DataBlade API Programmer's Manual.

If you selected an initialization function, AggregateInit(), you must add code to it to initialize the state type required by the aggregate computation. You can set up smart large objects or temporary files for storing intermediate results as the state type. The AggregateInit() function returns the state type.

The first argument of the AggregateInit() function is a dummy argument whose value is always NULL. The second argument is an optional initialization parameter to customize aggregate computation. The initialization parameter cannot be a lone host variable reference.

You must add code to the iteration function, AggregateIter(), to perform the aggregate computations.

The AggregateIter() function should not maintain additional states in its MI_FPARAM argument because the MI_FPARAM argument is not shared among the aggregate functions. However, you can use the MI_FPARAM argument to hold information that does not affect the aggregate result.

Tip: Although the iteration function is called by the database server multiple times to calculate the aggregation, it is not implemented as an iterator function that returns a set of results. The Combine Function

If you selected a combine function, AggregateComb(), you must add code to it to merge one partial result with another and return the updated state type.

If you selected a final function, AggregateFinl(), you must add code to convert the state type to the result type.

You can also add code to the AggregateFinl() function to release resources acquired by the initialization function. However, the AggregateFinl() function must not free the state type.

If you create a user-defined function and mark it as a selectivity function for another function (see Selectivity Functions), BladeSmith generates the selectivity function in the udr.c source code file.

For a description of selectivity and user-defined statistics, see User-Defined Statistics.

BladeSmith generates only templates for selectivity functions.

The generated code declares the function, its return type, and arguments. In addition to the arguments you specified when you created the function, BladeSmith also generates an MI_FPARAM argument, which is not used by the generated code.

You must add code to the selectivity function to call the statistics support functions and calculate the selectivity of the associated function for a given set of arguments. For built-in data types, call the built-in statistics functions, such as StatCollect(). For opaque data types, call the statistics support functions in the statistics.c file, such as OpaqueStatCollect(). For more information on statistics support functions for opaque data types, see Editing Statistics Routines in statistics.c.

For example, if you have a selectivity function on an OpaqueEqual() function that is overloaded for an opaque data types, the code for the selectivity function, OpaqueEqualSelectivity(), might perform the following tasks:

• Determine if either of the arguments has a null value. If so, the selectivity of the OpaqueEqual() function is 0.
• Determine if either of the arguments is greater than the maximum or minimum value of your opaque data type. If so, the selectivity of the OpaqueEqual() function is 0.
• Determine where in the distribution one of the arguments falls. Because you know how many values are in each bin, from the location in the distribution you can estimate how many values are less than the argument. The selectivity of the OpaqueEqual() function is then the number of values less than the argument divided by the total number of values.

For more information on coding selectivity functions, see the DataBlade API Programmer's Manual.

The Box DataBlade module has selectivity functions.

If you create an iterator function that returns a set one row at a time, BladeSmith adds code to process the set. The Informix database server calls iterator functions repeatedly to process all of the return values.

In addition to the arguments you specified when creating it, an iterator function contains an MI_FPARAM argument. The Informix database server uses an MI_FPARAM structure to control iteration over the set. The generated code includes a C switch statement with different cases to process the set. The switch statement uses the mi_fp_request() function to obtain the request flag from the MI_FPARAM structure. The Informix database server sets this flag to one of the following values before calling the function:

• SET_INIT. The initial call to the iterator function. The iterator function allocates and initializes memory for state information. The memory allocated must use the mi_alloc(size, PER_COMMAND) function to be available in subsequent calls.
• SET_RETONE. The iterator function is called with this request flag once for each value in the set.

For each value in the set, the function places the address of the next value in the set in the Gen_RetVal argument and returns Gen_RetVal.

When there are no more values to return, the iterator function must call the mi_fp_setisdone() function to signal the Informix database server that all of the set values have been returned, as follows:

		mi_fp_setisdone(Gen_fparam, MI_TRUE);

On this call, the iterator function returns a null pointer.

• SET_END. The request flag the Informix database server sets after all values in the set have been returned. The iterator function frees allocated memory and releases any other resources it has obtained.

In the generated code, each of these sections has a TO DO: note. To avoid code merging problems, make changes only where indicated.

To complete the iterator code, you must:

• add information declarations.
• initialize the iterator function.
• allocate private state information.
• compute the value of the iteration.
• call mi_fp_setisdone() when the iteration is complete.
• free private resources.

For more information on programming iterator functions, see the DataBlade API Programmer's Manual.

The LoanAmortization() function in the Business DataBlade module is an iterator function.