INFORMIX
Informix-ESQL/C Programmer's Manual
Chapter 8: Working with Simple Large Objects
Home Contents Index Master Index New Book

Locating Simple Large Objects in Memory

To have ESQL/C locate the TEXT or BYTE data in primary memory, set the loc_loctype field of the locator structure to LOCMEMORY as follows:

When you use memory as a simple-large-object location, a locator structure uses the lc_mem structure of the lc_union structure. Figure 8-4 summarizes the lc_union.lc_mem fields.

Figure 8-4
Fields in lc_union.lc_mem Structure Used for Simple Large Objects Located in Memory

Field Data Type Description

lc_bufsize

long

The size, in bytes, of the buffer to which the lc_buffer field points. For more information, see "Allocating the Memory Buffer".

lc_buffer

char *

The address of the buffer to hold the simple large-object value. Your ESQL/C program must allocate the space for this buffer and store its address here in lc_buffer. For more information, see "Allocating the Memory Buffer".

lc_currdata_p

char *

The address of the system buffer. This is an internal field and must not be modified by the ESQL/C program.

lc_mflags

int

The flags to use when you allocate memory.

The locator.h file provides the following macro shortcuts to use when you access fields in lc_union.lc_mem:

Tip: Informix recommends that you use these shortcut names when you access the locator structure. The shortcut names improve code readability and reduce coding errors. This manual uses these shortcut names when it refers to the lc_bufsize, lc_buffer, lc_currdata_p, and lc_mflags fields of the lc_union.lc_mem structure.
The demo directory contains the following two sample ESQL/C programs that demonstrate how to handle simple-large-object data located in an open file:

These programs assume the stores7 database as the default database for the simple-large-object data. The user can specify another database (on the default database server) as a command-line argument.

The getcd_me.ec and updcd_me.ec programs are briefly explained on page 8-15 and page 8-17, respectively.

Allocating the Memory Buffer

When your program selects simple-large-object data into memory, ESQL/C uses a memory buffer. Before your program fetches TEXT or BYTE data, you must set the loc_bufsize (lc_union.lc_mem.lc_bufsize) field as follows to indicate how ESQL/C allocates this memory buffer:

Warning: When you locate simple large objects in memory, you must always set loc_mflags (lc_union.lc_mem.lc_mflags) and loc_oflags to 0 (zero) initially.

A Memory Buffer That the ESQL/C Libraries Allocate

 When you set loc_bufsize to -1, ESQL/C allocates the memory buffer on a fetch or select. ESQL/C uses the malloc() system call to allocate the memory buffer to hold a single simple-large-object value. (If it cannot allocate the buffer, ESQL/C sets the loc_status field to -465 to indicate an error.) When the select (or the first fetch) completes, ESQL/C sets loc_buffer to the address of the buffer and both loc_bufsize and loc_size to the size of the fetched simple large object to update the locator structure.

To fetch subsequent simple-large-objects whose data is of larger or smaller size, set loc_mflags to the LOC_ALLOC constant (that locator.h defines) to request that ESQL/C reallocate a new memory buffer. Leave loc_bufsize to the size of the currently allocated buffer.

Warning: If you do not set loc_mflags to LOC_ALLOC after the initial fetch, ESQL/C does not release the memory it has allocated for the loc_buffer buffer. Instead, it allocates a new buffer for subsequent fetches. This situation can cause your program size to grow for each fetch unless you explicitly free the memory allocated to each loc_buffer buffer with the free() system call.
When you set loc_mflags to LOC_ALLOC, ESQL/C handles memory allocation as follows:

    If this reallocation occurs, ESQL/C alters the memory address at which it stores simple-large-object data. Therefore, if you reference the address in your programs, your program logic must account for the address change. ESQL/C also updates the loc_bufsize and loc_size field to the size of the fetched simple large object.

    After the fetch, the loc_size field indicates the size of the fetched simple large object while the loc_bufsize field still contains the size of the allocated buffer.

ESQL/C frees the allocated memory when it fetches the next simple-large-object value. Therefore, ESQL/C does not explicitly free the last simple-large-object value fetched until your program disconnects from the database server.

For an example in which loc_bufsize is set to -1, see "Selecting a Simple Large Object into Memory".

A Memory Buffer That the Program Allocates

If you wish to handle your own memory allocation for simple large objects, use the malloc() system call to allocate the memory and then set the following fields in the locator structure:

If the fetched data does not fit in the allocated buffer, the ESQL/C libraries set loc_status (and SQLCODE) to a negative value (-451) and put the actual size of the data in loc_indicator. If the fetched data does fit, ESQL/C sets loc_size to the size of the fetched data.

Important: When you allocate your own memory buffer, also free the memory when you are finished selecting or inserting simple large objects. ESQL/C does not free this memory because it has no way to determine when you are finished with the memory. Because you have allocated the memory with malloc(), you can use the free() system call to free the memory.

Selecting a Simple Large Object into Memory

The getcd_me sample program from the demo directory shows how to select a simple large object from the database into memory. Figure 8-5 shows a code excerpt that selects the cat_descr TEXT column of the catalog table into memory and then displays it.

Figure 8-5
Code Excerpt from the getcd_me Sample Program

The program sets the cat_descr locator structure fields as follows:

After the SELECT or FETCH statement, the locator structure contains the following information:

The program in Figure 8-5 calls prdesc() to display the text that the SELECT statement returned. For a description of the prdesc() function, see "Guide to the prdesc.c File". If this program were to select a second simple large object, it would need to set the loc_mflags to the LOC_ALLOC constant before the second SELECT statement to prevent memory leaks.

The program in Figure 8-5 displays the cat_descr column for a catalog number that the user enters. Figure 8-6 shows the user input and the output that results from the cat_descr column of the stores7 database.

Figure 8-6
Sample Output from the getcd_me Sample Program

Inserting a Simple Large Object from Memory

The updcd_me sample program from the demo directory shows how to insert a simple large object from memory into the database. The program updates the cat_descr TEXT column of the catalog table from a memory buffer that contains text that the user enters. Figure 8-7 shows sample output as the user updates the cat_descr column of the stores7 database.

Figure 8-7
Sample Output from the updcd_me Sample Program

Figure 8-8 shows a code excerpt that illustrates how the updcd_me program uses the locator structure to update the cat_descr column from the text that is stored in memory.

Figure 8-8
Code Excerpt from the updcd_me Sample Program

The program sets the cat_descr locator structure fields as follows:

If you insert a null simple-large-object value, your program also needs to set the loc_indicator field to -1.

Figure 8-9 shows a code excerpt that illustrates how to use a locator structure in an INSERT statement.

Figure 8-9
Sample INSERT Operation from Primary Memory

After the UPDATE or INSERT statement, ESQL/C updates the loc_size field with the number of bytes read from the memory buffer and sent to the database server. It also sets the loc_status field to indicate the status of the operation: 0 for success and a negative value if an error has occurred. For information about possible errors, see "Allocating the Memory Buffer".



Informix-ESQL/C Programmer's Manual, version 9.1
Copyright © 1998, Informix Software, Inc. All rights reserved.