The default BladeSmith locale, en_us.8859-1, is for U.S. English using code set 8859. This is the default locale for the Informix database server on UNIX platforms. 
The following sections describe properties of errors.
Error codes are allocated for your DataBlade module by the Informix DataBlade Developers Program registry, to ensure that your error codes do not conflict with built-in error codes and those of other DataBlade modules.
See Contacting the Informix Registry for information on how to design and register your error codes.
The error locale enables the database server to select a translated error or trace message for a localized database. The locale is specified using the format language_country.codeset. Be sure to create messages for all of the locales in which your DataBlade module executes.
The default BladeSmith locale, en_us.8859-1, is for U.S. English using code set 8859. This is the default locale for the Informix database server on UNIX platforms.
The default code set for the Informix database server on Windows NT is 1252. Create U.S. English messages using locale en_us.1252 for Windows NT database servers.
For more information on locales, see the Guide to GLS Functionality.
The SQL error text is displayed with the error code in the language specified by the message locale. To specify parameters in messages, assign each parameter a unique name enclosed in percent characters ( % ). For example, an input function could send the following message when it is unable to translate an input value:
For information about tracing and calling error messages, see the DataBlade API Programmer's Manual.
If you expect other DataBlade modules to use the functionality provided by your DataBlade module, create an interface. DataBlade developers can include the interface in a DataBlade module to ensure that BladeManager registers the DataBlade module with the interface before registering the DataBlade module dependent on the interface.
The interface you define encompasses all of your DataBlade module.
The following table lists the properties you specify when you create an interface.
For Dynamic Server Version 9.2, the maximum length of an interface name is 64 characters.
For Dynamic Server Version 9.14, the maximum length of an interface name is 18 characters.
You can define public or private user-defined routines that support your DataBlade module. You can specify if the routine is called by SQL or is an internal routine.
Routines can be functions, which return values, or procedures, which do not return values. Routines can be written in the C or Java programming languages or the Informix Stored Procedure Language (SPL).
Use the New Routine wizard to:
The following table lists the properties you specify when you create a routine.
The SQL that BladeSmith generates for routines uses the ALTER FUNCTION statement to specify all but the following properties:
Using the ALTER FUNCTION statement allows BladeManager to reregister the routine without dropping and re-creating it.
The following sections describe properties of routines.
Specify the name of an existing routine to overload it for a new data type, or specify a unique routine name to create a new routine.
If you are creating a selectivity routine for a user-defined routine, name the selectivity routine RoutineSelectivity.
You can overload built-in operator and other arithmetic routine for collection, row, and distinct data types. (You can overload most arithmetic routines for opaque data types with the New Opaque Type wizard.) How arithmetic routines operate on collection and row data types is determined by the code you write for them. For example, if you overload the Plus() function for a row data type, it might either:
See Extending Informix Dynamic Server 2000 for a list of built-in routines you can overload.
Although it is not necessary, you can create new support routines for collection, row, and distinct data types.
If you want your function to return two values, check the statement local variable check box. The last argument for your function is then defined as an OUT parameter. The OUT parameter corresponds to a value the function returns indirectly, through a pointer, to a statement local variable (SLV). The value the function returns through the pointer is an extra value, in addition to the value it returns explicitly.
The SLV provides a temporary name that a single statement can manipulate. An SQL statement uses each SLV to transmit the output from a single function to other parts of the SQL statement.
See the DataBlade API Programmer's Manual for more information.
A routine can accept 0 to 20 arguments.
Arguments passed to a routine have the following properties:
By default, user-defined functions are variant. Variant functions can return different values or have varying side effects, given the same arguments. For example, a function that returns the current date or time is a variant function. However, a function that appears nonvariant can also have varying side effects, such as updating a table or external file.
The cost of defining a nonvariant function as variant is low: you might experience slightly diminished performance. However, the cost of defining a function that exhibits variant behavior as nonvariant can be high, because a query might return incorrect results.
Most functions are not variant; marking them as nonvariant improves performance. If the function is nonvariant, the database server might cache the return values of expensive functions or run parallel queries. Functional indexes are only allowed on nonvariant functions.
See the Extending Informix Dynamic Server 2000 manual for more information.
Mark a routine as parallelizable if it can be executed within a parallel database query (PDQ) statement. PDQ statements allow the Informix database server to distribute the executions of one query among several processors by dividing the query into subqueries. The database server then allocates subqueries to separate threads for parallel processing and thus improves performance. See Extending Informix Dynamic Server 2000 for more information about using the parallelizable option.
Use routine parallelization if your routine is used as an expression in qualification clauses, in GROUP BY lists, or as an overloaded comparison operator.
A routine cannot be parallelizable if it accepts row or collection data types as arguments.
C and Java routines are parallelizable if they call only the DataBlade API routines listed in the following categories from the DataBlade API Programmer's Manual:
See the DataBlade API Programmer's Manual for more information about the routines under each category.
SQL allows overloading of routine names; however, the C language does not. Therefore, if you overload a routine, you must give it a unique C name.
A routine is well-behaved within the context of Informix database server architecture if it:
If your routine violates one of these conditions, mark it as poorly behaved and type the name of a user-defined virtual processor in the user-defined virtual processor class field.
The name of the grouping class for the user-defined virtual processor must be 128 alphanumeric characters or fewer, and it must be unique. The class name is case insensitive. Informix recommends that you begin the name of your virtual processor class with your DataBlade module new object prefix. If you want to have your DataBlade module certified by Informix, virtual processor classes must begin with the DataBlade module prefix.
Tip: You can create a routine that references a virtual processor class before that class exists. However, you must create the virtual processor class and create virtual processors in it before you register your DataBlade module in the database.
Stack Size
You can specify stack size only for a user-defined routine written in C.
Stack space is allocated from a common region in shared memory that can be overrun if a routine consumes more stack space than is allocated for it. To avoid stack overrun:
When you specify a stack size for a user-defined routine, the database server allocates the specified amount of memory for every execution iteration of the routine.
See the Administrator's Guide for Informix Dynamic Server 2000 for more information on stacks.
You can specify cost only for user-defined routines written in C.
The relative cost of the routine is used by the query optimizer to determine the order in which to process WHERE clauses in a SELECT statement. Expensive routines are called after inexpensive routines. A cost of 0 indicates that the routine costs about the same as the routines in the reference list that have a cost of 0. The reference list shows all user-defined routines created in the project. The standard formula for computing routine cost is:
Because the optimizer compares routine costs, the actual cost is irrelevant; only the relative cost matters. However, follow the general formula to ensure that your routines interact with other DataBlade module routines in a predictable way.
If your user-defined function compares or acts as a filter for two instances of the same data type and returns a Boolean result, you can specify related functions to optimize the execution of the function when it is called in the WHERE clause of a SELECT statement.
Important: Related functions must exist before you can choose them. You can create them before you create the function they are related to, or you can update the original routine to add related routines after you create them.
Commutator and Negator Functions
You can specify a commutator function only for user-defined routines written in C.
The database server calls a commutator or a negator function instead of the original function if the query optimizer determines that it is faster. A commutator function returns the same Boolean result as the original function with the same arguments but with the arguments in reverse order. A negator returns the opposite Boolean result as the original function with the same arguments in the same order.
Selectivity FunctionsYou can specify a selectivity function only for user-defined routines written in C.
A selectivity function estimates the percentage of rows that might be returned by your function, given a set of arguments. Define a selectivity function if you want to determine the cost of your function so that the query optimizer can determine when it is most efficient to call your function. Selectivity functions determine the cost of a function with statistics gathered about the values of the data type on which the function operates. See User-Defined Statistics for more information on selectivity functions and how they process user-defined statistics.
You can create a selectivity function for your user-defined function if your function compares or acts as a filter for two values of the following kind of data types:
An opaque data type for which you have created user-defined statistics support routines (see Statistics Support) The B-tree functions Equal() and NotEqual() that are overloaded for an opaque data type are good candidates for selectivity functions. Because the Equal() and NotEqual() functions are created with the Opaque Type wizard, you must add selectivity support by assigning selectivity routines on their properties pages after you create them.
Built-in data types have built-in statistics support routines, and all qualifying built-in functions (such as B-tree functions) have built-in selectivity functions. You can only create selectivity functions for functions that take built-in data types if those functions are user-defined.
A selectivity function must have the following properties:
For a description of user-defined statistics and selectivity, see User-Defined Statistics.
You can create the extended data types described in the following sections in BladeSmith:
In addition, you must define qualified built-in data types (see Qualified Data Type) before you can use them in a BladeSmith project.
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.
| Property | Default Value | Description |
|---|---|---|
| Type | None | The data type that makes up the collection. See Valid Element Data Types for more information. |
| Constructor | None | The type constructor: LIST, MULTISET, or SET. See Type Constructors for more information. |
See the Informix Guide to SQL: Tutorial for general information on collection data types.
The following sections describe properties of collection data types.
Valid Element Data TypesYou 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:
You can also create collections of opaque or distinct data types.
Tip: If you create a collection with an element of type BLOB or CLOB, you can test for the existence of a particular sbspace when your DataBlade module is being registered in a database using BladeManager. For information, see Appendix C, Testing for an Sbspace.
Type Constructors
The type constructor determines the structure of the collection. The following table shows the options between the type constructors.
See the Informix Guide to SQL: Reference for more information about collection type constructors.
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.
Tip: If you create a distinct type with a source type of BLOB, CLOB, or an opaque data type containing BLOB or CLOB arguments, you can test for the existence of a particular sbspace when your DataBlade module is being registered in a database using BladeManager. For information, see Appendix C, Testing for an Sbspace.
See the Informix Guide to SQL: Reference for more information on distinct data types.
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 Extending Informix Dynamic Server 2000 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 LengthsThe 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:
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 MethodsIf 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 StructureYou 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 SizeYou 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 InformationSpecify the following information about the internal members of your opaque data type:
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.
Tip: If you create an opaque type with a member of type MI_LO_HANDLE, you can test for the existence of a particular sbspace when your DataBlade module is being registered in a database using BladeManager. For information, see Appendix C, Testing for an Sbspace.
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 AlignmentIf 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 Extending Informix Dynamic Server 2000 for more information on memory alignment.
Support RoutinesYou can select from the following categories of support routines to support your opaque data type:
These support routines are described in the following sections.
Basic Text Input and OutputThis 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() |
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() |
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() |
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() |
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 NotificationThis 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 SupportThis 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 SupportThis 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:
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 SupportVersion 4.0 of BladeSmith does not generate code for R-tree support routines.
Refer to the Informix R-Tree Index User's Guide or the Informix Developer Network Web site at http://www.informix.com/idn for information about creating DataBlade modules that use the R-tree secondary access method.
Type Mathematic OperatorsThis 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 OperatorsThis 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 OperatorThis 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 SupportThis 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:
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().
Tip: Statistics support functions reside in the statistics.c source code file, instead of in the opaque.c source code file with all other opaque data type support routines.
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:
The following table lists the data types that take qualifications.
BladeSmith restricts your input for qualification values to valid choices.
See Informix Guide to SQL: Reference for more information about qualified data types.
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 TypesYou can create a named or an unnamed row data type.
A named row data type has these general characteristics:
An unnamed row type has these general characteristics:
See the Informix Guide to SQL: Tutorial for more information on named and unnamed row data types.
Row Data Type InheritanceNamed 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 Informix Guide to SQL: Tutorial for more information on inheritance.
Row Data Type FieldsFields in row data types can be any existing data type except SERIAL and SERIAL8.
Tip: If you create a row data type with a field of type BLOB or CLOB, you can test for the existence of a particular sbspace when your DataBlade module is being registered in a database using BladeManager. For information, see Appendix C, Testing for an Sbspace.