Writing TEXT values

uses the loc_t locator structure to read simple large objects from and write simple large objects to the database server.

The loc_type field of this structure indicates the data type of the simple large object that the structure describes. When the client and database code sets are the same (no code-set conversion), the client application does not need to set the loc_type field explicitly because the database server can determine the simple large object data type implicitly. The database server assumes character data in the TEXT data type and noncharacter data in the BYTE data type.

If the client and database code sets are different and convertible, however, the client application must know the data type of the simple large object in order to determine whether to perform code-set conversion on the data.

Before the client application inserts a simple large object in the database, it must explicitly set the loc_type field of the simple large object:
  • For a TEXT value, the client application must set the loc_type field to SQLTEXT before the INSERT statement. The client performs code-set conversion on TEXT data before it sends this data to the database for insertion.
  • For a BYTE value, the client application must set the loc_type field to SQLBYTES before the INSERT statement. The client does not perform code-set conversion on BYTE data before it sends this data to the database for insertion.
Important: The sqltypes.h header file defines the data type constants SQLTEXT and SQLBYTES. To use these constants, you must include this header file in your source file.

Your source code does not need to set loc_type before it reads simple-large-object data from a database. The database server obtains the data type of the simple large object from the database and sends this data type to the client with the data.

If you set loc_bufsize to -1, allocates memory to hold a single simple large object. It stores the address of this memory buffer in the loc_buffer field of the loc_t structure. If the client application performs code-set conversion on TEXT data that the database server retrieves, handles any possible data expansion as follows:
  1. Frees the existing memory that the loc_buffer field references
  2. Reallocates a memory buffer that is large enough to store the expanded TEXT data
  3. Assigns the address of this new buffer to the loc_buffer field
  4. Assigns the size of the new memory buffer to the loc_bufsize field

If this reallocation occurs, changes the memory address at which it stores the TEXT data. If your program references this address, the program must account for the address change.

does not need to reallocate memory for the TEXT data if code-set conversion does not expand the TEXT data or if it condenses the data. In either of these cases, the loc_buffer field remains unchanged, and the loc_bufsize field contains the size of the buffer that the loc_buffer field references.