DataBlade Developers Kit User's Guide Programming DataBlade Modules in Java

BladeSmith generates code for the following types of methods:

• Most User-Defined Methods, next
• Iterators
• Aggregates
• Cast Support Methods

This code is generated in the in the ProjectUDRs.java file.

Important: To avoid code merge problems, modify only code in the sections marked with a TO DO: note. If you do modify code outside the designated areas, after you regenerate, you might 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.

Most User-Defined Methods

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

BladeSmith only generates templates for most user-defined methods.

The generated method declares the routine, its return type, and arguments.

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

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

For more information on programming routines, see Creating UDRs in Java.

The example JavaCircle DataBlade module has user-defined methods.

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

In addition to the arguments you specified when you created it, an iterator function contains an MI_FPARAM argument. The Informix database server use an MI_FPARAM structure to control iteration over the set. The generated code includes a Java else statement with different cases to process the set. The else statement uses the getIterationState() method to obtain the request flag from the UDREnv object. The Informix database server sets this flag to one of the following values before it calls the method:

• UDR_SET_INIT. The initial call to the iterator method. The iterator method allocates and initializes memory for state information.
• UDR_SET_RETONE. The iterator method is called with this request flag once for each value in the set.

For each value in the set, the method 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 method must call the setSetIterationIsDone() function to signal the Informix database server that all of the set values have been returned.

• UDR_SET_END. The request flag the Informix database server sets after all values in the set have been returned. The iterator method 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 setSetIterationIsDone() when the iteration is complete.
• free private resources.

For more information on programming iterator methods, see Creating UDRs in Java.

If you created a user-defined aggregate with the Aggregate wizard, BladeSmith generates aggregate methods in the ProjectUDRs.java source code file.

BladeSmith only generates templates for aggregate methods.

The generated method declares the method, its return type, and arguments.

To complete the code for aggregate methods, you must:

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

For more information on programming aggregate methods, see Creating UDRs in Java.

If you selected an initialization method, AggregateInit(), you must add code to it to initialize the state type required by the aggregate computation. The AggregateInit() method returns the state type.

The first argument of the AggregateInit() method 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 method, AggregateIter(), to perform the aggregate computations.

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

If you selected a combine method, 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 method, AggregateFinl(), you must add code to convert the state type to the result type.

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

If you specified a cast support method when you created a cast, BladeSmith generates the cast support method in the ProjectUDRs.java file.

BladeSmith generates only templates for cast support methods.

The generated method declares the routine, its return type, and arguments.

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

• add your declarations, if necessary.
• remove the call to Log(), 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 method, 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.