|
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 7-4 summarizes the lc_union.lc_mem fields.
Figure 7-4
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 and updcd_me programs are briefly explained on page 7-15 and page 7-17, respectively.
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.
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:
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.
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 7-5 shows a code excerpt that selects the cat_descr TEXT column of the catalog table into memory and then displays it.
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 excerpt in Figure 7-5 on page 7-15 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 excerpt also displays the cat_descr column for a catalog number that the user enters. Figure 7-6 shows the user input and the output from the cat_descr column of the stores7 demonstration database.
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 7-7 shows sample output as the user updates the cat_descr column of the stores7 database.
Figure 7-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.
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 7-9 shows a code excerpt that illustrates how to use a locator structure in an INSERT statement.
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.