The 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.

Function signature

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: 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: 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 about how to obtain information from this varying-length structure, see Information about varying-length data.
srvr_internal_rep: 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 Figure 1 through Figure 3 show. Most opaque types are passed by reference.

Sample code fragments

The following code fragment declares a sample importbin support function for a fixed-length opaque type named circle (which Figure 1 declares).

Figure 1. 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.

The following code fragment declares a sample importbin function for a fixed-length opaque type named two_bytes (which Figure 1 declares).

Figure 2. 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.

The following code fragment declares a sample importbin support function for a varying-length opaque type named image (which Figure 1 declares).

Figure 3. 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) );
}

Usage

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 1), the two_bytes opaque type (Figure 2), and the image opaque type (Figure 3) use this method.
Omit the importbin function from the definition of the opaque type
You must still create the implicit cast from the IMPEXPBIN 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.

Function tasks

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 aboutmemory management, see Manage 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 Determine the passing mechanism for an opaque type.