A memory buffer that the ESQL/C libraries allocate

When you set loc_bufsize to -1, allocates the memory buffer on a fetch or select. uses the malloc() system call to allocate the memory buffer to hold a single simple-large-object value. (If it cannot allocate the buffer, sets the loc_status field to -465 to indicate an error.) When the select (or the first fetch) completes, 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 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, 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() function to free it. Otherwise use the free() system call.

When you set loc_mflags to LOC_ALLOC, handles memory allocation as follows:
  • If the size of the simple-large-object data increases, frees the existing buffer and allocates the necessary memory.

    If this reallocation occurs, 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. 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, 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.

frees the allocated memory when it fetches the next simple-large-object value. Therefore, 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 ids_esqlc_0207.html#ids_esqlc_0207.