The output support function

When an application performs some operation that requests the external representation of an opaque type (such as a SELECT operation that requests data in its text representation), the database server calls the output support function.

Function signature

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

mi_lvarchar *output(srvr_internal_rep)

output: The name of the C-language function that implements the output support function for the opaque type. It is recommended that you include the name of the opaque type in the name of its output function. For example, if the UDT name is image, the name of the output function would be image_output().
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 Figure 1 through Figure 3 show. Most opaque types are passed by reference.

An mi_lvarchar value is always passed by reference. Therefore, the return value of the output support function 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.

Sample code fragments

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

Figure 1. Output support function for circle opaque type

/* Output support function: circle */
mi_lvarchar *circle_output(srvr_intrnl_rep)
   circle_t *srvr_intrnl_rep;

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

The circle_output() 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 output support function can pass the server internal representation by value.

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

Figure 2. Output support function for two_bytes opaque type

/* Output support function: two_bytes */
mi_lvarchar *two_bytes_output(srvr_intrnl_rep)
   two_bytes_t 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 output support function for a varying-length opaque type named image (which Figure 1 declares).

Figure 3. Output support function for image opaque type

/* Output support function: image */
mi_lvarchar *image_output(srvr_intrnl_rep)
   mi_lvarchar *srvr_intrnl_rep;

Function tasks

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

The output support 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 output support function accepts a pointer to the server internal representation. If the opaque data type is passed by value, the output 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 external representation of the opaque type
The output 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 output string of the external 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_output() 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 representation into an mi_lvarchar structure
You must use the mi_new_var() function to create a new mi_lvarchar structure. You can use mi_set_vardata() to copy data into the mi_lvarchar structure or mi_set_varptr() to store a pointer to storage allocated by mi_alloc().
Returns a pointer to the external representation for the opaque type
This character string must be in the data portion of an mi_lvarchar structure. Therefore, the output support function returns a pointer to this mi_lvarchar structure.