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);