Support Functions for Opaque Data Types
The support functions for an opaque data type are a set of well-defined, type-specific functions that the database server automatically invokes. Typically, these functions are not explicitly invoked in an SQL statement. The following table summarizes the support functions of an opaque data type.
Handling the External Representation
Every opaque type has its internal and external representation. The internal representation is the internal structure that you define for the opaque type. (For more information, see "The Internal Structure".) The external representation is a character string that is a printable version of the opaque value.
When you define an opaque type, you must supply the following support functions that convert between the internal and external representations of the opaque type:
These support functions do not have to be named input and output, but they do have to perform the specified conversions. They should be reciprocal functions; that is, the input function should produce a value that the output function accepts as an argument and vice versa.
For your opaque data type to accept an external representation on non-default locales, you must use the Informix GLS API in the input and output functions to access Informix locales from within these functions. For more information, see "Handling Locale-Sensitive Data". 
The LVARCHAR Data Type
SQL statements use the LVARCHAR data type to hold the external representation of an opaque data type. This data type supports varying-length strings whose length is greater than 256 bytes. The input and output support functions serve as casting functions between the LVARCHAR and opaque data type.
INFORMIX-ESQL/C applications use lvarchar or other character-based host variables in SQL statements to transfer the external representation of an opaque type. The database server implicitly invokes the input and output support functions when it receives an SQL statement that contains an lvarchar host variable.
For more information on how to use SQL statements to register support functions, see page 5-15.
Input Support Function
Is an input function required for all opaque types? If so, does the server verify that it exists?
The database server calls the input function when it receives the external representation of an opaque type from a client application. For example, when a client application issues an INSERT or UPDATE statement, it can send the character representation of an opaque type to the database server to be stored in an opaque-type column. The database server calls the input function to convert this external representation to an internal representation that it stores on disk.
Figure 6-1 shows when Universal Server executes the input support function.
If the opaque data type is pass-by-reference, the input support function should perform the following tasks:
It can use the mi_alloc() DataBlade API function to allocate the space for the internal structure.
It must obtain the individual members from the input string and store them into the appropriate fields of the internal structure
If the opaque data type is pass-by-value, the input support function should perform these same basic tasks but return the actual value in the internal structure instead of a pointer to this structure. You can use pass-by-value only for opaque types that are less than 4 bytes in length.
The input function takes an mi_lvarchar value as an argument and returns the internal structure for the opaque type. The following function signature is an input support function for an opaque data type whose internal structure is ll_longlong_t:
The ll_longlong_input() function is a casting function from the LVARCHAR data type to the ll_longlong_t internal structure. It must be registered as an implicit casting function with the CREATE IMPLICIT CAST statement. For more information on casting functions, see "Creating the Casts".
Output Support Function
Is an output function required for all opaque types? If so, does the server verify that it exists?
The database server calls the output function when it sends the external representation of an opaque type to a client application. For example, when a client application issues a SELECT or FETCH statement, it can save the data of an opaque type that it receives from the database server in a character host variable. The database server calls the output function to convert the internal representation that is stored on disk to the external representation that the character host variable requires.
Figure 6-2 shows when Universal Server executes the output support function.
If the opaque data type is pass-by-reference, the output support function should perform the following tasks:
It can use the mi_alloc() DataBlade API function to allocate the space for the character string. For more information on memory management and the mi_alloc() function, refer to the DataBlade API Programmer's Manual.
It must build the external representation with the values from the appropriate fields of the internal structure.
If the opaque data type is pass-by-value, the output support function should perform the same basic tasks but accept the actual value in the internal structure. You can use pass-by-value only for opaque types that are less than 4 bytes in length.
The output function takes the internal structure for the opaque type as an argument and returns an mi_lvarchar value. The following function signature is for an output support function of an opaque data type whose internal structure is ll_longlong_t:
The ll_longlong_output() function is a casting function from the ll_longlong_t internal structure to the LVARCHAR data type. It must be registered as an explicit casting function with the CREATE EXPLICIT CAST statement. For more information on casting functions, see "Creating the Casts".
Handling Platform-Specific Internal Representations
If a client application that uses an opaque data type executes on a different computer than the database server, it might have a different way of representing the internal structure of the opaque type. For example, the client computer might use a different byte ordering than the server computer. For cases where the internal representation of an opaque type might differ on the client and server computers, you must supply the receive and send support functions that convert between the internal representation on the client computer and that on the server computer.
Italicized line is from Example Code book and had "Illustra", not Informix. Is it correct?
These functions must handle conversions for all platform variations that the client applications might encounter. When the client application establishes a connection with Universal Server, it sends a description of the internal representations that the client computer uses. One representation is the same for all client applications that run on the same architecture. Universal Server uses this description to determine which client representation to use in its receive and send support functions.
The Informix DataBlade API provides functions that support conversion between different internal representations of opaque types. Your send and receive functions can call these DataBlade API routines for each member of the internal structure to convert them to the appropriate representation for the destination platform.
For your opaque data type to accept an internal representation on non-default locales, you must use the Informix GLS API in the receive and send functions to access Informix locales from within these functions. For more information, see "Handling Locale-Sensitive Data".
The receive and send functions support the binary transfer of opaque types. They convert between the internal representation of an opaque type on a client computer and the internal representation on the server computer.
These support functions do not have to be named receive and send, but they do have to perform the specified conversions. They should be reciprocal functions; that is, the receive function should produce a value that the send function accepts as an argument and vice versa.
The SENDRECV Data Type
SQL statements support an internal data type called SENDRECV to hold the internal representation of an opaque data type when it is transferred between the client computer and the server computer. The SENDRECV data type allows for any possible change in the size of the data when it is converted between the two representations. The receive and send support functions serve as casting functions between the SENDRECV and opaque data type.
For more information on how to use SQL statements to register support functions, see page 5-15.
The SENDRECV data type is not surfaced in INFORMIX-ESQL/C applications. Instead, these applications use fixed binary and var binary host variables in SQL statements to transfer the internal representation of an opaque type on the client computer. The database server implicitly invokes the receive and send support functions when it receives an SQL statement that contains a fixed binary or var binary host variable.
Receive Support Function
The database server calls the receive function when it receives the internal representation of an opaque type from a client application. For example, when a client application issues an INSERT or UPDATE statement, it can send the internal representation of an opaque type to the database server to be stored in a column.
INFORMIX-ESQL/C applications use the fixed binary and var binary host variables to send the internal representation of an opaque data type.
Figure 6-3 shows when Universal Server executes the receive support function.
The database server calls the receive function to convert the internal representation of the client computer to the internal representation of the server computer, where the opaque type is stored on disk.
The receive function takes as an argument an mi_sendrecv structure (that holds the internal structure on the client computer) and returns the internal structure for the opaque type (the internal representation on the server computer). The following function signature is for a receive support function of an opaque data type whose internal structure is ll_longlong_t:
The ll_longlong_receive() function is a casting function from the SENDRECV data type to the ll_longlong_t internal structure. It must be registered as an implicit casting function with the CREATE IMPLICIT CAST statement. For more information on casting functions, see "Creating the Casts".
Send Support Function
The database server calls the send function when it sends the internal representation of an opaque type to a client application. For example, when a client application issues a SELECT or FETCH statement, it can save the data of an opaque type that it receives from the database server in a host variable that conforms to the internal representation of the opaque type.
INFORMIX-ESQL/C applications use the fixed binary and var binary host variables to receive the internal representation of an opaque data type.
Figure 6-4 shows when Universal Server executes the send support function.
The database server calls the send function to convert the internal representation that is stored on disk to the internal representation that the client computer uses.
The send function takes as an argument the internal structure for the opaque type on the server computer and returns an mi_sendrecv structure that holds the internal structure on the client computer. The following function signature is for a send support function of an opaque data type whose internal structure is ll_longlong_t:
The ll_longlong_send() function is a casting function from the ll_longlong_t internal structure to the SENDRECV data type. It must be registered as an explicit casting function with the CREATE EXPLICIT CAST statement. For more information on casting functions, see "Creating the Casts".
Performing Bulk Copies
Universal Server can copy data in and out of a database with a bulk copy operation. In a bulk copy, the database server sends large numbers of column values in a copy file, rather than copying each column value individually. For large amounts of data, bulk copying is far more efficient than moving values individually.
The following Informix utilities can perform bulk copies:
Universal Server can perform bulk copies on binary (internal) or character (external) representations of opaque-type data.
Import and Export Support Functions
The import and export support functions perform any tasks needed to process the external representation of an opaque type for a bulk copy. When Universal Server copies data into or out of a database in external format, it calls the following support functions for every value copied to or from the copy file:
These support functions do not have to be named import and export, but they do have to perform the specified conversions. They should be reciprocal functions; that is, the import function should produce a value that the export function accepts as an argument and vice versa.
The import and export functions can take special actions on the values before they are copied. Typically, only opaque data types that contain smart large objects have import and export functions defined for them. For example, the export function for such a data type would create a file on the client computer, write the smart-large-object data from the database into this file, and send the name of the client file as the data to store in the copy file. Similarly, the import function for such a data type would take the client file name from the copy file, open the client file, and load the large-object data from the copy file into the database. The advantage of this design is that the smart-large-object data does not appear in the copy file; therefore, the copy file grows more slowly and is easier for people to read.
For small opaque data types, you do not usually need to defined the import and export support functions. If they are not defined, the database server uses the input and output functions, respectively, when it performs bulk copies.
The IMPEXP Data Type
SQL statements support an internal data type called IMPEXP to hold the external representation of an opaque data type for a bulk copy. The IMPEXP data type allows for any possible change in the size of the data when it is converted between the two representations. The import and export support functions serve as cast functions between the IMPEXP and opaque data type.
For more information on how to use SQL statements to register support functions, see page 5-15.
Import
The import function takes as an argument an mi_impexp structure (that holds the bulk-copy format of the external representation of the user-defined type) and returns the internal structure for the user-defined type. The following function signature is for an import support function of an opaque data type whose internal structure is ll_longlong_t:
The ll_longlong_import() function is a casting function from the IMPEXP data type to the ll_longlong_t data structure. It must be registered as an implicit casting function with the CREATE IMPLICIT CAST statement. For more information on casting functions, see "Creating the Casts".
Any files that the import function reads must reside on the server computer. If you do not provide an import support function, Universal Server uses the input support function to import textual data.
Export
The export function takes as an argument the internal structure for the opaque type and returns an mi_impexp structure that holds the bulk-copy format of the external representation of the opaque type. The following function signature is for an export support function of an opaque data type whose internal structure is ll_longlong_t:
The ll_longlong_export() function is a casting function from the ll_longlong_t internal structure to the IMPEXP data type. It must be registered as an explicit casting function with the CREATE EXPLICIT CAST statement. For more information on casting functions, see "Creating the Casts".
If you do not provide an export support function, Universal Server uses the output support function to export textual data.
Importbinary and Exportbinary Support Functions
The importbinary and exportbinary support functions perform any tasks needed to process the internal (binary) representation of an opaque type for a bulk copy, as follows:
These support functions do not have to be named importbinary and exportbinary, but they do have to perform the specified conversions. They should be reciprocal functions; that is, the importbinary function should produce a value that the exportbinary function accepts as an argument and vice versa. The Informix DataBlade API provides functions that support conversion between different internal representations of opaque types.
For opaque data types that have identical external and internal representations, the import and importbinary support functions can be the same function. Similarly, the export and exportbinary support functions can be the same function.
The IMPEXPBIN Data Type
SQL statements support an internal data type called IMPEXPBIN to hold the internal representation of an opaque data type for a bulk copy. The IMPEXPBIN data type allows for any possible change in the size of the data when it is converted between the two representations. The importbinary and exportbinary support functions serve as cast functions between the IMPEXPBIN and opaque data type.
For more information on how to use SQL statements to register support functions, see page 5-15.
Importbinary
The importbinary function takes as an argument an mi_impexpbin structure (that holds the bulk-copy format of the internal format of the opaque type) and returns the internal structure for the opaque type. The following function signature is for an importbinary support function of an opaque data type whose internal structure is ll_longlong_t:
The ll_longlong_importbin() function is a casting function from the IMPEXPBIN data type to the ll_longlong_t internal structure. It must be registered as an implicit casting function with the CREATE IMPLICIT CAST statement. For more information on casting functions, see "Creating the Casts".
Any files that the import function reads must reside on the server computer. If you do not provide an importbinary support function, Universal Server imports the binary data in the server internal representation of the opaque data type.
Exportbinary
The exportbinary function takes as an argument the internal structure for the opaque type and returns an mi_impexpbin structure that holds the bulk-copy format of the internal representation of the opaque type. The following function signature is for an exportbinary support function of an opaque data type whose internal structure is ll_longlong_t:
The ll_longlong_exportbin() function is a casting function from the ll_longlong_t internal structure to the IMPEXPBIN data type. It must be registered as an explicit casting function with the CREATE EXPLICIT CAST statement. For more information on casting functions, see "Creating the Casts".
If you do not provide an exportbinary support function, Universal Server exports the binary data in the internal representation of the opaque data type.
Inserting and Deleting Data
Some opaque data types might require special processing before they are saved to or removed from disk. For Universal Server to perform this special processing on an opaque type, you can create the following support functions:
A common use of the assign() and destroy() support functions is for an opaque data type that contains spatial or multirepresentational data. Such a data type might provide a choice of how to store the data: inside the internal structure or, for very large objects, in a smart large object. If the data is stored in a smart large object, the internal structure of the opaque data type contains the LO-pointer structure to identify the location of the data; it does not contain the data itself. The assign() support function can make the decision of how to store the data, and the destroy() support function can decide how remove the data, regardless of where it is stored. For an example of such an opaque type, see "A Varying-Length Opaque Type: image".
These support functions must be named assign and destroy, but the names are case insensitive. They must perform the tasks that should occur before the opaque data type is stored to or removed from disk. The assign() and destroy() functions are required for opaque types that have smart large objects and multirepresentational data.
The assign() Support Function
Universal Server calls the assign() support function just before it stores the internal representation of an opaque type on disk. For example, when a client application issues an INSERT, UPDATE or LOAD statement, the database server calls the assign() function before it saves the internal representation of an opaque type in a column.
Figure 6-5 shows when Universal Server executes the assign() function.
When you store a value of an opaque data type, the assign() function takes as an argument the internal structure for the opaque data type and returns the data that is actually stored in the table.
The destroy() Support Function
Universal Server calls the destroy() support function just before it removes the internal representation of an opaque type from disk. For example, when a client application issues a DELETE or DROP TABLE statement, the database server calls the destroy() function before it deletes an opaque-type value from a column.
Figure 6-6 shows when Universal Server executes the destroy() function.
Is there a particular return value?
The destroy() function takes as an argument the internal structure for the opaque data type.
Handling Smart Large Objects
If an opaque data type contains an embedded smart large object, you must define an lohandles() support function for the opaque type. The lohandles() support function takes an instance of the opaque type and returns a list of the -pointer structures for the smart large objects that are embedded in the data type.
Is there a function signature for an lohandles support function?
Universal Server uses the lohandles() support function whenever it must search opaque-type values for references to smart large objects. Examples of this search include the following:
If you define an opaque type that references one or more smart large objects, you must also consider defining the following support functions:
For more information on assign() and destroy() support functions, see "Inserting and Deleting Data". For information on the import, export, importbinary, and exportbinary support functions, see "Performing Bulk Copies".
Comparing Data
The compare() function is an SQL-invoked function that sorts the target data type. Universal Server uses the compare() function to execute the following clauses and keywords of the SELECT statement:
The database server also uses the compare() function to evaluate the BETWEEN operator in the condition of an SQL statement. For more information on conditional clauses, see the Condition segment in the Informix Guide to SQL: Syntax.
For Universal Server to be able to sort an opaque type, you must define a compare() function that handles the opaque type. This compare() function must follow these rules:
1. The name of the function must be compare(). However, the name is not case sensitive; the compare() function is the same as the Compare() function.
2. The function must accept two arguments, each of the data type to be compared.
3. The function must return an integer value to indicate the result of the comparison, as follows:
If your opaque type is not bit-hashable, the compare() function should generate an error so that the database server does not use the default compare() function.
The compare() function is the support function for the built-in secondary access method, B-tree. For more information on the built-in secondary access method, see "The Generic B-Tree Index". For more information on how to customize a secondary access method for an opaque data type, see "Using an Operator Class".
|
