The var binary host variables

In the IBM® 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/C var 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

CREATE TABLE image_tab 
(
   image_id         integer not null primary key),
   image_col         image
);

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 Figure 2).

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

For more information about the ifx_var_flag(), ifx_var_alloc(), ifx_var_setdata(), ifx_var_getdata(), and ifx_var_dealloc() functions, see The lvarchar pointer and var binary library functions.