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