Important: If you use text input and output functions for smart large objects, you must define Assign() and Destroy() routines to prevent runtime errors from the database server.
The corresponding code for the CircReceive() function is identical, except it uses mi_get_double_precision() instead of mi_put_double_precision().
In general, you do not need to modify the generated binary send and receive functions. If you do add code to one of the functions, you must make corresponding changes to the other function. You can alter the binary send and receive functions to encrypt data in the mi_sendrecv type before sending data to the client and decrypt data from the mi_sendrecv type before receiving data into the database.
The following example DataBlade module use the binary send and receive functions without modification:
The text file import function transfers a flat file to the text representation of the opaque data type. The C name of the text file import function for each opaque data type is OpaqueImportText().
The text file export function transfers the text representation of the opaque data type to a flat file. The C name of the text file export function for each opaque data type is OpaqueExportText().
BladeSmith generates complete C code for these functions.
The database server calls the text file import function with a pointer to an mi_impexp type containing the input text, which it retrieves from an external file, and an unused MI_FPARAM pointer. The text file import function converts the text to an instance of the opaque type and returns a pointer to it.
The text file import function allocates memory for the opaque structure that it returns and then calls Gen_sscanf() for each member of the structure, storing the scanned values in the allocated memory.
The database server calls the text file export function with a pointer to an instance of the opaque type and an unused MI_FPARAM pointer. The text file export function converts the opaque type value to a text value stored in an mi_lvarchar variable that it allocates. The generated code works the same way as the text output function.
The text file export function computes the maximum length of the text value it can return by adding the maximum lengths for each structure member. Then it calls mi_new_var() to allocate an mi_impexp argument large enough to hold the largest possible text value.
To create the output text, the function calls sprintf() once for each member of the opaque type structure, concatenating a text representation of the value to the string in the mi_impexp variable. Each value is followed by a space.
The default text file export function uses the same text representation as the input and import functions. This format allows database users to enter values for the opaque type and enables opaque types to be displayed. For bulk copy operations, however, a user-readable format is not necessary.
The default format for imported text is the same as for the text input function: a string containing each structure member, delimited with spaces. If you use a different text representation for your data type, you can modify the format strings in the Gen_sscanf() calls.
To conserve space in the external file or to match the representation required by some another application that uses the export file, you can use a different text representation for bulk copy. When you modify the text representation that the text file export function uses for copy-out operations, make corresponding modifications in the text file import function.
If the data type contains the smart large object handle data type MI_LO_HANDLE, the input contains the large object filename in double quotation marks. The text file import function calls Gen_LoadLOFromFile() to retrieve the smart large object data from the external file. The text file export function calls Gen_StoreLOToFile() to save the smart large object in an external file.
The binary file import function transfers the binary representation of the opaque data type to a flat file. The C name of the binary file import function for each opaque data type is OpaqueImportBinary().
The binary file export function transfers the binary representation of the opaque data type from a flat file. The C name of the binary file export function for each opaque data type is OpaqueExportBinary().
BladeSmith generates complete C code for these functions.
The Informix database server calls the binary file import function with an mi_impexpbin pointer containing the binary representation of an opaque type value, read from an external file. The function also receives an unused MI_FPARAM pointer.
The binary file import function translates the binary data in the mi_impexpbin structure into an instance of the opaque type and returns a pointer to the C structure containing the opaque data type. The BladeSmith-generated code allocates memory for the return structure and then calls DataBlade API mi_get functions to retrieve a value for each member of the structure.
The Informix database server calls the binary file export function with a pointer to a C structure, which contains an instance of the opaque type, and an unused MI_FPARAM pointer. The function translates the opaque type value into a binary image and returns it in an mi_impexpbin structure. The Informix database server writes the returned binary value into external files.
The binary file export function calls mi_new_var() to allocate an mi_bitvarying variable and then calls an mi_put function for each element of the opaque structure to store the value.
You should not modify the generated code for the binary file import and export functions.
If the opaque type includes large objects, the binary file import function calls Gen_LoadLOFromFile() to read the large object data from a file. The binary file export function calls Gen_StoreLOToFile() to save the smart large object in an external file.
The Assign() function performs tasks before saving an opaque data type to disk. The C name for each opaque data type is OpaqueAssign().
The Destroy() procedure performs tasks before saving an opaque data type to disk. The C name for each opaque data type is OpaqueDestroy().
BladeSmith generates complete C code for Assign() and Destroy() routines that manage large object reference counts. For other types of special processing, you must add code to the generated code.
Important: If you use text input and output functions for smart large objects, you must define Assign() and Destroy() routines to prevent runtime errors from the database server.
The Generated Code
The Informix database server calls the Assign() function with a pointer to an instance of an opaque type and a pointer to an MI_FPARAM structure that is not used by the generated code. The function returns a pointer to the opaque type to the database server. Usually, the pointer returned by the Assign() function is the same one the Informix database server passed to it. If the Assign() function alters the input opaque type in any way and returns a pointer to it, the database server stores the modified value in the database.
The Informix database server calls the Destroy() procedure before removing an opaque type from the database. It passes the Destroy() procedure a pointer to the opaque type value that is about to be removed from the database and an unused MI_FPARAM pointer. The procedure returns no value.
If your opaque data type does not contain a smart large object, you must add code to perform the required task.
If your opaque data type contains a smart large object, then the generated Assign() function manages smart large object reference counts. It calls mi_lo_validate() to determine if a valid large object exists and mi_lo_increfcount() to increment the reference count for the large object.
The Destroy() procedure calls mi_lo_validate() for each large object. For valid large objects, it calls mi_lo_decrefcount() to decrement the reference count for the large object.
The following example DataBlade modules use Assign() and Destroy() routines for smart large object processing:
The MultiRep DataBlade module uses the Assign() function to determine whether to put the multirepresentational opaque type in the database table or in a smart large object, depending on its size. The Destroy() procedure removes the reference counts to smart large objects, but has not effect on in-row data.
The Creating Distinct Types and Casts exercise in the tutorial uses the Assign() function for the FTemp (representing Fahrenheit degrees) and CTemp (representing Celsius degrees) distinct data types to prevent a user from entering a temperature value below absolute zero.
The Informix database server calls the LOhandles() function to retrieve the smart large object handles or list of smart large object handles used by an opaque type. The LOhandles() function receives a pointer to the opaque type and a pointer to an MI_FPARAM structure.
The LOhandles() function returns a pointer to an mi_bitvarying variable containing an MI_LO_HANDLES structure. BladeSmith defines MI_LO_HANDLES in the generated header file; it is not part of the DataBlade API. The structure holds a list of MI_LO_HANDLE structures. It has the following definition:
The LOhandles() function calls the mi_lo_validate() function for each large object in the opaque type structure, accumulating a count of valid large objects. If there are no valid large objects in the opaque type, the LOhandles() function returns 0 to its caller.
If the opaque type contains valid large objects, the LOhandles() function performs the following tasks:
The Informix database server calls DataBlade module comparison functions to compare two opaque type values. For example, database users can compare opaque values in SQL statements. If you want to support B-tree or R-tree indexes on an opaque type, you must provide an additional set of comparison functions.
The Compare() function compares two opaque types and returns an integer indicating the result of the comparison. The C name for each opaque data type is OpaqueCompare().
BladeSmith generates the complete C code for this function.
The Generated CodeThe generated code compares the members of an opaque type C structure to the members in the other opaque type, in the order defined in the structure. This algorithm might not be the appropriate way to compare your data; if it is not, you must customize the code as described in the next section.
The Compare() function returns:
For example, the Circle DataBlade module defines a Pnt data type as follows:
The Compare() function generated for the Pnt type first compares the two values of x. If the two values of x are not equal, Compare() stops and returns the result of the comparison. If the two values of x are equal, Compare() proceeds to compare the two values of y.
For data types such as mi_boolean, which cannot be compared for relative magnitude, the Compare() function returns +1 if the values differ. If all structure members are equal, it returns 0.
Customizing the CodeThe algorithm used to generate the Compare() function cannot evaluate the semantic content of an opaque type. Therefore, for many opaque types, replace the generated code with more appropriate code.
For example, the Circ.h file of the Circle DataBlade module defines the Circ data type as follows:
The Pnt member has two mi_double_precision members: x and y. The generated code for Compare() compares the three mi_double_precision values individually: first x, then y, and then radius. However, if the size of your circles is more important than their origins, you could remove the code that compares the x and y members to base the comparison on the length of the radius only.
If you want to use B-tree indexing, the Compare() function is the B-tree support function. Therefore, you should analyze how you want to index your opaque data types when modifying Compare().
Smart Large Object ConsiderationsThe generated Compare() function does not compare the values of the smart large objects; it compares the smart large object handles. If the smart large object handles are the same, then both handles refer to the same object. You can customize the code to compare the actual values of the smart large objects.
ExamplesThe following example DataBlade modules implement the Compare() function to compare opaque data types member by member:
The Shapes DataBlade module uses Compare() to perform a bitwise comparison on its Circle and Box data types.
The Informix database server calls the following comparison operators when constructing B-tree indexes for opaque data types:
The C names of each of these functions are prefixed by the name of the opaque data type for which they are defined.
Important: The Equal() function is required if you use Visual Basic to develop a DataBlade module.
BladeSmith generates the complete C code for these functions.
The Generated CodeFor these functions, BladeSmith generates code that calls the Compare() function described in Compare Function. For example, the Matrix2dEqual() function generated for the Matrix2d type calls the Matrix2dCompare() function, as follows:
Customizing the CodeYou should not modify these functions. You can, however, modify the Compare() function that these functions call.
Smart Large Object ConsiderationsBecause these functions call the Compare() function, they only evaluate the smart large object handles. You must customize the Compare() function to evaluate the actual contents of smart large objects.
ExamplesThe following example DataBlade modules contain some of the B-tree comparison functions:
Version 4.0 of BladeSmith does not generate code for R-tree comparison functions.
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.
If you choose to generate mathematic functions, BladeSmith generates the following mathematic functions that take two opaque data type arguments, return an opaque data type, and are bound to operators:
BladeSmith generates the following mathematic functions that take one opaque data type argument, return an opaque data type, and are bound to operators:
The C name of each of these functions is prefixed by the name of the opaque data type for which they are defined.
BladeSmith generates only template code for these mathematic functions.
These functions have an unused MI_FPARAM argument and one or two opaque data type arguments, and they return a pointer to the resulting opaque type structure.
In the generated code, the return value is set to 0. You must add code to perform the required operation.
To complete the code for these mathematic functions, you must:
The database server frees the allocated memory when it has finished processing the result.
See Extending Informix Dynamic Server 2000 for more information on these functions.
The Matrix DataBlade module contains some of the mathematic functions.
The Concat() function concatenates the values of its two opaque data type arguments and returns the result. It is bound to the || operator.
The C name of this function is prefaced by the name of the opaque data type: OpaqueConcat().
BladeSmith generates only a template for this function. You must add code to perform the required operation.
The database server uses the Hash() function when evaluating the Equal() function for two opaque data types that do not have identical bit representations.
The C name of this function is prefaced by the name of the opaque data type: OpaqueHash().
BladeSmith generates only a template for this function. You must add code to perform the necessary operation.