In the
Informix® ESQL/C program,
the varying-length C structure, ifx_varlena_t, stores a binary
value for a var binary host variable. This data structure allows
you to transfer binary data without knowing the exact structure of
the internal format for the opaque data type. It provides a data buffer
to hold the data for the associated var binary host variable.
Important: The ifx_varlena_t structure is an opaque structure
to Informix ESQL/C programs.
That is, you do not access its internal structure directly. The internal
structure of ifx_varlena_t might change in future releases.
Therefore, to create portable code, always use the Informix ESQL/C accessor
functions for this structure to obtain and store values in the ifx_varlena_t structure.
For a list of these Informix ESQL/C access
functions, see The lvarchar pointer and var binary library functions.
This section uses a varying-length opaque data type called image to
demonstrate how the Informix ESQL/Cvar
binary host variable accesses an opaque data type. The image data
type encapsulates an image such as a JPEG, GIF, or PPM file. If the
image is less than 2 kilobytes, the data structure for the data type
stores the image directly. However, if the image is greater than 2
kilobytes, the data structure stores a reference (an LO-pointer structure)
to a smart large object that contains the image data. The following
figure shows the internal data structure for the image data
type in the database. Figure 1: Internal data structures for the image opaque
data type
typedef struct
{
int img_len;
int img_thresh;
int img_flags;
union
{
ifx_lop_t img_lobhandle;
char img_data[4];
}
} image_t;
typedef struct
{
point_t center;
double radius;
} circle_t;
The following figure shows the CREATE TABLE statement
that creates a table called image_tab that has a column of
type image and an image identifier. Figure 2: Creating a column of the image
opaque data type
The following figure shows how to use a var binary host
variable to insert and select data in the image_col column
of the image_tab table (see Creating a column of the image
opaque data type). Figure 3: Accessing the internal format
of the image opaque data type with a var binary host variable
#include <image.h>;
EXEC SQL BEGIN DECLARE SECTION;
var binary 'image' vbin_image;
EXEC SQL END DECLARE SECTION;
struct image_t user_image, *image_ptr;
int imgsz;
/* Load data into members of internal data structure
load_image(&user_image);
imgsz = getsize(&user_image);
/* Allocate memory for var binary data buffer */
ifx_var_flag(&vbin_image, 0);
ifx_var_alloc(&vbin_image, imgsz);
/* Assign data to data buffer of var binary host
* variable */
ifx_var_setdata(&vbin_image, &user_image, imgsz);
/* Insert a new image_tab row with a var binary host
* variable */
EXEC SQL insert into image_tab values (1, :vbin_image);
/* Deallocate image data buffer */
ifx_var_dealloc(&vbin_image);
/* Select an image_tab row from into a var binary
* host variable */
ifx_var_flag(&vbin_image, 1);
EXEC SQL select image_col into :vbin_image
from image_tab
where image_id = 1;
image_ptr = (image_t *)ifx_var_getdata(&vbin_image);
unload_image(&user_image);
ifx_var_dealloc(&vbin_image);