DataBlade module example descriptions

This section describes the example DataBlade® modules provided with the DataBlade Developers Kit.

Topic-to-example table

The following table lists topics, in alphabetical order, covered by the example DataBlade modules provided with the DataBlade Developers Kit.

Table 1. topics to examples
Main topic Subtopic and DataBlade module
Accessor functions ActiveX value objects: Color DataBlade module, Multirep DataBlade module
ActiveX Client value objects: Color DataBlade module
C++ Client program: UDTExporter DataBlade module

ActiveX value objects: Color DataBlade module
Casts Numeric to text: Strings DataBlade module
Client Using ESQL/C: UDTExporter DataBlade module

Using C++: UDTExporter DataBlade module

Using ActiveX value objects: Color DataBlade module
Collection data types Returning a collection with a user-defined routine: DataBladeAPI DataBlademodule, TopK Terms DataBlade module, Parts Explosion DataBlade module

Retrieving through ESQL/C: UDTExporter DataBlade module

Argument in a user-defined routine: TopK Terms DataBlade module
DataBlade API User-defined routines for the server: DataBladeAPI DataBlademodule
ESQL/C Client program: UDTExporter DataBlade module
GLS Using GLS routines: Strings DataBlade module
Large object data types Multirepresentational data types: Multirep DataBlade module, Strings DataBlade module

Support functions (Assign, Destroy, LOhandles): Multirep DataBlade module
Multirepresentational data types Variable-length opaque data type: Multirep DataBlade module
Opaque data types Variable length: Multirep DataBlade module

Multirepresentational: Multirep DataBlade module

Floating-point array: Multirep DataBlade module

Integer array: FuzzyMatch DataBlade module

Compressed string: Strings DataBlade module

Retrieving through ESQL/C: UDTExporter DataBlade module

Coordinate points: Circle DataBlade module

With an opaque data type member: Circle DataBlade module

With user-defined statistics: Box DataBlade module

Displaying as ActiveX value objects: Color DataBlade module
Row data types Creating a typed table: FuzzyMatch DataBlade module

Retrieving through ESQL/C: UDTExporter DataBlade module
Secondary access methods User-defined: Strings DataBlade module
Support functions Large objects (Assign, Destroy, LOhandles): Multirep DataBlade module

Custom Input function: FuzzyMatch DataBlade module, Strings DataBlade module

ActiveX value objects: Color DataBlade module

Statistics functions: Box DataBlade module

Custom Output function: Strings DataBlade module
User-defined routines

Manipulating opaque data type members: Multirep DataBlade module

Returning a set: DataBladeAPI DataBlademodule

Arithmetic: Business DataBlade module, Matrix DataBlade module

Iterator: TopK Terms DataBlade module

Containment: Circle DataBlade module

Selectivity: Box DataBlade module

Matching numbers: FuzzyMatch DataBlade module

Example descriptions

The following example DataBlade modules are provided in the dbdk\examples directory:

Most of these examples have a BladeSmith project file (.ibs) and source code, SQL registration scripts for use with BladeManager, simple installation files for use with BladePack, and functional tests.

Compiled binaries for the examples are not included and must be rebuilt using the source files.

To set up example DataBlade modules, read the readme.txt file in the %ONEDB_HOME%\dbdk\examples directory.

Box DataBlade module

The Box DataBlade module illustrates how to use user-defined statistics and selectivity with an opaque data type.

The Box DataBlade module contains the following objects:
  • The Box opaque data type, which has two members: Height and Width.
  • The BoxArea() user-defined function, which calculates the area of the Box data type.
  • Support routines for the Box data type, including B-tree indexing comparison functions
  • A selectivity function corresponding to each B-tree indexing comparison function
  • Statistics support functions: BoxStatCollect(), BoxStatPrint(), BoxSetMinValue(), BoxSetMaxValue(), and BoxSetHistogram()

The box.dsw file in the %ONEDB_HOME%\dbdk\examples\types\dapi\Statistics\Box\src directory is the Visual C++ workspace file for this DataBlade module.

Business DataBlade module

The Business DataBlade module illustrates how to perform arithmetic calculations with the following user-defined functions:
  • ExmAmortize. Applies compound interest to loans that are to be paid off in installments.
  • ExmFV. Calculates the value of payments after a given time when compounded at a given interest rate.
  • ExmPV. Calculates the value today of future payments discounted at the appropriate discount rate.

The business.dsw file in the %ONEDB_HOME%\dbdk\examples\routines\dapi\businessmat\src directory is the Visual C++ workspace file for this DataBlade module.

Circle DataBlade module

The Circle DataBlade module illustrates how to represent two-dimensional coordinates and circles with two opaque types (Pnt and Circ). The Circ data type contains the Pnt data type as one of its members. The DataBlade module provides the Contains() function for calculating the distance between two points and the Distance() function for testing whether a circle contains a given point.

The circle.dsw file in the %ONEDB_HOME%\dbdk\examples\types\dapi\circle\src directory is the Visual C++ workspace file for this DataBlade module.

Color DataBlade module

The Color DataBlade module illustrates how to encapsulate an opaque data type as an ActiveX value object. It consists of a server project and a client project. The server project defines the Color opaque data type, its support routines, and its accessor methods for execution on the server. The client project provides the code that allows Microsoft™ Visual Basic to instantiate the server opaque data type as a client-side ActiveX value object; it also provides the ActiveX custom methods and interfaces with which Visual Basic and the client application developer can access the ActiveX value object.

The client program connects to an HCL OneDB™ database table that contains a Color data type column, retrieves a row from that table, and then makes use of the ActiveX client project to visualize (display) the data as a color in Visual Basic.

The Color data type represents standard RGB color codes. It has three members: one each for red, green, and blue.

The readme.txt file in the %ONEDB_HOME%\dbdk\examples\Types\ActiveX\AxColorDemo directory describes:
  • How to create a database containing a table with a Color data type column and how to populate the table with sample data.
  • How to connect to the database server with Visual Basic, using Microsoft RDBC and ODBC.
  • How to create a reference to the Color Project and display the ActiveX value objects for the Color data type in Visual Basic.

The axcolordemo.dsw file in the %ONEDB_HOME%\dbdk\examples\types\activex\axcolordemo\src is the Visual C++ workspace file for this DataBlade module.

DataBladeAPI DataBlademodule

The DataBladeAPI DataBlade module illustrates how to use DataBlade API calls and query processing from within a server user-defined routine. It queries for a column in a table and returns the values as a set.

The DataBladeAPI DataBlade module provides the CIter function and a table.

The databladeapi.dsw file in the %ONEDB_HOME%\dbdk\examples\routines\dap\querydata\src is the Visual C++ workspace file for this DataBlade module.

For more information, read the readme.txt file in the %ONEDB_HOME\dbdk\examples\Routines\dapi\QueryData directory.

FuzzyMatch DataBlade module

The FuzzyMatch DataBlade module illustrates how to:
  • Use row types.
  • Write a custom Input support routine.
  • Create an opaque data type.
  • Use SQL for custom data matching.

The FuzzyMatchDataBlade module was designed for a clothing manufacturer that must store information about the clothing it manufactures and retrieve that information based on color.

The table holding the clothing data is a typed table based on a row type called ClothingType. The ClothingType row type includes an opaque type called ColorType, which holds color information. Custom handling of a color description is performed by the Input routine ColorTypeInput. This routine is based on the assumption that a color description is supplied as a number or a name. The number is an RGB color triplet, with each color appearing in the range 0 - 255. If, while reading the color description, ColorTypeInput detects a leading character rather than a digit, it looks up the name in an external file, called color.map, and uses the associated numeric color value.

To locate data based on color, the FuzzyMatch() function checks to see if two colors are in close proximity by computing the distance between them using a Euclidean metric on the RGB color values. The value is normalized and examined to see if it is less than the value 0-1, as specified by the SQL user. If so, a match is made, and the clothing data is displayed.

The fuzzymatch.dsw file in the %ONEDB_HOME%\dbdk\examples\routines\dapi\fuzzymatch\src directory is the Visual C++ workspace file for this DataBlade module.

Matrix DataBlade module

The Matrix DataBlade module illustrates how to store and retrieve two-dimensional matrixes, as opaque data types, to and from the database. In addition, it provides user-defined routines that perform arithmetic operations between matrixes of compatible dimensions.

The matrix.dsw file in the %ONEDB_HOME%\dbdk\examples\types\dapi\matrix\src directory is the Visual C++ workspace file for this DataBlade module.

MMX Matrix DataBlade module

The MMX Matrix DataBlade module illustrates how to use MMX technologies with a user-defined function from within a DataBlade module to multiply a matrix by a vector to produce another vector. The VxMmx() function uses MMX code to multiply a matrix and a vector to produce another vector.

The mmxmatrix.dsw file in the %ONEDB_HOME%\dbdk\examples\types\mmx\matrix\src directory is the Visual C++ workspace file for this DataBlade module.

MMX String Search DataBlade module

The MMX String Search DataBlade module illustrates how to use MMX technologies with a user-defined function from within a DataBlade module to test for the presence of one string within another. The strstrmmx() function uses MMX assembly code to match the two strings.

The mmxstring.dsw file in the %ONEDB_HOME%\dbdk\examples\routines\mmx\strings\src\mmxstring directory is the Visual C++ workspace file for this DataBlade module.

Multirep DataBlade module

The Multirep DataBlade module illustrates how to use multirepresentational data, which is stored in different ways based on its size. This DataBlade module uses an sbspace to store data too large to fit in a database table row.

Important: You cannot currently create this DataBlade module using BladeSmith; for information on how to install it, read the readme.html file in the %ONEDB_HOME%\dbdk\examples\Types\dap\MultirepLO directory.

This DataBlade module creates a variable-length opaque data type, MyUdt, containing an internal array of double-precision floating-point values, support functions for MyUdt, and user-defined routines.

These functions are provided:
  • Text input (MyUdtIn) and output (MyUdtOut) for inserting and displaying data in a table
  • Large-object support functions: Assign(), Destroy(), and LOhandles()
  • Two accessor functions to obtain the number of elements in the floating-point array (NumElements) and the value of an individual element (Element)
  • Two modifier functions to append an element to an array (AppendElement()) and change the value of an existing element (ReplaceElement())

The myblade.c file in the %ONEDB_HOME%\dbdk\examples\types\dapi\multireplo directory contains the source code for the MyUdt data type support routines and the user-defined routines.

Parts Explosion DataBlade module

The Parts Explosion DataBlade module illustrates how to use a simple solution to a parts explosion problem, which finds all dependent child objects for a given parent object. For example, you could find all parts that must be ordered to build the engine of a particular model of automobile.

The assumption for this module is that all objects (parts) are stored in one table. This table has at least two columns:
  • A key column, unique for every object in the table
  • A pointer column describing the "is part of" relationship to other objects in the table

This implementation requires that both the key column and the pointer column be of type INTEGER.

Typically, the table also has a description of the object, its price, and so on. This parts explosion solution is limited in that it is based on the assumption that an object can be the child of only one parent.

This example DataBlade module demonstrates the use of SQL statements within a DataBlade module, how to return a set of results, and the use of the MI_FPARAM structure to return multiple rows. The results of the parts explosion are stored in a linked list in memory allocated by the function before they are returned to the caller.

The parts.dsw file in the is the %ONEDB_HOME%\dbdk\examples\routines\dapi\partsexplode\src directory is the Visual C++ workspace file for this DataBlade module.

Strings DataBlade module

The Strings DataBlade module illustrates how to use GLS support in user-defined routines that manipulate character strings. This DataBlade module also illustrates how to create custom Input and Output support functions for the CompressedStr data type, an opaque data type containing compressed character data. These functions compress data as it is written to the server and uncompress it as it is written out using Huffman encoding.

The Strings DataBlade module has a cast to convert numeric values to a character string: for example, the number 117 is cast to the string "one hundred seventeen."

The strings.dsw file in the %ONEDB_HOME%\dbdk\examples\routines\dapi\strings\src directory is the Visual C++ workspace file for this DataBlade module.

TopK Terms DataBlade module

The TopK Terms DataBlade module illustrates how to take a set as an argument and returning a set with a user-defined iterator function. The TopK() function finds the top k integer terms from a set of integers.

The topk.dsw file in the %ONEDB_HOME%\dbdk\examples\routines\dapi\topkterms\src directory is the Visual C++ workspace file for this DataBlade module.

UDTExporter DataBlade module

The UDTExporter DataBlade module illustrates how to use extended data types on an ESQL/C client. The UDTExporter DataBlade module contains row data types, collection data types, an opaque data type (ComplexNumber), qualified data types, and distinct data types. An additional program is provided, udtexpo.ec, in the %ONEDB_HOME%\dbdk\examples\Client\esqlc\UDTExporter directory. This program illustrates:

The UDTExporter DataBlade module illustrates how to use extended data types on an ESQL/C and a C++ client. The UDTExporter DataBlade module contains row data types, collection data types, an opaque data type (ComplexNumber), qualified data types, and distinct data types. Two additional programs are provided: an ESQL/C program, udtexpo.ec, in the %ONEDB_HOME%\dbdk\examples\Client\esqlc\UDTExporter directory; and a C++ program, cppclient.cpp, in the %ONEDB_HOME%\dbdk\examples\Client\c++api\UDTExporter directory. These programs illustrate:

  • creating tables with each kind of data provided in the DataBlade module.
  • inserting values into the tables.
  • retrieving values from the tables.

For information on how to run the client programs, see the readme.txt file for ESQL/C client.

For information on how to run the client programs, see the readme.txt file for ESQL/C client and the readme.txt file for C++.

For the ESQL/C program, the udtexporter.dsw file is the source code for the ComplexNumber data type support routines.

For the C++ program, the udtexporter.dsw file is the source code for the ComplexNumber data type support routines.