Writing Opaque-Type Support Functions

Home | Previous Page | Next Page Creating User-Defined Routines > Extending Data Types > Creating an Opaque Data Type >

Writing Opaque-Type Support Functions

The database server does not know the internal representation of an opaque type. To handle the internal representation, you write opaque-type support functions. These support functions tell the database server how to interact with the opaque type. The following table summarizes the opaque-type support functions.

Category of Support Function	Opaque-Type Support Functions	More Information
Support functions as casts	input, output receive, send import, export importbin, exportbin	Support Functions as Casts
Stream support functions	streamwrite( ), streamread( )	Stream Support Functions
Disk-storage support functions	assign( ), destroy( )	Disk-Storage Support Functions
Other support functions	compare( ), deepcopy( ), update( )	The IBM Informix: User-Defined Routines and Data Types Developer's Guide

Tip:

The IBM Informix BladeSmith development tool, which is part of the DataBlade Developer's Kit, automatically generates some of the C source code for the support routines of an opaque type. For more information, see the IBM Informix: DataBlade Developer's Kit User's Guide.

The following sections provide information specific to the development of the opaque-type support functions as C UDRs. For a general discussion of opaque-type support functions, see the IBM Informix: User-Defined Routines and Data Types Developer's Guide.

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. Table 111 shows the opaque-type representations and the corresponding SQL and DataBlade API data types that implement them.

Table 111. 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 111 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. Table 112 shows the opaque-type support functions cast from each of the SQL data types in Table 111 to the internal representation of the opaque type.

Table 112. Opaque-Type Support Functions That Cast from SQL to Opaque Data Types
Cast		Opaque-Type Support Function
From	To	Opaque-Type Support Function
LVARCHAR	opaque data type	input
SENDRECV	opaque data type	receive
IMPEXP	opaque data type	import
IMPEXPBIN	opaque data type	importbinary

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 112 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 111 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. Table 113 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 111.

Table 113. Opaque-Type Support Functions That Cast from Opaque to SQL Data Types
Cast		Opaque-Type Support Function
From	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 113 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 111, 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 IBM Informix: User-Defined Routines and Data Types Developer's Guide.

The DataBlade API data types in Table 111 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 on 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.	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.	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

Input and Output Support Functions

To handle opaque-type data in its external text representation, the database server calls the input and output support functions for the opaque type. The external representation is the text version of the opaque-type data. (For more information, see Determining External Representation.) The external representation is often what end users enter for the opaque-type value. When a client application sends or receives opaque-type data in its external representation, the database server must find a support function to handle the conversion of this data between its server internal representation (in the database) and the external representation. The input and output support functions are the cast functions for an opaque type between its external (text) representation and its internal (binary) representation (on the server computer). The server internal representation is the C structure that holds the opaque-type data in the database. For more information, see Determining Internal Representation.

The database server stores the external representation of an opaque type in an mi_lvarchar structure. The mi_lvarchar structure is a varying-length structure that encapsulates the external representation of the opaque type. The mi_lvarchar structure is always passed by reference. Therefore, the input and output support routines cast the data as follows.

Opaque-Type Support Function	Cast From	Cast To
Input	mi_lvarchar *	Server internal representation of the opaque data type
Output	Server internal representation of the opaque data type	mi_lvarchar *

There is no limitation on the size of an mi_lvarchar structure. The DataBlade API can transport mi_lvarchar data to and from the database server. However, to conform to the storage limit of a database table (32 kilobytes for a table, two kilobytes for an LVARCHAR column), the input support function might need to handle extra data and the output support function might need to generate the extra data.

The two-kilobyte restriction does not apply to an mi_lvarchar structure that holds the external representation of an opaque-type column. If the input and output support functions of the opaque data type can handle more than two kilobytes, the mi_lvarchar structure can hold more than two kilobytes. For more information, see The mi_lvarchar Data Type.

Global Language Support

For your opaque data type to accept an external representation in non-default locales, you must internationalize the input and output support functions. For more information, see Internationalization of DataBlade API Modules (GLS).

End of Global Language Support

Input Support Function

When an application performs some operation that passes the external representation of an opaque type to the database server (such as INSERT or UPDATE with an opaque-type value as a literal string), the database server calls the input support function. The input support function accepts the external representation of the opaque type, which is encapsulated in an mi_lvarchar structure, and returns the appropriate server internal representation for that type, as the following signature shows:

srvr_internal_rep input(external_rep)
   mi_lvarchar *external_rep;

external_rep: is a pointer to an mi_lvarchar structure that holds the external representation of the opaque type.
An mi_lvarchar is always passed by reference. Therefore, the external_rep argument must always be a pointer to the mi_lvarchar data type. For information on how to obtain information from this varying-length structure, see Information About Varying-Length Data.
input: is the name of the C-language function that implements the input support function for the opaque type. It is recommended that you include the name of the opaque type in its input function.
srvr_internal_rep: is the appropriate format for the server internal representation of the opaque data type. The passing mechanism of this return value depends on the kind of opaque type, as Figures Figure 117 through Figure 119 show. Most opaque types are passed by reference.

Figure 117 declares a sample input support function for a fixed-length opaque type named circle (which Figure 113 declares).

Figure 117. Input Support Function for circle Opaque Type

/* Input support function: circle */
circle_t *circle_input(extrnl_rep)
   mi_lvarchar *extrnl_rep;

The circle_input( ) function is a cast function from the mi_lvarchar data type (which contains the external representation for the circle opaque type) to the circle_t internal representation (on the server computer). The database server executes circle_input( ) when it needs a cast function to convert from the SQL data type LVARCHAR to the server internal representation of the circle opaque type. For more information, see Support Functions as Casts.

The circle_input( ) function returns a pointer to the circle_t data type. Because circle cannot fit into an MI_DATUM structure, it must be passed by reference. If your fixed-length opaque type can fit into an MI_DATUM structure, the input support function can return the internal representation by value. Figure 118 declares a sample input function for a fixed-length opaque type named two_bytes (which Figure 116 declares).

Figure 118. Input Support Function for two_bytes Opaque Type

/* Input support function: two_bytes */
two_bytes_t two_bytes_input(extrnl_rep)
   mi_lvarchar *extrnl_rep;

The two_bytes opaque type must be registered as PASSEDBYVALUE to tell the database server that it can be passed by value.

Figure 119 declares a sample input support function for a varying-length opaque type named image (which Figure 114 declares).

Figure 119. Input Support Function for image Opaque Type

/* Input support function: image */
mi_lvarchar *image_input(extrnl_rep)
   mi_lvarchar *extrnl_rep;

The image opaque type stores its data inside an mi_lvarchar structure, which must be passed by reference. The image_input( ) function is a cast function from the external representation of image to the server internal representation of image.

The input support function performs the following tasks:

Accepts as an argument a pointer to the external representation of the opaque type
The external representation is in the data portion of an mi_lvarchar structure, which is passed by reference.
Allocates enough space to hold the server internal representation of the opaque type
The input function can use the mi_alloc( ) DataBlade API function to allocate the space for the internal representation, or the mi_new_var( ) function if the opaque type is varying length. For more information on memory management, see Managing User Memory.
Parses the input string of the external representation
The input function must obtain the individual members from the input string and store them into the appropriate fields of the server internal representation. The DataBlade API provides functions to convert various DataBlade API data types from their external to internal representations. For example, to convert a date string in an external representation to its internal representation (the mi_date value in the image_t structure), the image_input( ) function can call the mi_string_to_date( ) function. For a list of these DataBlade API functions, see Conversion of Opaque-Type Data Between Text and Binary Representations.
Returns the appropriate server internal representation for the opaque type
If the opaque data type is passed by reference, the input function returns a pointer to the server internal representation. If the opaque data type is passed by value, the input function returns the actual value of the server internal representation instead of a pointer to this representation. For more information, see Determining the Passing Mechanism for an Opaque Type.

Output Support Function

When an application performs some operation that requests the external representation of an opaque type (such as a SELECT operation that requests data in its text representation), the database server calls the output support function. The output support function accepts the appropriate server internal representation of the opaque type and returns the external representation of that type, which is encapsulated in an mi_lvarchar structure, as the following signature shows:

mi_lvarchar *output(srvr_internal_rep)

output: is the name of the C-language function that implements the output support function for the opaque type. It is recommended that you include the name of the opaque type in the name of its output function. For example, if the UDT name is image, the name of the output function would be image_output( ).
srvr_internal_rep: is the appropriate format for the server internal representation of the opaque data type. The passing mechanism of this argument value depends on the kind of opaque type, as Figures Figure 120 through Figure 122 show. Most opaque types are passed by reference.

An mi_lvarchar value is always passed by reference. Therefore, the return value of the output support function must always be a pointer to the mi_lvarchar data type. For information on how to obtain information from this varying-length structure, see Information About Varying-Length Data.

Figure 120 declares a sample output support function for a fixed-length opaque type named circle (which Figure 113 declares).

Figure 120. Output Support Function for circle Opaque Type

/* Output support function: circle */
mi_lvarchar *circle_output(srvr_intrnl_rep)
   circle_t *srvr_intrnl_rep;

The circle_output( ) function is a cast function from the circle_t internal representation (on the server computer) to the mi_lvarchar data type (which contains the external representation for circle). The database server executes circle_output( ) when it needs a cast function to convert from the server internal representation of the circle opaque type to the SQL data type LVARCHAR. For more information, see Support Functions as Casts.

The circle_output( ) function accepts as an argument a pointer to the circle_t data type. Because circle cannot fit into an MI_DATUM structure, it must be passed by reference. If your fixed-length opaque type can fit into an MI_DATUM structure, the output support function can pass the server internal representation by value. Figure 121 declares a sample output function for a fixed-length opaque type named two_bytes (which Figure 116 declares).

Figure 121. Output Support Function for two_bytes Opaque Type

/* Output support function: two_bytes */
mi_lvarchar *two_bytes_output(srvr_intrnl_rep)
   two_bytes_t srvr_intrnl_rep;

The two_bytes opaque type must be registered as PASSEDBYVALUE to tell the database server that it can be passed by value.

Figure 122 declares a sample output support function for a varying-length opaque type named image (which Figure 114 declares).

Figure 122. Output Support Function for image Opaque Type

/* Output support function: image */
mi_lvarchar *image_output(srvr_intrnl_rep)
   mi_lvarchar *srvr_intrnl_rep;

The image opaque type stores its data inside an mi_lvarchar structure, which must be passed by reference. The image_output( ) function is a cast function from the internal representation of image to the external representation of image.

The output support function performs the following tasks:

Accepts as an argument a pointer to the appropriate server internal representation of the opaque type
If the opaque data type is passed by reference, the output support function accepts a pointer to the server internal representation. If the opaque data type is passed by value, the output function returns the actual value of the internal representation instead of a pointer to this representation. For more information, see Determining the Passing Mechanism for an Opaque Type.
Allocates enough space to hold the external representation of the opaque type
The output function can use the mi_alloc( ) DataBlade API function to allocate the space for the character string. For more information on memory management, see Managing User Memory.
Creates the output string of the external representation from the individual members of the server internal representation
The DataBlade API provides functions to convert various DataBlade API data types from their internal to external representations. For example, to convert the mi_date value in the image_t structure to its appropriate external representation, the image_output( ) function can call the mi_date_to_string( ) function. For a list of these DataBlade API functions, see Conversion of Opaque-Type Data Between Text and Binary Representations.
Copies the external representation into an mi_lvarchar structure
You must use the mi_new_var( ) function to create a new mi_lvarchar structure. You can use mi_set_vardata( ) to copy data into the mi_lvarchar structure or mi_set_varptr( ) to store a pointer to storage allocated by mi_alloc( ).
Returns a pointer to the external representation for the opaque type
This character string must reside in the data portion of an mi_lvarchar structure. Therefore, the output support function returns a pointer to this mi_lvarchar structure.

Conversion of Opaque-Type Data Between Text and Binary Representations

The input and output support functions can call the following DataBlade API functions to convert the atomic C data types within the server internal representation of the opaque data type between their external (text) and internal (binary) representations.

Type of Data	DataBlade API Function
Type of Data	In Input Support Function	In Output Support Function
Date and Date/time data
DATE data	mi_string_to_date( )	mi_date_to_string( )
DATETIME data	mi_string_to_datetime( )	mi_datetime_to_string( )
INTERVAL data	mi_string_to_interval( )	mi_interval_to_string( )
Integer data
SMALLINT data (two-byte integers)	rstoi( ), atoi( )
INTEGER data (four-byte integers)	rstol( ), atol( )
INT8 data (eight-byte integers)	ifx_int8cvasc( )	ifx_int8toasc( )
Fixed-point and Floating-point data
DECIMAL data (fixed-point and floating-point)	mi_string_to_decimal( )	mi_decimal_to_string( )
MONEY data	mi_string_to_money( )	mi_money_to_string( )
SMALLFLOAT data	atof( )
FLOAT data	rstod( )
Other data
Character data, Varying-length data	mi_string_to_lvarchar( )	mi_lvarchar_to_string( )
LO handle (smart large objects)	mi_lo_from_string( )	mi_lo_to_string( )

Global Language Support

Most DataBlade API functions that convert between text and binary representations recognize the end-user formats for data in a locale-specific format. For more information about how to internationalize a C UDR, see Internationalization of DataBlade API Modules (GLS).

End of Global Language Support

Send and Receive Support Functions

To handle opaque-type data in its external binary representation, the database server calls the send and receive support functions for the opaque type. When a client application sends or receives opaque-type data in its internal representation, the database server must find a support function to handle the possibility that the client computer uses a different byte ordering than the server computer. The send and receive support functions are the cast functions for an opaque type between its internal representation on a client computer and its internal representation on the server computer.

The database server stores the client internal representation of an opaque type in an mi_sendrecv structure. The mi_sendrecv structure is a varying-length structure that encapsulates the client internal representation. Its ability to store varying-length data enables it to handle any possible changes in the size of the opaque-type data when it is converted between these two internal representations. For example, the client and server computers might have different packing rules for structures. Because the mi_sendrecv data type is a varying-length structure (like mi_lvarchar), it is always passed by reference. Therefore, the send and receive support routines cast the data as follows.

Opaque-Type Support Function	Cast From	Cast To
Send	Server internal representation of the opaque data type	mi_sendrecv *
Receive	mi_sendrecv *	Server internal representation of the opaque data type

The database server receives a description of the client computer when the client application establishes a connection. The DataBlade API provides several functions that access this information for use in send and receive functions. For more information, see Conversion of Opaque-Type Data with Computer-Specific Data Types.

Receive Support Function

When an application executes a query, such as INSERT or UPDATE, and specifies binary transfer of data, the database server calls the receive support function. The way to specify binary transfer (for fetch or send) depends on the client API:

ODBC uses an SQLBindCol( ) call.
The DataBlade API mi_exec_prepared_statement( ) call takes a PARAMS_ARE_BINARY flag.
ESQL/C uses the host-variable data type to specify if the transfer is binary or text.

The receive support function accepts the client internal representation of the opaque type, which is encapsulated in an mi_sendrecv structure, and returns the appropriate server internal representation of that type, as the following signature shows:

srvr_internal_rep receive(client_internal_rep)
   mi_sendrecv *client_internal_rep;

client_internal_rep: is a pointer to an mi_sendrecv structure that holds the client internal representation of the opaque type.
An mi_sendrecv is always passed by reference. Therefore, the client_internal_rep argument must always be a pointer to the mi_sendrecv data type. For more information, see Information About Varying-Length Data.
receive: is the name of the C-language function that implements the receive support function for the opaque type. It is recommended that you include the name of the opaque type in its receive function.
srvr_internal_rep: is the appropriate format for the server internal representation of the opaque data type. The passing mechanism of this return value depends on the kind of opaque type, as Figures Figure 123 through Figure 125 show. Most opaque types are passed by reference.

Figure 123 declares a sample receive support function for a fixed-length opaque type named circle (which Figure 113 declares).

Figure 123. Receive Support Function for circle Opaque Type

/* Receive support function: circle */
circle_t *circle_recv(client_intrnl_rep)
   mi_sendrecv *client_intrnl_rep;

The circle_recv( ) function is a cast function from the mi_sendrecv data type (which contains the client internal representation for the circle opaque type) to the circle_t internal representation (on the server computer). The database server executes circle_recv( ) when it needs a cast function to convert from the SQL data type SENDRECV to the server internal representation of the circle opaque type. For more information, see Support Functions as Casts.

The circle_recv( ) function returns a pointer to the circle_t data type. Because circle cannot fit into an MI_DATUM structure, it must be passed by reference. If your fixed-length opaque type can fit into an MI_DATUM structure, the receive support function can return the server internal representation by value. Figure 124 declares a sample receive function for a fixed-length opaque type named two_bytes (which Figure 116 declares).

Figure 124. Receive Support Function for two_bytes Opaque Type

/* Receive support function: two_bytes */
two_bytes_t two_bytes_recv(client_intrnl_rep)
   mi_sendrecv *client_intrnl_rep;

The two_bytes opaque type must be registered as PASSEDBYVALUE to tell the database server that it can be passed by value.

Figure 125 declares a sample receive support function for a varying-length opaque type named image (which Figure 114 declares).

Figure 125. Receive Support Function for image Opaque Type

/* Receive support function: image */
mi_lvarchar *image_recv(client_intrnl_rep)
   mi_sendrecv *client_intrnl_rep;

The image opaque type stores its data inside an mi_lvarchar structure, which must be passed by reference. The image_recv( ) function is a cast function from the mi_sendrecv data type (which contains the client internal representation of image) to the mi_lvarchar data type (which contains the server internal representation of image).

The receive support function performs the following tasks:

Accepts as an argument a pointer to the client internal representation of the opaque type
The client internal representation is in the data portion of an mi_sendrecv structure, which is passed by reference.
Allocates enough space to hold the server internal representation of the opaque type
The receive function can use the mi_alloc( ) DataBlade API function to allocate the space for the internal representation, or the mi_new_var( ) function if the opaque type is varying length. For more information on memory management, see Managing User Memory.
Creates the server internal representation from the individual members of the client internal representation
The DataBlade API provides functions to convert simple C data types from their client to server binary representations. For example, to convert the double-precision values in the circle_t structure to their binary representation on the server computer, the circle_recv( ) function can call the mi_get_double_precision( ) function. For a list of these DataBlade API functions, see Conversion of Opaque-Type Data with Computer-Specific Data Types.
Returns the appropriate server internal representation for the opaque type
If the opaque data type is passed by reference, the receive function returns a pointer to the server internal representation. If the opaque data type is passed by value, the receive function returns the actual value of the internal representation instead of a pointer to this representation. For more information, see Determining the Passing Mechanism for an Opaque Type.

Send Support Function

When an application performs some operation that requests the binary representation of an opaque type (such as a SELECT that requests data in its binary representation), the database server calls the send support function. The send support function takes the appropriate server internal representation of the opaque data type and returns the client internal representation of that type, encapsulated in an mi_sendrecv structure, as the following signature shows:

mi_sendrecv *send(srvr_internal_rep)

send: is the name of the C-language function that implements the send support function for the opaque type. It is recommended that you include the name of the opaque type in its send function.
srvr_internal_rep: is the appropriate format for the server internal representation of the opaque data type. The passing mechanism of this argument value depends on the kind of opaque type, as Figures Figure 126 through Figure 128 show. Most opaque types are passed by reference.

An mi_sendrecv is always passed by reference. Therefore, the return value of the send support function must always be a pointer to the mi_sendrecv data type. For information on how to obtain information from this varying-length structure, see Information About Varying-Length Data.

Figure 126 declares a sample send support function for a fixed-length opaque type named circle (which Figure 113 declares).

Figure 126. Send Support Function for circle Opaque Type

/* Send support function: circle */
mi_sendrecv *circle_send(srvr_intrnl_rep)
   circle_t *srvr_intrnl_rep;

The circle_send( ) function is a cast function from the circle_t internal representation (on the server computer) to the mi_sendrecv data type (which contains the client internal representation for circle). The database server executes circle_send( ) when it needs a cast function to convert from the internal representation of the circle opaque type to the SQL data type SENDRECV. For more information, see Support Functions as Casts.

The circle_send( ) function accepts as an argument a pointer to the circle_t data type. Because circle cannot fit into an MI_DATUM structure, it must be passed by reference. If your fixed-length opaque type can fit into an MI_DATUM structure, the send support function can pass the server internal representation by value. Figure 127 declares a sample send function for a fixed-length opaque type named two_bytes (which Figure 116 declares)

Figure 127. Send Support Function for two_bytes Opaque Type

/* Send support function: two_bytes */
mi_sendrecv *two_bytes_send(srvr_intrnl_rep)
   two_bytes_t srvr_intrnl_rep;

The two_bytes opaque type must be registered as PASSEDBYVALUE to tell the database server that it can be passed by value.

Figure 128 declares a sample send support function for a varying-length opaque type named image (which Figure 114 declares)

Figure 128. Send Support Function for image Opaque Type

/* Send support function: image */
mi_sendrecv *image_send(srvr_intrnl_rep)
   mi_lvarchar *srvr_intrnl_rep;

The image opaque type stores its data inside an mi_lvarchar structure, which must be passed by reference. The image_send( ) function is a cast function from the mi_lvarchar data type (which contains the server internal representation of image) to the mi_sendrecv data type (which contains the client internal representation of image).

The send support function performs the following tasks:

Accepts as an argument a pointer to the appropriate server internal representation of the opaque type
If the opaque data type is passed by reference, the send function accepts a pointer to the server internal representation. If the opaque data type is passed by value, the send function accepts the actual value of the internal representation instead of a pointer to this representation. For more information, see Determining the Passing Mechanism for an Opaque Type.
Allocates enough space to hold the client internal representation
The send function can use the mi_alloc( ) DataBlade API function to allocate the space for the internal representation. For more information on memory management, see Managing User Memory.
Creates the client internal representation from the individual members of the server internal representation
The DataBlade API provides functions to convert simple C data types from server to client binary representations. For example, to convert the double-precision values in the circle_t structure to their binary representation on the client computer, the circle_send( ) function can call the mi_put_double_precision( ) function. For a list of these DataBlade API functions, see Conversion of Opaque-Type Data with Computer-Specific Data Types.
Copies the client internal representation into an mi_sendrecv structure
You must use the mi_new_var( ) function to create a new mi_sendrecv structure. You can use mi_set_vardata( ) to copy the data into the mi_sendrecv structure or mi_set_varptr( ) to store the pointer to storage allocated by mi_alloc( ).
Returns a pointer to the client internal representation for the opaque type
This client internal representation must reside in the data portion of an mi_sendrecv structure. Therefore, the send support function returns a pointer to this mi_sendrecv structure.

Conversion of Opaque-Type Data with Computer-Specific Data Types

The send and receive support functions can call DataBlade API functions to convert data of the atomic C data types within the internal (binary) representation of an opaque data type. Table 114 shows the DataBlade API functions that can convert a difference in alignment or byte order between the client computer and the server computer.

Table 114. Type-Transfer Functions of the DataBlade API
Type of Data	DataBlade API Function
Type of Data	In Send Support Function	In Receive Support Function
Byte data	mi_put_bytes( )	mi_get_bytes( )
Date and Date/time data
DATE data	mi_put_date( )	mi_get_date( )
DATETIME data	mi_put_datetime( )	mi_get_datetime( )
INTERVAL data	mi_put_interval( )	mi_get_interval( )
Integer data
SMALLINT data (two-byte integers)	mi_put_smallint( ), mi_fix_smallint( )	mi_get_smallint( ), mi_fix_smallint( )
INTEGER data (four-byte integers)	mi_put_integer( ), mi_fix_integer( )	mi_get_integer( ), mi_fix_integer( )
INT8 data (eight-byte integers)	mi_put_int8( )	mi_get_int8( )
Fixed-point and Floating-point data
DECIMAL data (fixed-point and floating-point)	mi_put_decimal( )	mi_get_decimal( )
MONEY data	mi_put_money( )	mi_get_money( )
SMALLFLOAT data	mi_put_real( )	mi_get_real( )
FLOAT data	mi_put_double_precision( )	mi_get_double_precision( )
Other data
Character data	mi_put_string( )	mi_get_string( )
LO handle (smart large objects)	mi_put_lo_handle( )	mi_get_lo_handle( )

Global Language Support

Characters have the same binary representation on all architectures, so they do not need to be converted. However, if the code sets of the server-processing locale (in which the UDR executes) and the client locale differ, the mi_get_string( ) and mi_put_string( ) functions automatically perform the appropriate code-set conversion (provided that the two code sets are compatible). For more information about how to internationalize a C UDR, see Internationalization of DataBlade API Modules (GLS).

End of Global Language Support

Bulk-Copy Support Functions

The database server can copy data in and out of a database with a bulk copy operation. In a bulk copy, the database server reads or sends large numbers of column values in a copy file, rather than handling each column value individually. IBM Informix utilities such as DB–Access, the dbimport and dbexport utilities, and the High Performance Loader (HPL) can perform bulk copies.

The format of the opaque-type data in the copy file is called its unload representation. This unload representation might be different from the server internal representation of the opaque-type data (which is stored in the database). You can create the following opaque-type support functions to handle the unload representations of the opaque-type data.

Unload Representation	Description	Opaque-Type Support Functions
External unload representation	The text format of the opaque type, as it resides in a copy file	import, export
Internal unload representation	The binary format of the opaque type, as it resides in a copy file	importbin, exportbin

External Unload Representation

To handle opaque-type data in its external unload representation, the database server calls the import and export support functions of the opaque type. The external unload representation is the text version of the opaque-type data when it resides in a copy file. Usually, the external unload and external representations of an opaque type are the same. When a bulk-copy utility sends or receives opaque-type data in its external unload representation, the database server must find a support function to handle any conversion between this text in the copy file and the individual field values of the server internal representation. The import and export support functions are the cast functions for an opaque type between its external unload representation (its text format in a copy file) and its server internal (binary) representation.

Important:

An opaque data type only requires import and export support functions if its external unload representation is different from its external representation (which the input and output support functions handle). For most opaque data types, the database server can use the input and output support functions for import and export, respectively, to handle bulk copies of the opaque-type columns to and from their text representation.

The database server stores the external unload representation of an opaque type in an mi_impexp structure. The mi_impexp structure is a varying-length structure that encapsulates the external unload representation. Its ability to store varying-length data enables it to handle any possible changes in the size of the opaque-type data when it is converted between its server internal and its external unload representations. For example, opaque data types that contain smart large objects might have a filename in their external unload representation rather than storing all the smart-large-object data in the copy file.

Because the mi_impexp data type is a varying-length structure (like mi_lvarchar), it is always passed by reference. Therefore, the import and export support routines have the following basic signatures.

Opaque-Type Support Function	Cast From	Cast To
Import	mi_impexp *	Server internal representation of the opaque data type
Export	Server internal representation of the opaque data type	mi_impexp *

Global Language Support

For your opaque data type to accept an external representation in nondefault locales, you must internationalize the import and export support functions. For more information, see Internationalization of DataBlade API Modules (GLS).

End of Global Language Support

For most opaque types, the import support function can be the same as the input support function because the external representation and the external unload representation are usually the same. For such opaque types, you can handle the import support function in either of the following ways:

Call the input function inside the import function.
The import functions for the circle opaque type (Figure 129) and the two_bytes opaque type (Figure 130) use this method.
Omit the import function from the definition of the opaque type.
You must still create the implicit cast from the IMPBIN data type to the opaque data type with the CREATE CAST statement. However, instead of listing an import support function as the cast function, list the input support function. The database server would then automatically call the appropriate input support function to load the opaque type when it is in its external unload representation.

Import Support Function

When a bulk-copy utility performs a load of opaque-type data in its external unload representation, the database server calls the import support function. For example, when DB–Access performs a bulk load of an opaque-type column with the LOAD statement, the database server calls the import support function for the opaque type.

The import support function takes the external unload representation of the opaque type, which is encapsulated in an mi_impexp structure, and returns the appropriate server internal representation of that type, as the following signature shows:

srvr_internal_rep import(external_unload_rep)
   mi_impexp *external_unload_rep;

external_unload_rep: is a pointer to an mi_impexp structure that holds the external unload representation of the opaque type.
An mi_impexp is always passed by reference. Therefore, the external_unload_rep argument must always be a pointer to the mi_impexp data type. For information on how to obtain information from this varying-length structure, see Information About Varying-Length Data.
import: is the name of the C-language function that implements the import support function for the opaque type. It is recommended that you include the name of the opaque type in its import function.
srvr_internal_rep: is the appropriate format for the server internal representation of the opaque data type. The passing mechanism of this return value depends on the kind of opaque type, as Figures Figure 129 through Figure 131 show. Most opaque types are passed by reference.

Figure 129 declares a sample import support function for a fixed-length opaque type named circle (which Figure 113 declares).

Figure 129. Import Support Function for circle Opaque Type

/* Import support function: circle */
circle_t *circle_imp(extrnl_unload_rep)
   mi_impexp *extrnl_unload_rep;
{
   return (circle_input((mi_lvarchar *)extrnl_unload_rep));
}

The circle_imp( ) function is a cast function from the mi_impexp data type (which contains the external unload representation for the circle opaque type) to the circle_t internal representation (on the server computer). The database server executes circle_imp( ) when it needs a cast function to convert from the SQL data type IMPEXP to the server internal representation of the circle opaque type. For more information, see Support Functions as Casts.

The circle_imp( ) function returns a pointer to the circle_t data type. Because circle cannot fit into an MI_DATUM structure, it must be passed by reference. If your fixed-length opaque type can fit into an MI_DATUM structure, the import support function can return the server internal representation by value. Figure 130 declares a sample import function for a fixed-length opaque type named two_bytes (which Figure 116 declares).

Figure 130. Import Support Function for two_bytes Opaque Type

/* Import support function: two_bytes */
two_bytes_t two_bytes_imp(extrnl_unload_rep)
   mi_impexp *extrnl_unload_rep;
{
   return ( two_bytes_input( (mi_lvarchar *)extrnl_unload_rep) );
}

The two_bytes opaque type must be registered as PASSEDBYVALUE to tell the database server that it can be passed by value.

Figure 131 declares a sample import support function for a varying-length opaque type named image (which Figure 114 declares).

Figure 131. Import Support Function for image Opaque Type

/* Import support function: image */
mi_lvarchar *image_imp(extrnl_unload_rep)
   mi_impexp *extrnl_unload_rep;

The image opaque type stores its data inside an mi_lvarchar structure, which must be passed by reference. The image_imp( ) function is a cast function from the mi_impexp data type (which contains the external unload representation of image) to the mi_lvarchar data type (which contains the server internal representation of image).

Typically, only opaque data types that contain smart large objects have import and export functions defined. The external unload representation can include a client filename (which contains the smart-large-object data), a length, and an offset. The import support function can use the mi_lo_from_file( ) function (with the MI_O_CLIENT_FILE file-mode constant) to:

Open the specified client file.
Load from the client file into a new smart large object, the smart-large-object data that the length specified, starting at the specified offset, for the amount of data that the length specifies.

Finally, the import function must save the LO handle for the new smart large object in the server internal representation of the opaque type.

Tip:

For opaque types with smart large objects, you can choose whether to provide support for an external representation (a client filename, length, and offset) in the input and output support functions or the import and export support functions. When you define the input and output support functions to handle this external representation, applications can use this representation as a literal value for opaque-type data.

For an opaque type that does require an import support function, the import function performs the following tasks:

Accepts as an argument a pointer to the external unload representation of the opaque type
The external unload representation is in the data portion of an mi_impbin structure, which is passed by reference.
Allocates enough space to hold the server internal representation of the opaque type
The import function can use the mi_alloc( ) DataBlade API function to allocate the space for the internal representation. For more information on memory management, see Managing User Memory.
Parses the input string of the external unload representation
Obtain the individual members from the input string and store them into the appropriate fields of the server internal representation. The DataBlade API provides functions to convert various DataBlade API data types from their external to internal representations. For example, to convert a date string in an external unload representation to its internal representation (the mi_date value in the image_t structure), the image_imp( ) function can call the mi_string_to_date( ) function. For a list of these DataBlade API functions, see Conversion of Opaque-Type Data Between Text and Binary Representations.
Returns the appropriate server internal representation for the opaque type
If the opaque data type is passed by reference, the import function returns a pointer to the server internal representation. If the opaque data type is passed by value, the import function returns the actual value of the internal representation instead of a pointer to this representation. For more information, see Determining the Passing Mechanism for an Opaque Type.

Because the image opaque type contains a smart large object, it would require an import function. From the external unload representation that is read from the copy file, the import function could obtain the name of the client file that contains the smart-large-object data.

Export Support Function

When a bulk-copy utility performs an unload of opaque-type data to its external unload representation, the database server calls the export support function. For example, when DB–Access performs a bulk unload of an opaque-type column with the UNLOAD statement, the database server calls the export support function for the opaque type.

The export support function takes the appropriate server internal representation of the opaque data type and returns the external unload representation of that type, encapsulated in an mi_impexp structure, as the following signature shows:

mi_impexp *export(srvr_internal_rep)

export: is the name of the C-language function that implements the export support function for the opaque type. It is recommended that you include the name of the opaque type in its export function.
srvr_internal_rep: is the appropriate format for the server internal representation of the opaque data type. The passing mechanism of this argument value depends on the kind of opaque type, as Figures Figure 126 through Figure 128 show. Most opaque types are passed by reference.

An mi_impexp is always passed by reference. Therefore, the return value of the export support function must always be a pointer to the mi_impexp data type. For information on how to obtain information from this varying-length structure, see Information About Varying-Length Data.

Figure 132 declares a sample export support function for a fixed-length opaque type named circle (which Figure 113 declares).

Figure 132. Export Support Function for circle Opaque Type

/* Export support function: circle */
mi_impexp *circle_exp(srvr_intrnl_rep)
   circle_t *srvr_intrnl_rep;
{
   return ((mi_impexp *)circle_output(srvr_intrnl_rep));
}

The circle_exp( ) function is a cast function from the circle_t internal representation (on the server computer) to the mi_impexp data type (which contains the external unload representation for circle). The database server executes circle_exp( ) when it needs a cast function to convert from the server internal representation of the circle opaque type to the SQL data type IMPEXP. For more information, see Support Functions as Casts.

The circle_exp( ) function accepts as an argument a pointer to the circle_t data type. Because circle cannot fit into an MI_DATUM structure, it must be passed by reference. If your fixed-length opaque type can fit into an MI_DATUM structure, the export support function can pass the server internal representation by value. Figure 133 declares a sample export function for a fixed-length opaque type named two_bytes (which Figure 116 declares).

Figure 133. Export Support Function for two_bytes Opaque Type

/* Export support function: two_bytes */
mi_impexp *two_bytes_exp(srvr_intrnl_rep)
   two_bytes_t srvr_intrnl_rep;
{
   return ((mi_impexp *)two_bytes_output(srvr_intrnl_rep));
}

The two_bytes opaque type must be registered as PASSEDBYVALUE to tell the database server that it can be passed by value.

Figure 134 declares a sample export support function for a varying-length opaque type named image (which Figure 114 declares).

Figure 134. Export Support Function for image Opaque Type

/* Export support function: image */
mi_impexp *image_exp(srvr_intrnl_rep)
   mi_lvarchar *srvr_intrnl_rep;

The image opaque type stores its data inside an mi_lvarchar structure, which must be passed by reference. The image_exp( ) function is a cast function from the mi_lvarchar data type (which contains the server internal representation of image) to the mi_impexp data type (which contains the external unload representation of image).

In most cases, the export support function can be the same as the output support function, because the external representation and the external unload representation are usually the same. For such opaque types, you can handle the export functions in either of the following ways:

Call the output function inside the export function.
The export functions for the circle opaque type (Figure 132) and the two_bytes opaque type (Figure 133) use this method.
Omit the export function from the definition of the opaque type.
You must still create the explicit cast from the opaque data type to the IMPBIN data type with the CREATE CAST statement. However, instead of listing an export support function as the cast function, list the output support function. The database server would then automatically call the appropriate output support function to unload the opaque type to its external unload representation.

Typically, only opaque data types that contain smart large objects have import and export functions defined. The external unload representation can include a client filename (which contains the smart-large-object data), a length, and an offset. The export support function can obtain the LO handle of the smart large object from the server internal representation of the opaque type. With this LO handle, export can use the mi_lo_to_file( ) function (with the MI_O_CLIENT_FILE file-mode constant) to:

Create the specified file on the client computer.
Write the smart-large-object data into this file at the specified offset and for the number of bytes that the length specifies.

Finally, the export function can put the client filename, length of data, and starting offset into the external unload representation that is to be written to the copy file.

Tip:

For an opaque type that does require an export support function, the export function performs the following tasks:

Accepts as an argument a pointer to the appropriate server internal representation of the opaque type
If the opaque data type is passed by reference, the export function accepts a pointer to the server internal representation. If the opaque data type is passed by value, the export function accepts the actual value of the internal representation instead of a pointer to this representation. For more information, see Determining the Passing Mechanism for an Opaque Type.
Allocates enough space to hold the external unload representation of the opaque type
The export function can use the mi_alloc( ) DataBlade API function to allocate the space for the character string. For more information on memory management, see Managing User Memory.
Creates the external unload representation from the individual members of the server internal representation
The DataBlade API provides functions to convert various DataBlade API data types from their internal to external representations. For example, to convert the mi_date value in the image_t structure to its appropriate external representation, the image_exp( ) function can call the mi_date_to_string( ) function. For a list of these DataBlade API functions, see Conversion of Opaque-Type Data Between Text and Binary Representations.
Copies the external unload representation into an mi_impexp structure
You can use the mi_new_var( ) function to create a new mi_impexp structure and the mi_get_vardata( ) or mi_get_vardata_align( ) function to obtain a pointer to the data portion of this structure.
Returns a pointer to the external unload representation for the opaque type
This character string must reside in the data portion of an mi_impexp structure. Therefore, the export support function returns a pointer to this mi_impexp structure.

Because the image opaque type contains a smart large object, it would require an export function, which could save in the external unload representation that is written to the copy file the name of the client file that contains the smart-large-object data.

Internal Unload Representation

To handle opaque-type data in its internal unload representation, the database server calls the importbin and exportbin support functions of the opaque type. The internal unload representation is the binary version of the opaque-type data when it resides in a copy file. Usually, the internal unload and server internal representations of an opaque type are the same. When a bulk-copy utility sends or receives opaque-type data in its internal unload representation, the database server must find a support function to handle the possibility that the client computer uses a different byte ordering than the server computer. The importbin and exportbin support functions are the cast functions for an opaque type between its internal (binary) unload representation (its binary format in a copy file) and its server internal (binary) representation.

Important:

An opaque data type only requires importbin and exportbin support functions if its internal unload representation is different from its server internal representation (which the send and receive support functions handle). For most opaque data types, the database server can use the send and receive support functions for importbin and exportbin, respectively, to handle bulk copies of the opaque-type columns to and from their binary representation.

The database server stores the internal unload representation of an opaque type in an mi_impexpbin structure, which is a varying-length structure. Its ability to store varying-length data enables it to handle any possible changes in the size of the opaque-type data when it is converted between these two internal representations. For example, the client and server computers might have different packing rules for structures.

Because the mi_impexpbin data type is a varying-length structure (like mi_lvarchar), it is always passed by reference. Therefore, the importbin and exportbin support routines have the following basic signatures.

Opaque-Type Support Function	Cast From	Cast To
Importbin	mi_impexpbin *	Server internal representation of the opaque data type
Exportbin	Server internal representation of the opaque data type	mi_impexpbin *

Importbin Support Function

When a bulk-copy utility performs a load of opaque-type data in its internal unload representation, the database server calls the importbin support function. The importbin support function takes the internal unload representation of the opaque type, which is encapsulated in an mi_impexpbin structure, and returns the appropriate server internal representation of that type, as the following signature shows:

srvr_internal_rep importbin(internal_unload_rep)
   mi_impexpbin *internal_unload_rep;

importbin: is the name of the C-language function that implements the importbin support function for the opaque type. It is recommended that you include the name of the opaque type in its importbin function.
internal_unload_rep: is a pointer to an mi_impexpbin structure that holds the internal unload representation of the opaque type.
An mi_impexpbin is always passed by reference. Therefore, the internal_unload_rep argument must always be a pointer to the mi_impexpbin data type. For information on how to obtain information from this varying-length structure, see Information About Varying-Length Data.
srvr_internal_rep: is the appropriate format for the server internal representation of the opaque data type. The passing mechanism of this return value depends on the kind of opaque type, as Figures Figure 135 through Figure 137 show. Most opaque types are passed by reference.

Figure 135 declares a sample importbin support function for a fixed-length opaque type named circle (which Figure 113 declares).

Figure 135. Importbin Support Function for circle Opaque Type

/* Importbin support function: circle */
circle_t *circle_impbin(intrnl_unload_rep)
   mi_impexpbin *intrnl_unload_rep;
{
   return ( circle_recv((mi_sendrecv *)intrnl_unload_rep) );
}

The circle_impbin( ) function is a cast function from the mi_impexpbin data type (which contains the internal unload representation for the circle opaque type) to the circle_t internal representation (on the server computer). The database server executes circle_impbin( ) when it needs a cast function to convert from the SQL data type IMPEXPBIN to the server internal representation of the circle opaque type. For more information, see Support Functions as Casts.

The circle_impbin( ) function returns a pointer to the circle_t data type. Because circle cannot fit into an MI_DATUM structure, it must be passed by reference. If your fixed-length opaque type can fit into an MI_DATUM structure, the importbin support function can return the server internal representation by value. Figure 136 declares a sample importbin function for a fixed-length opaque type named two_bytes (which Figure 116 declares).

Figure 136. Importbin Support Function for two_bytes Opaque Type

/* Importbin support function: two_bytes */
two_bytes_t two_bytes_impbin(intrnl_unload_rep)
   mi_impexpbin *intrnl_unload_rep;
{
   return ( two_bytes_recv( (mi_sendrecv *)intrnl_unload_rep) );
}

The two_bytes opaque type must be registered as PASSEDBYVALUE to tell the database server that it can be passed by value.

Figure 137 declares a sample importbin support function for a varying-length opaque type named image (which Figure 114 declares).

Figure 137. Importbin Support Function for image Opaque Type

/* Importbin support function: image */
mi_lvarchar *image_impbin(intrnl_unload_rep)
   mi_impexpbin *intrnl_unload_rep;
{
   return ( image_recv( (mi_sendrecv *)intrnl_unload_rep) );
}

The image opaque type stores its data inside an mi_lvarchar structure, which must be passed by reference. The image_impbin( ) function is a cast function from the mi_impexpbin data type (which contains the internal unload representation of image) to the mi_lvarchar data type (which contains the server internal representation of image).

For most opaque types, the importbin support function can be the same as the receive support function, because the client internal representation and the internal unload representation are the same. For such opaque types, you can handle the importbin function in either of the following ways:

Call the receive function inside the importbin function
The importbin functions for the circle opaque type (Figure 135), the two_bytes opaque type (Figure 136), and the image opaque type (Figure 137) use this method.
Omit the importbin function from the definition of the opaque type
You must still create the implicit cast from the IMPBINBIN data type to the opaque data type with the CREATE CAST statement. However, instead of listing an importbin support function as the cast function, list the receive support function. The database server would then automatically call the appropriate receive support function to load the opaque type when it is in its internal unload representation.

For an opaque type that does require an importbin support function, the importbin function performs the following tasks:

Accepts as an argument a pointer to the internal unload representation of the opaque type
The internal unload representation is in the data portion of an mi_impexpbin structure, which is passed by reference.
Allocates enough space to hold the server internal representation of the opaque type
The importbin function can use the mi_alloc( ) DataBlade API function to allocate the space for the internal representation. For more information on memory management, see Managing User Memory.
Creates the server internal representation from the individual members of the internal unload representation
The DataBlade API provides functions to convert simple C data types from their client to server binary representations. For example, to convert the double-precision values in the circle_t structure to their binary representation on the server computer, the circle_impbin( ) function can call the mi_get_double_precision( ) function. For a list of these DataBlade API functions, see Conversion of Opaque-Type Data with Computer-Specific Data Types.
Returns the appropriate server internal representation for the opaque type
If the opaque data type is passed by reference, the importbin function returns a pointer to the server internal representation. If the opaque data type is passed by value, the importbin function returns the actual value of the internal representation instead of a pointer to this representation. For more information, see Determining the Passing Mechanism for an Opaque Type.

Exportbin Support Function

When a bulk-copy utility performs an unload of opaque-type data to its internal unload representation, the database server calls the exportbin support function. The exportbin support function takes the appropriate server internal representation of the opaque data type and returns the internal unload representation of that type, encapsulated in an mi_impexpbin structure, as the following signature shows:

mi_impexpbin *exportbin(srvr_internal_rep)

exportbin: is the name of the C-language function that implements the exportbin support function for the opaque type. It is recommended that you include the name of the opaque type in its exportbin function.
srvr_internal_rep: is the appropriate format for the server internal representation of the opaque data type. The passing mechanism of this argument value depends on the kind of opaque type, as Figures Figure 138 through Figure 140 show. Most opaque types are passed by reference.

An mi_impexpbin is always passed by reference. Therefore, the return value of the exportbin support function must always be a pointer to the mi_impexpbin data type. For information on how to obtain information from this varying-length structure, see Information About Varying-Length Data.

Figure 138 declares a sample exportbin support function for a fixed-length opaque type named circle (which Figure 113 declares).

Figure 138. Exportbin Support Function for circle Opaque Type

/* Exportbin support function: circle */
mi_impexpbin *circle_expbin(srvr_intrnl_rep)
   circle_t *srvr_intrnl_rep;
{
   return ((mi_impexpbin *)circle_send(srvr_intrnl_rep));
}

The circle_expbin( ) function is a cast function from the circle_t internal representation (on the server computer) to the mi_impexpbin data type (which contains the internal unload representation for circle). The database server executes circle_expbin( ) when it needs a cast function to convert from the server internal representation of the circle opaque type to the SQL data type IMPEXPBIN. For more information, see Support Functions as Casts.

The circle_expbin( ) function accepts as an argument a pointer to the circle_t data type. Because circle cannot fit into an MI_DATUM structure, it must be passed by reference. If your fixed-length opaque type can fit into an MI_DATUM structure, the exportbin support function can pass the server internal representation by value. Figure 139 declares a sample exportbin function for a fixed-length opaque type named two_bytes (which Figure 116 declares).

Figure 139. Exportbin Support Function for two_bytes Opaque Type

/* Exportbin support function: two_bytes */
mi_impexpbin *two_bytes_expbin(srvr_intrnl_rep)
   two_bytes_t srvr_intrnl_rep;
{
   return ( (mi_impexpbin *)two_bytes_send( srvr_intrnl_rep) );
}

The two_bytes opaque type must be registered as PASSEDBYVALUE to tell the database server that it can be passed by value.

Figure 140 declares a sample exportbin support function for a varying-length opaque type named image (which Figure 114 declares).

Figure 140. Exportbin Support Function for image Opaque Type

/* Exportbin support function: image */
mi_impexpbin *image_expbin(srvr_intrnl_rep)
   mi_lvarchar *srvr_intrnl_rep;
{
   return ((mi_impexpbin *)image_send(srvr_intrnl_rep));
}

The image opaque type stores its data inside an mi_lvarchar structure, which must be passed by reference. The image_expbin( ) function is a cast function from the mi_lvarchar data type (which contains the server internal representation of image) to the mi_impexpbin data type (which contains the internal unload representation of image).

For most opaque types, the exportbin function can be the same as the send support function, because the client internal representation and the internal unload representation are the same. For such opaque types, you can handle the exportbin support function in either of the following ways:

Call the send function inside the exportbin function.
The circle opaque type (Figure 138), the two_bytes opaque type (Figure 139), and the image opaque type (Figure 140) use this method.
Omit the exportbin function from the definition of the opaque type.
You must still create the explicit cast from the opaque data type to the IMPEXPBIN data type with the CREATE CAST statement. However, instead of listing an exportbin support function as the cast function, list the send support function. The database server would then automatically call the appropriate send support function to unload the opaque type to its internal unload representation.

For an opaque type that does require an exportbin support function, the exportbin function performs the following tasks:

Accepts as an argument a pointer to the appropriate server internal representation of the opaque type
If the opaque data type is passed by reference, the exportbin function accepts a pointer to the server internal representation. If the opaque data type is passed by value, the exportbin function returns the actual value of the internal representation instead of a pointer to this representation. For more information, see Determining the Passing Mechanism for an Opaque Type.
Allocates enough space to hold the internal unload representation of the opaque type
The exportbin function can use the mi_alloc( ) DataBlade API function to allocate the space for the internal representation. For more information on memory management, see Managing User Memory.
Creates the internal unload representation from the individual members of the server internal representation
The DataBlade API provides functions to convert simple C data types from server to client binary representations. For example, to convert the double-precision values in the circle_t structure to their binary representation on the client computer, the circle_expbin( ) function can call the mi_put_double_precision( ) function. For a list of these DataBlade API functions, see Conversion of Opaque-Type Data with Computer-Specific Data Types.
Copies the internal unload representation into an mi_impexpbin structure
You can use the mi_new_var( ) function to create a new mi_impexpbin structure and the mi_get_vardata( ) or mi_get_vardata_align( ) function to obtain a pointer to the data portion of this structure.
Returns a pointer to the internal unload representation for the opaque type
This internal unload representation must reside in the data portion of an mi_impexpbin structure. Therefore, the exportbin support function returns a pointer to this mi_impexpbin structure.

Stream Support Functions

The following support functions convert a UDT to or from a stream representation while reading the UDT from a stream or writing the UDT to a stream.

Support Function: Purpose
streamwrite( ): Conversion of opaque-type data from its binary representation to its stream representation
streamread( ): Conversion of opaque-type data from its stream representation to its binary representation

The stream representation is self-contained and includes enough information to enable the streamread( ) function to re-create the UDT instance.

Important:

If the UDT includes out-of-row data, the stream representation should normally include that data.

Enterprise Replication invokes the streamwrite( ) and streamread( ) support functions when replicating UDT columns. The streams it passes to these functions are Enterprise Replication streams, a write-only stream for streamwrite() and a read-only stream for streamread(). You cannot open or close an Enterprise Replication stream or use the mi_stream_setpos( ) or mi_stream_seek( ) function on it. For more information about Enterprise Replication, see the IBM Informix: Dynamic Server Enterprise Replication Guide.

Important:

If a column that includes out-of-row data is to be replicated, avoid placing a NOT NULL constraint on the column. Enterprise Replication collects out-of-row data for transmission after the user transaction has committed. Due to activity on the replicated row, the data might not exist at the time Enterprise Replication collects it for replication. In such cases, Enterprise Replication normally applies a NULL on the target system.

The streamwrite( ) Support Function

On a destination database server, the streamwrite( ) support function converts opaque-type data from its binary representation to its stream representation. The streamwrite( ) support function accepts a stream descriptor and the address of opaque-type data to write, as the following signature shows:

mi_integer streamwrite(strm_desc, binary_rep)
   MI_STREAM *strm_desc;
   my_opq_type *binary_rep;

strm_desc: is a pointer to a stream descriptor for an open stream. For more information, see Access to a Stream (Server).
binary_rep: is a pointer to the binary representation of the opaque-type data, which is written to the stream.
The binary representation is the appropriate format for the opaque-type data. The passing mechanism for this data depends on the kind of opaque type, as Figures Figure 117 through Figure 119 show. Most opaque-type values are passed by reference to the streamwrite( ) function as single pointers.

The streamwrite( ) function returns the number of bytes written to the stream or MI_ERROR. This function can also return the errors that mi_stream_write( ) returns. To convert the individual fields of the opaque-type internal representation to their stream representation, streamwrite( ) can call the stream-write functions of the DataBlade API (see Table 115).

A sample SQL declaration for the streamwrite() function follows:

CREATE FUNCTION streamwrite(STREAM, MyUdt)
RETURNS INTEGER
EXTERNAL NAME '/usr/local/udrs/stream/myudt.so(MyUdtStreamWrite)'
LANGUAGE C;

Tip:

Unlike most opaque-type support functions, the streamwrite( ) function for an opaque type must have the explicit name "streamwrite" when you register it with the CREATE FUNCTION statement. It is recommended that you include the name of the opaque type in the C-language version of its streamwrite( ) function.

The streamread( ) Support Function

On a target database server, the streamread( ) support function converts opaque-type data from its stream representation to its binary representation, which is stored in the target database. The streamread( ) support function accepts a stream descriptor and the address of a buffer into which to read the opaque-type data, as the following signature shows:

mi_integer streamread(strm_desc, binary_rep)
   MI_STREAM  *strm_desc;
   my_opq_type **binary_rep;

strm_desc: is a pointer to a stream descriptor for an open stream. For more information, see Access to a Stream (Server).
binary_rep: is a pointer to the buffer into which the function is to copy the binary representation of the opaque-type data.
The stream buffer is declared with the appropriate format for the binary representation of the opaque-type data. The passing mechanism for this buffer depends on the kind of opaque type, as Figures Figure 117 through Figure 119 show. Most buffers for opaque-type data are passed by reference to streamread( ) as double pointers.

The streamread( ) function returns the number of bytes read from the stream or MI_ERROR. This function can also return the errors that mi_stream_read( ) returns. To convert the individual fields of the opaque-type internal representation to their binary representation, streamwrite( ) can call the stream-read functions of the DataBlade API (see Table 115).

A sample SQL declaration for the streamread() function follows:

CREATE FUNCTION streamread(STREAM, OUT MyUdt)
RETURNS INTEGER
EXTERNAL NAME '/usr/local/udrs/stream/myudt.so(MyUdtStreamRead)'
LANGUAGE C;

Tip:

Unlike most opaque-type support functions, the streamread( ) function for an opaque type must have the explicit name "streamread" when you register it with the CREATE FUNCTION statement. It is recommended that you include the name of the opaque type in the C-language version of its streamread( ) function.

Converting Opaque-Type Data Between Stream and Binary Representations

The DataBlade API provides several functions to convert built-in data types between binary and stream representations. The streamwrite( ) and streamread( ) support functions can use these DataBlade API functions to convert a UDT between its binary representation and its stream representation.

Important:

Writing a collection or row to a stream opened for Enterprise Replication is not supported. Likewise, reading a collection or row from a stream opened for Enterprise Replication is not supported.

Table 115 shows the DataBlade API stream-conversion functions.

Table 115. Stream-Conversion Functions of the DataBlade API
Type of Data	DataBlade API Function
Type of Data	The streamwrite( ) Support Function	The streamread( ) Support Function
Byte data	mi_stream_write( )	mi_stream_read( )
Date and Date/time data
DATE data	mi_streamwrite_date( )	mi_streamread_date( )
DATETIME data	mi_streamwrite_datetime( )	mi_streamread_datetime( )
INTERVAL data	mi_streamwrite_interval( )	mi_streamread_interval( )
Integer data
SMALLINT data (two-byte integers)	mi_streamwrite_smallint( )	mi_streamread_smallint( )
INTEGER data (four-byte integers)	mi_streamwrite_integer( )	mi_streamread_integer( )
INT8 data (eight-byte integers)	mi_streamwrite_int8( )	mi_streamread_int8( )
Fixed-point and Floating-point data
DECIMAL data (fixed- and floating-point)	mi_streamwrite_decimal( )	mi_streamread_decimal( )
MONEY data	mi_streamwrite_money( )	mi_streamread_money( )
SMALLFLOAT data	mi_streamwrite_real( )	mi_streamread_real( )
FLOAT data	mi_streamwrite_double( )	mi_streamread_double( )
Other data
Character data	mi_streamwrite_string( )	mi_streamread_string( )
Smart large objects	mi_streamwrite_lo( )	mi_streamread_lo( ) mi_streamread_lo_by_lofd( )
Boolean data	mi_streamwrite_boolean( )	mi_streamread_boolean( )
Collection structures	mi_streamwrite_collection( )	mi_streamread_collection( )
Row structures	mi_streamwrite_row( )	mi_streamread_row( )
Varying-length structures	mi_streamwrite_lvarchar( )	mi_streamread_lvarchar( )

The DataBlade API function converts the corresponding data type to a machine-independent stream representation.

Important:

The mistrmutil.h header file declares the stream-conversion functions of the DataBlade API; however, the mi.h header file does not include mistrmutil.h. You must explicitly include mistrmutil.h in files that use these stream-conversion functions.

Disk-Storage Support Functions

To provide the ability to perform special processing on the internal representation of an opaque type that it is stored on disk, you can define the following disk-storage support functions for an opaque type.

Support Function: Purpose
assign( ): Special processing required just before a row that contains the opaque-type column is inserted into the table (written to disk)
destroy( ): Special processing required just before a row that contains the opaque-type column is deleted from a table (removed from disk)

The disk internal representation is the contents of the C structure that is actually written to disk for the opaque-type column. The assign( ) and destroy( ) support functions are useful for opaque types that contain smart large objects. For such data types, assign( ) and destroy( ) can provide management of the associated smart large object as well as any necessary modification of the internal representation.

Important:

An opaque data type requires assign( ) and destroy( ) support functions only if its disk internal representation is different from its server internal representation. For most opaque types, these two representations are the same.

The assign( ) Support Function

The database server calls the assign( ) support function for an opaque type when a value is ready to be inserted into an opaque-type column (INSERT, UPDATE, or LOAD). The assign( ) support function accepts the server internal representation of the opaque type and returns the appropriate disk internal representation for that type, as the following signature shows:

disk_internal_rep assign(internal_rep);

disk_internal_rep: is the appropriate format for the disk internal representation of the opaque data type. The passing mechanism of this return value depends on the kind of opaque type. For more information, see Determining the Passing Mechanism for an Opaque Type. The disk internal representation is the internal format as modified by the assign( ) support function. This format is what the database server writes to the database table.
internal_rep: is the appropriate format for the server internal representation of the opaque data type. The passing mechanism of this return value depends on the kind of opaque type. For more information, see Determining the Passing Mechanism for an Opaque Type. The server internal representation is the representation that the input support function returns.
Tip:

Unlike most opaque-type support functions, the assign( ) function for an opaque type must have the explicit name "assign" when you register it with the CREATE FUNCTION statement. No implicit casting occurs when the database server resolves this function. However, it is recommended that you include the name of the opaque type in the C-language version of its assign( ) function.

The destroy( ) Support Function

The database server calls the destroy( ) support function for an opaque type when a value is ready to be deleted from an opaque-type column (DELETE or DROP TABLE). The destroy( ) support function accepts the disk internal representation of the opaque data type and does not return a value, as the following signature shows:

void destroy(disk_internal_rep);

disk_internal_rep: is the appropriate format for the disk internal representation of the opaque data type. The passing mechanism of this return value depends on the kind of opaque type. For more information, see Determining the Passing Mechanism for an Opaque Type.
Tip:

Unlike most opaque-type support functions, the destroy( ) function for an opaque type must have the explicit name "destroy" when you register it with the CREATE FUNCTION statement. No implicit casting occurs when the database server resolves this function. However, it is recommended that you include the name of the opaque type in the C-language version of its destroy( ) function.

Handling Locale-Specific Opaque-Type Data (GLS)

To internationalize your opaque type, you must ensure that the following support functions handle data in a nondefault locale:

The input and output support functions provide the ability to transfer the external representation of the opaque type.
The send and receive support functions provide the ability to transfer the binary representation of the opaque type.

For a description of the internationalization support that the DataBlade API provides, see Internationalization of DataBlade API Modules (GLS). For general information on internationalized support that the opaque-type can provide, see the chapter on support functions in the IBM Informix: User-Defined Routines and Data Types Developer's Guide.