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 SQL and DataBlade API data types for opaque-type representations 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 SQL and DataBlade API data types for opaque-type representations 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 Opaque-type support functions that cast from SQL to opaque data types 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 SQL and DataBlade API data types for opaque-type representations 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 SQL and DataBlade API data types for opaque-type representations.
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 Opaque-type support functions that cast from opaque to SQL data types 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 SQL and DataBlade API data types for opaque-type representations, 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 Informix® User-Defined Routines and Data Types Developer's Guide.

The DataBlade® API data types in SQL and DataBlade API data types for opaque-type representations 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