Access the locator structure

In the 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 program sets the field, and the libraries inspect the field.
SYSTEM
The libraries set the field, and the program inspects the field.
INTERNAL
The field is a work area for the libraries, and the program does not need to examine the field.
does not automatically include the locator.h header file in the program. You must include the locator.h header file in any program that defines simple-large-object variables. 
EXEC SQL include locator;