The export support function

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)

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

/* 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 following code fragment declares a sample export function for a fixed-length opaque type named two_bytes (which Internal representation for the two_bytes opaque data type declares).

/* 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 following code fragment declares a sample export support function for a varying-length opaque type named image (which Internal representation for the image opaque data type declares).

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

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 (Export support function for circle opaque type) and the two_bytes opaque type (Export support function for two_bytes opaque type) 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 file name (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 file name, length of data, and starting offset into the external unload representation that is to be written to the copy file.

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