The send support function

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

Function signature

The send support function takes the appropriate server internal representation of the opaque data type and returns the client internal representation of that type, encapsulated in an mi_sendrecv structure, as the following signature shows:

mi_sendrecv *send(srvr_internal_rep)

send: The name of the C-language function that implements the send support function for the opaque type. It is recommended that you include the name of the opaque type in its send function.
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_sendrecv is always passed by reference. Therefore, the return value of the send support function must always be a pointer to the mi_sendrecv 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 send support function for a fixed-length opaque type named circle (which Figure 1 declares).

Figure 1. Send Support Function for circle Opaque Type

/* Send support function: circle */
mi_sendrecv *circle_send(srvr_intrnl_rep)
   circle_t *srvr_intrnl_rep;

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

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

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

Figure 2. Send support function for two_bytes opaque type

/* Send support function: two_bytes */
mi_sendrecv *two_bytes_send(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 send support function for a varying-length opaque type named image (which Figure 1 declares).

Figure 3. Send support function for image opaque type

/* Send support function: image */
mi_sendrecv *image_send(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_send() function is a cast function from the mi_lvarchar data type (which contains the server internal representation of image) to the mi_sendrecv data type (which contains the client internal representation of image).

The send 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 send function accepts a pointer to the server internal representation. If the opaque data type is passed by value, the send 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 client internal representation
The send 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.
Creates the client internal representation from the individual members of the server internal representation
The DataBlade API provides functions to convert simple C data types from server to client binary representations. For example, to convert the double-precision values in the circle_t structure to their binary representation on the client computer, the circle_send() function can call the mi_put_double_precision() function. For a list of these DataBlade API functions, see Conversion of opaque-type data with computer-specific data types.
Copies the client internal representation into an mi_sendrecv structure
You must use the mi_new_var() function to create a new mi_sendrecv structure. You can use mi_set_vardata() to copy the data into the mi_sendrecv structure or mi_set_varptr() to store the pointer to storage allocated by mi_alloc().
Returns a pointer to the client internal representation for the opaque type
This client internal representation must be in the data portion of an mi_sendrecv structure. Therefore, the send support function returns a pointer to this mi_sendrecv structure.