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.

When you set loc_mflags to LOC_ALLOC, Informix ESQL/C handles memory allocation as follows:
  • 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.