The receive support function

When an application executes a query, such as INSERT or UPDATE, and specifies binary transfer of data, the database server calls the receive support function.

The way to specify binary transfer (for fetch or send) depends on the client API:

ODBC uses an SQLBindCol() call.
The DataBlade® API mi_exec_prepared_statement() call takes a PARAMS_ARE_BINARY flag.
Informix® ESQL/C uses the host-variable data type to specify if the transfer is binary or text.

Function signature

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

srvr_internal_rep receive(client_internal_rep)
   mi_sendrecv *client_internal_rep;

client_internal_rep: A pointer to an mi_sendrecv structure that holds the client internal representation of the opaque type.
An mi_sendrecv is always passed by reference. Therefore, the client_internal_rep argument must always be a pointer to the mi_sendrecv data type. For more information, see Information about varying-length data.
receive: The name of the C-language function that implements the receive support function for the opaque type. It is recommended that you include the name of the opaque type in its receive 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 Receive support function for circle opaque type through Receive support function for image opaque type show. Most opaque types are passed by reference.

Sample code fragments

The following code fragment declares a sample receive support function for a fixed-length opaque type named circle (which Internal representation of the circle opaque data type declares).

Figure 1: Receive support function for circle opaque type

/* Receive support function: circle */
circle_t *circle_recv(client_intrnl_rep)
   mi_sendrecv *client_intrnl_rep;

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

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

The following code fragment declares a sample receive function for a fixed-length opaque type named two_bytes (which Internal representation for the two_bytes opaque data type declares).

Figure 2: Receive support function for two_bytes opaque type

/* Receive support function: two_bytes */
two_bytes_t two_bytes_recv(client_intrnl_rep)
   mi_sendrecv *client_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 receive support function for a varying-length opaque type named image (which Internal representation for the image opaque data type declares).

Figure 3: Receive support function for image opaque type

/* Receive support function: image */
mi_lvarchar *image_recv(client_intrnl_rep)
   mi_sendrecv *client_intrnl_rep;

Function tasks

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

The receive support function performs the following tasks:

Accepts as an argument a pointer to the client internal representation of the opaque type
The client internal representation is in the data portion of an mi_sendrecv structure, which is passed by reference.
Allocates enough space to hold the server internal representation of the opaque type
The receive 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 about memory management, see Manage user memory.
Creates the server internal representation from the individual members of the client internal representation
The DataBlade API provides functions to convert simple C data types from their client to server binary representations. For example, to convert the double-precision values in the circle_t structure to their binary representation on the server computer, the circle_recv() function can call the mi_get_double_precision() function. For a list of these DataBlade API functions, see Conversion of opaque-type data with computer-specific data types.
Returns the appropriate server internal representation for the opaque type
If the opaque data type is passed by reference, the receive function returns a pointer to the server internal representation. If the opaque data type is passed by value, the receive 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.