The input support function

When an application performs some operation that passes the external representation of an opaque type to the database server (such as INSERT or UPDATE with an opaque-type value as a literal string), the database server calls the input support function.

Function signature

The input support function accepts the external representation of the opaque type, which is encapsulated in an mi_lvarchar structure, and returns the appropriate server internal representation for that type, as the following signature shows:

srvr_internal_rep input(external_rep)
   mi_lvarchar *external_rep;

external_rep: A pointer to an mi_lvarchar structure that holds the external representation of the opaque type.
An mi_lvarchar is always passed by reference. Therefore, the external_rep argument must always be a pointer to the mi_lvarchar data type. For information about how to obtain information from this varying-length structure, see Information about varying-length data.
input: The name of the C-language function that implements the input support function for the opaque type. It is recommended that you include the name of the opaque type in its input 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 cod fragment declares a sample input support function for a fixed-length opaque type named circle (which Figure 1 declares).

Figure 1. Input support function for circle opaque type

/* Input support function: circle */
circle_t *circle_input(extrnl_rep)
   mi_lvarchar *extrnl_rep;

The circle_input() function is a cast function from the mi_lvarchar data type (which contains the external representation for the circle opaque type) to the circle_t internal representation (on the server computer). The database server executes circle_input() when it needs a cast function to convert from the SQL data type LVARCHAR to the server internal representation of the circle opaque type. For more information, see Support functions as casts.

The circle_input() 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 input support function can return the internal representation by value.

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

Figure 2. Input support function for two_bytes opaque type

/* Input support function: two_bytes */
two_bytes_t two_bytes_input(extrnl_rep)
   mi_lvarchar *extrnl_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 input support function for a varying-length opaque type named image (which Figure 1 declares).

Figure 3. Input support function for image opaque type

/* Input support function: image */
mi_lvarchar *image_input(extrnl_rep)
   mi_lvarchar *extrnl_rep;

Function tasks

The image opaque type stores its data inside an mi_lvarchar structure, which must be passed by reference. The image_input() function is a cast function from the external representation of image to the server internal representation of image.

The input support function performs the following tasks:

Accepts as an argument a pointer to the external representation of the opaque type
The external representation is in the data portion of an mi_lvarchar structure, which is passed by reference.
Allocates enough space to hold the server internal representation of the opaque type
The input function can use the mi_alloc() DataBlade API function to allocate the space for the internal representation, or the mi_new_var() function if the opaque type is varying length. For more information aboutmemory management, see Manage user memory.
Parses the input string of the external representation
The input function must 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 representation to its internal representation (the mi_date value in the image_t structure), the image_input() 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 input function returns a pointer to the server internal representation. If the opaque data type is passed by value, the input function returns the actual value of the server internal representation instead of a pointer to this representation. For more information, see Determine the passing mechanism for an opaque type.