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 is 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 file name 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 *

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

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 1) and the two_bytes opaque type (Figure 2) 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.