A memory buffer that the ESQL/C libraries allocate
When you set loc_bufsize to -1
,
Informix® ESQL/C allocates
the memory buffer on a fetch or select. Informix®
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, Informix®
ESQL/C sets
the loc_status field to -465
to indicate an
error.) When the select (or the first fetch) completes, Informix®
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 Informix® ESQL/C reallocate a new memory buffer. Leave loc_bufsize to the size of the currently allocated buffer.
If you do not set loc_mflags to LOC_ALLOC after the initial fetch, Informix® 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. If your application runs on a Windows™ operating system and uses the multithreaded library then use the SqlFreeMem() Informix® ESQL/C function to free it. Otherwise use the free() system call.
- If the size of the simple-large-object data increases, Informix®
ESQL/C frees
the existing buffer and allocates the necessary memory.
If this reallocation occurs, Informix® 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. Informix® ESQL/C also updates the loc_bufsize and loc_size field to the size of the fetched simple large object.
- If the size of the data decreases, Informix®
ESQL/C does
not need to reallocate the buffer.
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.
Informix® ESQL/C frees the allocated memory when it fetches the next simple-large-object value. Therefore, Informix® 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 Select a simple large object into memory.