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

Function signature

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: 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: 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 Exportbin support function for circle opaque type through Exportbin Support Function for image Opaque Type 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 about how to obtain information from this varying-length structure, see Information about varying-length data.

Sample code fragments

The following code fragment declares a sample exportbin support function for a fixed-length opaque type named circle (which Internal representation of the circle opaque data type declares).

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

The following code fragment declares a sample exportbin function for a fixed-length opaque type named two_bytes (which Internal representation for the two_bytes opaque data type declares).

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

The following code fragment declares a sample exportbin support function for a varying-length opaque type named image (which Internal representation for the image opaque data type declares).

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

Usage

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 (Exportbin support function for circle opaque type), the two_bytes opaque type (Exportbin support function for two_bytes opaque type), and the image opaque type (Exportbin Support Function for image Opaque Type) 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.

Function tasks

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 Determine 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 aboutmemory management, see Manage 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 be in the data portion of an mi_impexpbin structure. Therefore, the exportbin support function returns a pointer to this mi_impexpbin structure.