Access the locator structure

In the Informix® 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.
    It is recommended that you initialize the data structure before using it, as in the following example:
    byfill(&blob1, sizeof(loc_t), 0); 
where blob1 is declared as -- 
EXEC SQL BEGIN DECLARE SECTION; 
loc_t blob1; 
EXEC SQL END DECLARE SECTION;

    This ensures that all variables of the data structure have been initialized and will avoid inconsistencies

  • 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. The following figure shows the definition of the loc_t locator structure from the locator.h file.
Figure 1: Declaration of loc_t in the locator.h header file
typedef struct tag_loc_t
   {
   int2 loc_loctype;          /* USER: type of locator - see below      */
   union                       /* variant on 'loc'                       */
      {
      struct                   /* case LOCMEMORY                         */
         {
         int4  lc_bufsize;     /* USER: buffer size                      */
         char *lc_buffer;      /* USER: memory buffer to use             */
         char *lc_currdata_p;  /* INTERNAL: current memory buffer        */
         mint   lc_mflags;      /* USER/INTERNAL: memory flags            */
                               /*                      (see below)       */
         } lc_mem;

      struct                   /* cases L0CFNAME & LOCFILE               */
         {
         char *lc_fname;       /* USER: file name                        */
         mint   lc_mode;        /* USER: perm. bits used if creating      */
         mint   lc_fd;          /* USER: os file descriptior              */
         int4  lc_position;    /* INTERNAL: seek position                */
         } lc_file;
      } lc_union;

   int4  loc_indicator;        /* USER/SYSTEM: indicator                   */
   int4  loc_type;              /* SYSTEM: type of blob                     */
   int4  loc_size;              /* USER/SYSTEM: num bytes in blob or -1     */
   mint  loc_status;            /* SYSTEM: status return of locator ops     */
   char *loc_user_env;          /* USER: for the user's PRIVATE use         */
   int4  loc_xfercount;         /* INTERNAL/SYSTEM: Transfer count          */
           /* USER: open function                      */
   mint (*loc_open)(struct tag_loc_t *loc, mint flag, mint bsize);
;          /* USER: close function                     */
   mint (*loc_close)(struct tag_loc_t *loc)
;           /* USER: read function                      */
   mint (*loc_read)(struct tag_loc_t *loc, char *buffer, mint buflen)
;          /* USER: write function                     */
   mint (*loc_write)(struct tag_loc_t *loc, char *buffer, mint buflen)
            /* USER/INTERNAL: see flag definitions below */
   mint   loc_oflags;
   } loc_t;
In Declaration of loc_t in the locator.h header file, the following comments in the locator.h file indicate how the fields are used in the locator structure.
USER
The Informix ESQL/C program sets the field, and the Informix ESQL/C libraries inspect the field.
SYSTEM
The Informix ESQL/C libraries set the field, and the Informix ESQL/C program inspects the field.
INTERNAL
The field is a work area for the Informix ESQL/C libraries, and the Informix ESQL/C program does not need to examine the field.
Informix ESQL/C does not automatically include the locator.h header file in the Informix ESQL/C program. You must include the locator.h header file in any Informix ESQL/C program that defines simple-large-object variables. 
EXEC SQL include locator;