• Aggregates. To perform user-defined aggregating computations on data.
• Data Types. To characterize data to the database server (either built-in data types or new data types).
• Routines. To operate on or return data.
• Casts. To convert data from one type to another.
• Interfaces. To create dependencies between DataBlade modules.
• Errors. To create messages raised by user-defined routines that appear as standard database server messages.
• Functional Tests. To validate your DataBlade module routines.
• Imported SQL Files. To include custom SQL statements to create tables, user-defined access methods, and other database objects in your DataBlade module.
• Imported Client Files. To include client components, such as query tools and ActiveX value objects, in your DataBlade module package.

Aggregates

You can define two types of aggregates:

• Built-in aggregates that are overloaded to work with extended data types
• New, user-defined aggregates that implement user-defined routines

For more information on defining aggregates, see the DataBlade Developers Kit User's Guide.

Data Types

The following table lists the categories of data types available to you when you create a DataBlade module. You must define some of these data types; others you can use just as they are.

Data Type	You Define?	Code Needed?	Description
Built-in	No	No	A native Informix data type that comes with the database server
Qualified built-in	Yes	No	A built-in data type that takes one or more qualifications, such as storage size, range of values, or precision
Opaque	Yes	Yes (much of the basic code needed to implement an opaque type is generated automatically by BladeSmith)	A structured data type whose internal members cannot be accessed directly using SQL statements
Distinct	Yes	No	A unique name for an existing built-in or extended type
Collection	Yes	No	A group of elements of the same data type
Row	Yes	No	A structured data type whose internal members can be directly accessed through SQL statements

An extended data type is a data type that is not built into Informix Dynamic Server. Extended data types include opaque data types, distinct data types, collection data types, and row data types. Extended data types are described in the Extending INFORMIX-Universal Server: Data Types manual.

Collection and row data types are extended data types built from a combination of other data types; their components are accessed through SQL statements.

Built-in Data Type

Built-in data types are automatically included in your DataBlade module project file as imported objects.

For a complete list and descriptions of built-in data types, see the Informix Guide to SQL: Reference manual.

Qualified Built-in Data Type

You must define a qualified data type with BladeSmith by specifying its qualifications.

Example

More Information

Opaque Data Type

You can write opaque type support routines in C. If you provide ActiveX value objects as a client-side interface to your opaque data types, you can write the underlying support routines for the opaque data type in C++. Much of the basic code for support routines is generated automatically by BladeSmith. See "Support Routines" for more information.

Opaque data types typically contain more than one member, so they are similar to row data types, except that the database server can only access the individual components through accessor routines you define in the DataBlade module.

What Does an Opaque Data Type Look Like?

The table circle_tab consists of the columns circle_id(SERIAL), color(VARCHAR(15)), and circle_col(circle). The opaque data type circle is defined as a C structure, circle_t, which contains a radius member and another structure, point_t. The point_t structure contains an x and y member. To the database server, however, the whole circle_t structure is indivisible, unless you provide accessor functions.

Why Use an Opaque Data Type?

Many sorts of rich media data (images, audio, video, and so on) are typically represented by opaque types.

Opaque types require more work to create than other data types because you must write all the routines that support them.

More Information

Distinct Data Type

Why Use a Distinct Data Type?

You can use distinct data types to create inheritance hierarchies, which allow you to write very selective routines. A distinct data type can be passed to all routines defined for the source; however, the source data type cannot be passed to routines defined for the distinct data type.

Example

More Information

Collection Data Type

For a SET, the database server prevents insertion of duplicate elements. For a MULTISET, the database server takes no special actions. For a LIST, the database server orders the elements.

Elements can be almost any type, including other collection or row data types. You can access any element in a collection individually through SQL statements.

The number of elements in a collection is not mandated. You can change the number of elements in a collection without reinserting it into a table, and different rows can have different numbers of elements in their collections.

What Does a Collection Look Like?

Instead of putting contact information in a separate table, all the information is contained in one row, using a collection data type. You can add or remove elements without altering the table's columns.

Why Use a Collection Data Type?

Use a collection if you have data of the same data type that can be naturally grouped into a single column with a variable number of elements. You can group data even further by creating a collection of row types or other collections.

Collections are also useful as returned values: for example, a group of values from many rows in a column or fields in a row type. For example, if you want to obtain a list of every city in which your employees live from the sample collection data type in Figure 1-3, you could create a collection on the City column to return a set of values.

The following function types can return collections:

• A user-defined function that returns a collection
• An iterator function that returns a single value at a time but is called repeatedly to assemble a collection

Row Data Type

To create a row data type, you specify:

• a unique name for the whole row type.
• a unique name for each field.
• a data type for each field.

Instead of having additional columns in the Address table, the row data type groups data that is most often accessed together in one column. The table Address consists of the columns Name(LVARCHAR(30)), Address(address_t), and Dependents(SET(LVARCHAR)). The row data type address_t consists of the named fields Street(LVARCHAR(20)), City(LVARCHAR(20)), State(CHAR(2)), and Zip_code(INTEGER).

Why Use a Row Data Type?

Use a row type if you have data of differing data types that group naturally into a single column. You can further group your data if you include a collection or another row data type as a field within your row data type.

For best performance, use row data types if most user queries access all or most of the row data type's fields.

You can use row data types to create inheritance hierarchies, allowing you to write very selective routines. A child row data type inherits its parent's fields and can be passed to all routines defined for the parent; however, the parent data type cannot be passed to routines defined for the child data type.

More Information

Routines

A routine can be a function, which returns values, or a procedure, which does not. You can write routines in the Informix Stored Procedure Language (SPL), or in an external language, such as C. If you write database server-side routines in C, the DataBlade API provides access to a library of routines defined inside the database server. This library provides data manipulation and SQL query facilities to a DataBlade routine.

Routine overloading, or polymorphism, refers to writing a routine that performs the same task and has the same name as an existing routine, but takes a different data type as an argument. When you create opaque, collection, or row types, you can overload existing routines for your new data type. When the overloaded routine is called, Informix Dynamic Server determines which variant of the routine to use by examining the argument. BladeSmith creates a template for the overloaded routine; however, you must fill in the code to enable the routine to complete the assigned task.

You can overload built-in and operator functions for all data types except built-in data types. You can create user-defined routines for all categories of data types. You can create support routines for all extended data types. You must create support routines for opaque data types.

Built-in Functions and Operator Functions

When you overload a built-in or operator function, you must specify what the function does and what it returns. For example, if you overload the plus() function on a row type, you can choose to:

• add the respective field values and return a row type with the same number of fields as the input row types.
• return a row type that contains all the fields of the first input row type followed by all the fields of the second input row type.

For more information, see the Extending INFORMIX-Universal Server: User-Defined Routines manual.

User-Defined Routines

Support Routines

BladeSmith allows you to generate support routine code for opaque data types. You may have to add code to implement the functionality your opaque data type requires.

The following table describes the support routines you can create, and indicates for which category of opaque types they are recommended.

Function	Recommended for	Description
Text input/ output	All opaque types	Converts between external and internal representations. These functions implicitly cast between the opaque type and the LVARCHAR type.
Send/receive	All opaque types	Converts between internal representation on the database server and client computers. These functions implicitly cast between the opaque type and the SENDRECV type.
Text import/ export	All opaque types	Processes opaque types for bulk loading and unloading of textual data. These functions implicitly cast between the opaque type and the IMPEXP type.
Import binary/ export binary	All opaque types	Processes opaque types for bulk loading and unloading of binary data. These functions implicitly cast between the opaque type and the IMPEXPBIN type.
Assign/ Destroy	Large objects and multi- representational types	Processes opaque types that contain smart large objects or are multirepresentational for storage to and removal from disk.
LOhandles	Large objects	Returns the list of large-object handles in opaque types that contain smart large objects.
Compare	ActiveX value objects and other opaque data types sorted by a B-tree index	Sorts opaque type data within SQL statements and supports the B-tree access method.

You must create support routines for opaque types; built-in types already have them and row, collection, and distinct types inherit support routines from their component or source data types. You can, however, create support routines for row, collection, and distinct types if you need functionality that differs from the inherited routine.

Casts

For some data types you can choose whether the database server or the user controls casting. Create an:

• implicit cast if you want the database server to automatically convert the source data type.
• explicit cast if you want the user to specify the cast within an SQL statement.

You can use a built-in type as a source or target data type in a cast, but not as both. Built-in types have system-defined casts between each other that the database server invokes automatically.

A distinct type inherits all the casts of the source type. The database server automatically creates explicit casts between the distinct type and the source type.

For more information about casting, see the Extending INFORMIX-Universal Server: Data Types manual.

Interfaces

Interfaces can be:

• imported. These are defined interfaces from other DataBlade modules that you have installed on the database server.
• internal. These are interfaces that you define within your DataBlade module for use as imported interfaces in other DataBlade modules.

Errors

To localize your error messages, define multiple messages using the same error code, a different locale, and the message text for that locale. Which message the user sees is controlled by the value of the locale environment variables.

For more information, see the DataBlade Developers Kit User's Guide.

Functional Tests

For more information, see the DataBlade Developers Kit User's Guide.

Imported SQL Files

You can specify dependencies between objects in your DataBlade module and your custom SQL. These dependencies determine the sequence in which the SQL statements are executed when you register the DataBlade module.

For more information, see the DataBlade Developers Kit User's Guide.

Imported Client Files

• graphical user interfaces.
• documentation and help files.
• shared object files, dynamic link libraries, or header files containing DataBlade module routines executed in the client address space.

For more information, see the DataBlade Developers Kit User's Guide.