Informix-ESQL/C Programmer's Manual

Informix-ESQL/C Programmer's Manual
Chapter 8: Working with Simple Large Objects

Home Contents Index Master Index New Book

Programming with Simple Large Objects

ESQL/C supports the SQL simple large objects, the data types TEXT and BYTE, with the loc_t data type.

Tip: You cannot use literal values within an INSERT or UPDATE statement to put simple-large-object data within a TEXT or BYTE column. To insert values into a simple large object, you can use the LOAD statement from DB-Access or loc_t host variables from within an ESQL/C client application.

Because of the potentially huge size of simple-large-object data, the ESQL/C program does not store the data directly in a loc_t host variable. Instead, the loc_t structure is a locator structure. It does not contain the actual data; it contains information about the size and location of the simple-large-object data. You choose whether to store the data in memory, an operating-system file, or even user-defined locations.

To use simple-large-object variables in an ESQL/C program, take the following actions:

Declare a host variable with the loc_t data type
Access the fields of the loc_t locator structure

Declaring a Host Variable for a Simple Large Object

Use the loc_t data type to declare host variables for database values of type TEXT or BYTE. You declare a host variable for a simple-large-object column with the data type loc_t, as shown in the following example:

EXEC SQL include locator;
.

.

.


EXEC SQL BEGIN DECLARE SECTION;

	loc_t  text_lob;

	loc_t byte_lob;

EXEC SQL END DECLARE SECTION;

A locator variable with a TEXT data type has the loc_type field of the locator structure set to SQLTEXT. For a BYTE variable, loc_type is SQLBYTE. For more information on the fields of the locator structure, see "The Fields of the Locator Structure".

Tip: The sqltypes.h header file defines both SQLTEXT and SQLBYTE. Therefore, make sure you include sqltypes.h before you use these constants.

From an ESQL/C program, you can both select and insert simple-large-object data into loc_t host variables. You can also select only portions of a simple-large-object variable with subscripts on the simple-large-object column name. These subscripts can be coded into the statement as shown in the following example:

EXEC SQL declare catcurs cursor for

	select catalog_num, cat_descr[1,10]

	from catalog 

	where manu_code = 'HSK';

EXEC SQL open catcurs;

while (1)

	{

	EXEC SQL fetch catcurs into :cat_num, :cat_descr;
	.

	.

	.

	
	}

Subscripts can also be passed as input parameters as the following code fragment shows:

EXEC SQL prepare slct_id from

	'select catalog_num, cat_descr[?,?] from catalog \

	where catalog_num = ?'

EXEC SQL execute slct_id into :cat_num, :cat_descr

	using :n, :x, :cat_num;

Accessing the Locator Structure

In an ESQL/C program, you use a locator structure to access simple-large-object values. The locator structure is the host variable for TEXT and BYTE columns when they are stored in or retrieved from the database. This structure describes the location of a simple-large-object value for the following two database operations:

When the program inserts the simple large object into the database, the locator structure identifies the source of the simple-large-object data to insert.
When the program selects the simple large object from the database, the locator structure identifies the destination of the simple-large-object data.

The locator.h header file defines the locator structure, called loc_t. Figure 8-1 shows the definition of the loc_t locator structure from the locator.h file.

typedef struct tag_loc_t

    {

    short loc_loctype;       /* USER: type of locator - see below           */

    union                    /* variant on 'loc'                            */

        {

        struct               /* case LOCMEMORY                              */

            {

            long  lc_bufsize;     /* USER: buffer size                      */

            char *lc_buffer;      /* USER: memory buffer to use             */

            char *lc_currdata_p;  /* INTERNAL: current memory buffer        */

            int   lc_mflags;      /* USER/INTERNAL: memory flags            */

                                  /*                      (see below)       */

            } lc_mem;



        struct                    /* cases L0CFNAME & LOCFILE               */

            {

            char *lc_fname;       /* USER: file name                        */

            int   lc_mode;        /* USER: perm. bits used if creating      */

            int   lc_fd;          /* USER: os file descriptior              */

            long  lc_position;    /* INTERNAL: seek position                */

            } lc_file;

        } lc_union;



    long  loc_indicator;          /* USER/SYSTEM: indicator                   */

    long  loc_type;               /* SYSTEM: type of blob                     */

    long  loc_size;               /* USER/SYSTEM: num bytes in blob or -1     */

    int   loc_status;             /* SYSTEM: status return of locator ops     */

    char *loc_user_env;           /* USER: for the user's PRIVATE use         */

    long  loc_xfercount;          /* INTERNAL/SYSTEM: Transfer count          */



    int (*loc_open)();            /* USER: open function                      */

    int (*loc_close)();           /* USER: close function                     */

    int (*loc_read)();            /* USER: read function                      */

    int (*loc_write)();           /* USER: write function                     */

    int   loc_oflags;             /* USER/INTERNAL: see flag definitions below */

    } loc_t;