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

Function signature

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: 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 about how to obtain information from this varying-length structure, see Information about varying-length data.
import: 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: 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 import support function for a fixed-length opaque type named circle (which Figure 1 declares).

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

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

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

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

Figure 3. Import support function for image opaque type

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

Usage

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 file name (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 the data from the client file into a new smart large object, starting at the specified offset, and ending when the specified length is reached.

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 file name, 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.

Function tasks

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 about memory management, see Manage 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 Determine 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 can obtain the name of the client file that contains the smart-large-object data.