Creating Data Types

You can create the extended data types described in the following sections in BladeSmith:

• Collection Data Type, next
• Distinct Data Type
• Opaque Data Type
• Row Data Type

In addition, you must define qualified built-in data types (see Qualified Data Type) before you can use them in a BladeSmith project.

Collection Data Type

A collection data type is a set of elements of another, single data type. Collection elements can never be null.

You can overload existing user-defined routines and built-in routines to work on your collection data type. You can also define custom support routines for your collection data type. See Creating Routines for instructions.

The following table lists the properties you specify when you create a collection data type.

See the IBM Informix: Guide to SQL Tutorial for general information on collection data types.

The following sections describe properties of collection data types.

Valid Element Data Types

You can create a collection with elements of any data type listed in your project except SERIAL or SERIAL8. You can define a collection type of an existing collection or row data type. For example, you can define a list of a set of integers in SQL:

LIST(SET(integer not null))

You can also create collections of opaque or distinct data types.

Type Constructors

The type constructor determines the structure of the collection. The following table shows the options between the type constructors.

See the IBM Informix: Guide to SQL Reference for more information about collection type constructors.

Distinct Data Type

A distinct data type has an internal and external representation identical to another data type, but the database server treats it as a different data type. Any existing routines on the source data type are automatically registered on the distinct data type. However, you can define new routines that operate only on the distinct data type.

You can define custom support routines and user-defined routines for your distinct data type. You can also overload existing user-defined routines and built-in routines to work on your distinct type. See Creating Routines for instructions.

The following table lists the properties you specify when you create a distinct data type.

When you create a distinct data type, the database server creates explicit casts between the source data type and the distinct data type; however, you can also create implicit casts between a distinct data type and its source data type.

See the IBM Informix: Guide to SQL Reference for more information on distinct data types.

Opaque Data Type

An opaque data type is a C structure or C++/ActiveX class. The database server does not interpret the contents of the structure. Instead, it calls support routines that you provide to manipulate the structure.

BladeSmith generates much of the code for the support routines. You must complete the code and compile the source code.

The following table lists the properties you specify when you create an opaque data type.

See IBM Informix: User-Defined Routines and Data Types Developer's Guide for more information on opaque data types.

The following sections describe the properties of opaque data types you need to define when you create an opaque data type with BladeSmith.

Opaque Data Type Name Lengths

The limit of the opaque data type name is determined by the version of the database server and the client implementation language, as shown in the following table.

Server Implementation

The server implementation is the programming language in which you implement your opaque data type within the database server. Each language has restrictions on the functionality you can specify for your opaque data type:

• C. You cannot choose a client implementation or accessor methods in C.
• C++. See Opaque Type Limitations for C++/ActiveX for a list of C++ restrictions.
• Java. You cannot generate Java code for opaque types with DBDK 4.0.

Client Implementation

A client implementation of your opaque data type is a value object, which BladeSmith generates in the programming language you specify. A value object is a client-side interface to an opaque data type and its support routines. Client and server implementations need not be in the same programming language.

For information on the implications of using different languages for server and client implementations, see Mixing Languages in Server and Client Implementations.

For more information on value objects, see ActiveX Value Objects.

Accessor Methods

If you choose to create a client implementation of your opaque data type, you can specify whether to generate accessor methods. Choosing this option makes the members of the opaque data type available as properties, allowing client-side access to those values. BladeSmith generates set and get methods for each property.

For more information on ActiveX accessor methods, see ActiveX Properties.

Definition of Internal Structure

You can specify an undefined internal structure for an opaque data type with a server implementation in C or Java.

The internal structure of the opaque data type is not known to the database server. The support routines you define for the opaque data type operate on the internal structure.

If you define the internal structure of your opaque data type to BladeSmith, BladeSmith generates useful code for it. If you do not specify the internal structure, BladeSmith generates code that operates as if your opaque data type is a stream of bytes.

Fixed or Variable Size

You can specify a variable-sized structure for an opaque data type with a server implementation in C or Java.

An opaque data type can have a fixed size that is determined by the sum of the sizes of the data structures within the opaque data type. The maximum size is 32 KB.

Alternatively, an opaque data type can have a variable size if one of its internal data structures does not have a fixed size. Typically, variable data structures are smart large objects or other opaque data types. Variable-length data structures can have a maximum size. Variable-length opaque data types are treated as bit-varying types.

Member Information

Specify the following information about the internal members of your opaque data type:

• Name. Must be unique within the opaque data type.
• Data structure. Select from the list, which includes any extended data types you have defined or imported in the project and the data structures that correspond to the programming language you choose.
• Array size. Specifies the number of components and subcomponents.

The following table maps the DataBlade API data structures listed in the Opaque Type wizard to their external programming language equivalents.

If you choose to create a variable-length opaque data type, a member is automatically added as an mi_int1 of variable size. Change the mi_int1 data structure to be the one you need. Be sure to list the variable-length member last.

Maximum Size

If you create a variable-length opaque data type, specify the maximum allocated length of that data type. The database server does not allow an opaque data type to grow beyond its maximum length. If you choose to specify a maximum length, the maximum value is 32,767 bytes. This value, however, is the maximum size of a row in a database table. Therefore, if your opaque data type is 32,767 bytes, you cannot have any other columns in your table.

Memory Alignment

If you do not specify the internal structure of your opaque data type in BladeSmith, you must choose the memory alignment of the first member; your compiler aligns the other members with this value. Choose an alignment value that corresponds to the greatest alignment requirement in the data structure. The default alignment is 4. If you do not know the alignment of the member with the greatest alignment, choose 8.

See IBM Informix: User-Defined Routines and Data Types Developer's Guide for more information on memory alignment.

Support Routines

You can select from the following categories of support routines to support your opaque data type:

• Basic Text Input and Output
• Binary Send and Receive
• Text Import and Export
• Binary File Import and Export
• Contains Large Objects (not available for C++)
• Type Insert and Delete Notification (not available for C++)
• Type Compare Support
• B-Tree Indexing Support
• Type Mathematic Operators
• More Mathematic Operators
• Type Concatenation Operator
• Type Hash Support
• Statistics Support (not available for C++ or Java)

These support routines are described in the following sections.

Basic Text Input and Output

This category is valid for the C and C++ languages. BladeSmith generates this category by default.

Basic text input and output functions convert between the text representation of the opaque data type and the internal database server format.

The text representation of an opaque data type is an mi_lvarchar value that contains a printable representation of an instance of the data type. The text representation enters values for the data type in SQL statements such as INSERT and displays values in output from SQL statements such as SELECT.

The names of these functions differ for different programming languages, as listed in the following table.

Language

Function Names

SQL

OpaqueIn()

OpaqueOut()

C

OpaqueInput()

OpaqueOutput()

C++

FromString()

ToString()

Binary Send and Receive

This category is valid for the C and C++ languages. BladeSmith generates this category by default.

Binary send and receive functions transfer the binary representation of the opaque data type to and from the client.

Binary send and receive functions allow the client and server to execute on different platforms, with different data type representations. When a client connects with a server, it sends a description of its data representation. The server calls the binary send function to convert opaque data type values to the client format before sending them to the client. The binary receive function converts a value arriving from the client binary format to the server binary format.

You do not have to know the specifics about data representation on different platforms to convert an instance of a data type. Binary send and receive functions call DataBlade API routines for each member of the structure to convert values to the appropriate C data type representation for the destination platform.

The names of these functions differ for different programming languages, as listed in the following table.

Language

Function Names

SQL

OpaqueSend()

OpaqueRecv()

C

OpaqueSend()

OpaqueReceive()

C++

Send()

Receive()

Text Import and Export

This category is valid for the C and C++. BladeSmith generates this category by default.

Text file import and export functions transfer the text representation of the opaque data type to and from a flat file.

Text file import and export functions enable bulk copy for opaque data types. When you copy data from a file into a database with PLOAD or the DB–Access LOAD command, the server calls a text file import function to convert the incoming value to the server binary format. When data is copied out of the database into an external file, the server calls a text file export function to convert the value from server binary format to text file format.

You need text file import and export functions for opaque data types that include large objects or that are exported to a disk file. On copy-out, the text file export function creates a file on the client, writes the large object data to it, and then sends the name of the file as the data value for storage in the copy file. The text file import function takes the filename, opens it, and loads the large object data. This method stores large object data independent from the copy file so that the copy file is smaller and easier to read.

If you do not define text file import and export routines, the server calls the text input and output routines.

The names of these functions differ for different programming languages, as listed in the following table.

Language

Function Names

SQL

OpaqueImpT()

OpaqueExpT()

C

OpaqueImportText()

OpaqueExportText()

C++

ImportText()

ExportText()

Java

textImport()

textExport()

Binary File Import and Export

This category is valid for the C and C++ languages. BladeSmith generates this category by default.

Binary file import and export functions transfer the binary representation of the opaque data type to and from a flat file.

Use the binary file import and export functions for bulk copy of binary data. These functions are the same as the text file import and export functions, except that they operate on binary representations of the data type. The functions are called when PLOAD executes.

The names of these functions differ for different programming languages, as listed in the following table.

Language

Function Names

SQL

OpaqueImpB()

OpaqueExpB()

C

OpaqueImportBinary()

OpaqueExportBinary()

C++

ImportBinary()

ExportBinary()

Contains Large Objects

This category is valid for the C language.

The LOhandles() function retrieves a list of the pointer structures for the smart large objects embedded in the opaque data type. The database server calls the LOhandles() function to obtain a list of large objects used by an opaque data type. The LOhandles() function takes a pointer to an instance of the data type and returns an array of the large object handles used by the object.

This category also includes the Assign() function and the Destroy() procedure described in the section Type Insert and Delete Notification, next.

For the C language, BladeSmith prefixes the names of these functions with the name of the data type for which they are specified: OpaqueLOhandles(), OpaqueAssign(), and OpaqueDestroy().

Type Insert and Delete Notification

This category is valid for the C language.

The Assign() function and the Destroy() procedure perform tasks before storing or deleting an opaque data type on disk: for example, to ensure proper reference counting on smart large objects.

You can provide Assign() and Destroy() routines for an opaque data type that requires special processing when an instance is stored in a database or removed from the database. The database server calls the Assign() function before it writes a value to a table. The database server calls the Destroy() procedure before it deletes a value from a table.

For example, opaque data types that include large objects require special handling before they are stored on disk or removed from a table. The database server maintains a reference count for large objects to ensure that an object is not dropped while a row in the database references it. When a reference to a large object is inserted into a table, the Assign() function increments the reference count. When a reference to a large object is deleted from a table, the Destroy() procedure decrements the reference count.

For the C language, BladeSmith prefixes the names of these functions with the name of the data type for which they are specified: OpaqueAssign() and OpaqueDestroy().

Type Compare Support

This category is valid for the C and C++ languages. BladeSmith generates this category by default.

Type comparison functions Compare(), Equal() (bound to the = operator), and NotEqual() (bound to the <> and != operators) compare two opaque data types: for example, to support an ORDER BY clause in a query.

For the C language, BladeSmith prefixes the names of these functions with the name of the data type for which they are specified: OpaqueCompare(), OpaqueEqual(), and OpaqueNotEqual().

B-Tree Indexing Support

This category is valid for the C and C++.

The following B-tree strategy and support functions support using the B-tree secondary access method to create an index on your opaque data type column:

• Compare()
• Equal() (bound to the = operator)
• LessThan() (bound to the < operator)
• GreaterThan() (bound to the > operator)
• LessThanOrEqual() (bound to the <= operator)
• GreaterThanOrEqual() (bound to the >= operator)
• NotEqual() (bound to the != and the <> operators)

Defining these routines for opaque data types allows fast B-tree index searches on the new data types. If a query uses the operator bound to one of the functions, the optimizer can evaluate strategies that use the index.

For the C language, BladeSmith prefixes the names of these functions with the name of the data type for which they are specified: OpaqueCompare(), OpaqueEqual(), OpaqueLessThan(), OpaqueGreaterThan(), OpaqueLessThanOrEqual(), and OpaqueGreaterThanOrEqual().

R-Tree Indexing Support

Version 4.0 of BladeSmith does not generate code for R-tree support routines.

Refer to the IBM Informix: R-Tree Index User's Guide or the IBM Informix Developer Zone at www.ibm.com/software/data/developer/informix for information about creating DataBlade modules that use the R-tree secondary access method.

Type Mathematic Operators

This category is valid for the C and C++ languages.

Binary arithmetic operators Plus() (bound to the + operator), Minus() (bound to the - operator), Times() (bound to the * operator), and Divide() (bound to the / operator) perform operations on your opaque data type.

If you define these routines for an opaque data type, the database server can resolve mathematic expressions in the select list or WHERE clause of a query.

For the C language, BladeSmith prefixes the names of these functions with the name of the data type for which they are specified: OpaquePlus(), OpaqueMinus(), OpaqueTimes(), and OpaqueDivide().

More Mathematic Operators

This category is valid for the C and C++ languages.

Unary arithmetic functions Positive() (bound to the + operator) and Negate() (bound to the - operator) perform operations on your opaque data type.

If you define these routines for an opaque data type, your database server can resolve mathematic expressions in the select list or WHERE clause of a query.

For the C language, BladeSmith prefixes the names of these functions with the name of the data type for which they are specified: OpaquePositive() and OpaqueNegate().

Type Concatenation Operator

This category is valid for the C and C++ languages.

The Concat() function (bound to the || operator) concatenates the values of two opaque data types.

For the C language, BladeSmith prefixes the names of these functions with the name of the data type for which it is specified: OpaqueConcat().

Type Hash Support

This category is valid for the C and C++ languages.

You should define a Hash() function for your opaque data type if the database server cannot use the built-in hashing function to cache its return values.

Most data types are bit-hashable and can use the built-in hash routine.

Bit-hashable data types have the property that for any hash routine:

if A = B then hash(A) = hash(B)

In practice, this means that A and B have identical bit representations.

There are some data types for which two equal values have different bit representations. For example, in one's-complement notation, there are two distinct representations for 0 (+0 and -0). The SQL rules for the data type VARCHAR require that trailing blanks be ignored in equality comparisons. Thus, two VARCHAR values with different numbers of trailing blanks will have different bit representations, but they should still be considered equal.

For data types that are not bit-hashable, you must provide a Hash() function.

For the C language, BladeSmith prefixes the names of these functions with the name of the data type for which it is specified: OpaqueHash().

Statistics Support

Statistics support is available with Dynamic Server Version 9.2 and later.

This category is valid for the C language.

User-defined statistics provide a way to improve performance when you compare opaque data type values. User-defined statistics compile information about the values in an opaque data type column that the query optimizer can use when it creates a query plan.

You can define statistics support functions for an opaque data type and then a selectivity function for a routine that takes opaque data types as its arguments. See User-Defined Statistics for more information on user-defined statistics.

Statistics support functions are OpaqueStatCollect(), OpaqueStatPrint(), Opaque_SetMinValue(), Opaque_SetMaxValue(), and Opaque_SetHistogram().

Qualified Data Type

A qualified data type is a built-in data type with additional specifications that provide information about the storage size, range of values, or precision of the data type. For example, CHAR is a built-in data type, but CHAR(16) is a qualified data type because you are fixing its length. You must add a qualified data type to a BladeSmith project before you can use it as a component of an extended data type.

When you create a qualified data type in a BladeSmith project, BladeSmith adds to the list of data types from which you choose when creating extended data types. Qualified data types do not need SQL or source code.

For example, to create a collection data type that stores sets of 16-byte character strings, you must first create a CHAR(16) qualified data type. Then create the collection data type, choosing CHAR(16) as the base data type and SET as the constructor function. The new data type has the following SQL definition:

SET(CHAR(16) not null)

The following table lists the data types that take qualifications.

Data Type

Qualification

CHARACTER, CHAR

(size)

CHARACTER VARYING

(size, minimum)

DATETIME

largest_qualifier TO smallest_qualifier

DECIMAL, DEC

(precision, scale)

INTERVAL

largest_qualifier(n) TO smallest_qualifier(n)

MONEY

(precision, scale)

NCHAR

(size)

NVARCHAR

(size, minimum)

SERIAL, SERIAL8

(start value)

VARCHAR

(size, minimum)

BladeSmith restricts your input for qualification values to valid choices.

See IBM Informix: Guide to SQL Reference for more information about qualified data types.

Row Data Type

A row data type is a group of fields of existing data types arranged like a row in a table. The fields of a row data type can be almost any data type that exists in your project, including other row data types.

You can overload existing user-defined routines and built-in routines to work on your row type. See Creating Routines for instructions.

The following table lists the properties you specify when you create a row data type.

The following sections describe properties of row data types.

Named and Unnamed Row Data Types

You can create a named or an unnamed row data type.

A named row data type has these general characteristics:

• Its name is unique.
• It supports inheritance from a parent row data type or to a child row data type.
• It can be used as the basis of a typed table.

An unnamed row type has these general characteristics:

• It is equivalent to any other unnamed row type with the same structure. The structure is defined by the number of fields, the data types of the fields, and the order of the fields.
• It does not support inheritance.
• It cannot be used as the basis of a typed table.

See the IBM Informix: Guide to SQL Tutorial for more information on named and unnamed row data types.

Row Data Type Inheritance

Named row data types can inherit from other named row data types. A child row data type inherits its parent's fields and can be passed to all routines defined for the parent data type.

You can add additional fields and routines that are only valid for the child data type.

See the IBM Informix: Guide to SQL Tutorial for more information on inheritance.

Row Data Type Fields

Fields in row data types can be any existing data type except SERIAL and SERIAL8.