Support functions as casts

The internal (binary) representation of an opaque type is a C structure that encapsulates the opaque-type information. The database server does not know about the structure of this internal representation. To be able to transfer opaque-type data to various locations, the database server assumes that cast functions exist between the internal representation of the opaque type (which the database server does not know) and some known representation of the opaque-type data.

Many of the opaque-type support functions serve as casts between some known representation of opaque-type data and the internal representation of the opaque type. Each known representation of an opaque type has an associated SQL data type, which you use when you register the support function. Each of these SQL data types has a corresponding DataBlade API data type, which you use when you declare the C function that implements the support function. The following table shows the opaque-type representations and the corresponding SQL and DataBlade API data types that implement them.

Table 1. SQL and DataBlade API data types for opaque-type representations
Opaque-type representation	SQL data type	DataBlade API data type	Opaque-type support functions
External (text) representation	LVARCHAR	mi_lvarchar	input, output
External binary representation on the client	SENDRECV	mi_sendrecv	receive, send
Text load file representation	IMPEXP	mi_impexp	import, export
Binary load file representation	IMPEXPBIN	mi_impexpbin	importbin, exportbin

When the database server receives some known representation of the opaque type, it receives it in one of the SQL data types that Table 1 lists. To locate the appropriate opaque-type support function, the database server looks in the syscasts system catalog table for a cast function that performs a cast from one of these SQL data types to the opaque type. The following table shows the opaque-type support functions cast from each of the SQL data types in Table 1 to the internal representation of the opaque type.

Table 2. Opaque-type support functions that cast from SQL to opaque data types
Cast from	Cast to	Opaque-type support functions
LVARCHAR	opaque data type	input
SENDRECV	opaque data type	receive
IMPEXP	opaque data type	import
IMPEXPBIN	opaque data type	importbin

For example, when the database server receives from a client application an LVARCHAR value for a column of type circle, it looks for a cast function that casts this value to the internal representation of the circle opaque type. This cast function is the input support function for circle, which takes as an argument an mi_lvarchar value and returns the circle_t structure (which contains the internal representation of circle):

circle_t *circle_input(external_rep)
   mi_lvarchar *external_rep;

The database server then saves the return value of the circle_input() support function in the column whose data type is circle. In this way, the database server does not need to know about the internal representation of circle. The circle_input() support function handles the details of filling the C structure.

Tip: All of the opaque-type support functions in Table 2 must be registered as implicit casts in the database. For more information, see Registering an opaque data type.

Similarly, when the database server sends some known representation of the opaque type, it sends it in one of the SQL data types that Table 1 lists. To locate the appropriate opaque-type support function, the database server looks for a cast function that performs a cast from the opaque type to one of these SQL data types. The following table shows the opaque-type support functions that cast from the internal representation of the opaque type to each of the SQL data types in Table 1.

Table 3. Opaque-type support functions that cast from opaque to SQL data types
Cast from	Cast to	Opaque-type support function
opaque data type	LVARCHAR	output
opaque data type	SENDRECV	send
opaque data type	IMPEXP	export
opaque data type	IMPEXPBIN	exportbin

All the opaque-type support functions in Table 3 must be registered as explicit casts in the database. For more information, see Registering an opaque data type.

Important: For the database server to locate one of the opaque-type support functions in Table 1, you must register these support functions as cast functions with the CREATE CAST statement. Otherwise, the database server will not find the function to perform the cast when it checks the syscasts system catalog table. For more information, see the description of how to create casts for support functions in the HCL Informix® User-Defined Routines and Data Types Developer's Guide.

The DataBlade API data types in Table 1 are all implemented as varying-length structures. Therefore, all these data types have the same internal format. Any DataBlade API function that is declared to handle the mi_lvarchar data type can also handle these other varying-length data types. However, you might need to cast between these types to avoid compilation warnings. If you are using a varying-length data type other than mi_lvarchar, you can cast between the varying-length type you are using and mi_lvarchar.

For example, the mi_string_to_lvarchar() function converts a null-terminated string to an mi_lvarchar varying-length data type. You can use casting to have this function convert a null-terminated string to an mi_impexp varying-length data type, as follows:

mi_impexp *new_impexp;
...
new_impexp = (mi_impexp *)mi_string_to_lvarchar(strng);

This casting is not strictly required, but many compilers recommend it and it does improve clarity of purpose.

Any size of data can fit into a varying-length structure. When a varying-length data type holds a value for an opaque-type column, this two-kilobyte size restriction for LVARCHAR columns does not apply. You can write the appropriate support functions of the opaque data type to handle more than two kilobytes. For more information about how to manage these varying-length structures, see Varying-length data type structures.

Subsequent sections describe each of the opaque-type support functions, grouped by the opaque-type representation that they handle, as the following table shows.

Opaque-type support functions	Description	More information
input, output	Convert the opaque-type data between its external and internal representation. Serve as casts between the LVARCHAR and opaque data types.	The input and output support functions
send, receive	Convert the opaque-type data between its internal representations on the client and server computers. Serve as casts between the SENDRECV and opaque data types.	The send and receive support functions
import, export	Convert the opaque-type data between its external unload representation and its server internal representation. Serve as casts between the IMPEXP and opaque data types.	External unload representation
importbin, exportbin	Convert the opaque-type data between its internal unload representation and its server internal representation. Serve as casts between the IMPEXPBIN and opaque data types.	Internal unload representation