Select 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.

The following figure shows a code excerpt that selects the cat_descr TEXT column of the catalog table into memory and then displays it.

Figure 1. Code excerpt from the getcd_me sample program

cat_descr.loc_loctype = LOCMEMORY;      /* set loctype for in memory */
cat_descr.loc_bufsize = -1;             /* let db get buffer */
cat_descr.loc_oflags = 0;               /* clear loc_oflags */
cat_descr.loc_mflags = 0;               /* set loc_mflags to 0 */
EXEC SQL select catalog_num, cat_descr  /* look up catalog number */
   into :cat_num, :cat_descr from catalog
   where catalog_num = :cat_num;
if((ret = exp_chk2("SELECT", WARNNOTIFY)) == 100)     /* if not found */
   {
   printf("\nCatalog number %ld not found in catalog table\n", 
      cat_num);
   if(!more_to_do())                         /* More to do? */
        break;                          /* no, terminate loop */
    else
        continue;                       /* yes */
   }
if(ret < 0)
   {
   printf("\nSelect for catalog number %ld failed\n", cat_num);
   EXEC SQL disconnect current;
   printf("GETCD_ME Sample Program over.\n\n");
   exit(1);
   }
prdesc();                               /* if found, print cat_descr */

The program sets the cat_descr locator structure fields as follows:

The loc_loctype field is set to LOCMEMORY so that Informix® ESQL/C returns the cat_descr text in a memory buffer.
The loc_bufsize field is set to -1 to have Informix ESQL/C allocate the memory for the buffer. For more information, see A memory buffer that the ESQL/C libraries allocate.
The loc_oflags field is set to 0 because the program does not use a file for the simple large object.
You must always set the loc_mflags field to 0 when you locate a simple large object in memory.

After the SELECT or FETCH statement, the locator structure contains the following information:

The loc_buffer field contains the address of the memory buffer.
The loc_bufsize field contains the size of the loc_buffer buffer. This is the total amount of memory allocated for simple-large-object storage.
The loc_size field contains the number of bytes of simple-large-object data in loc_buffer.
The loc_indicator field contains -1 if the selected simple-large-object value is null.
The loc_status field contains the status of the operation: 0 for success and a negative value if an error has occurred. For information about possible errors, see Allocate the memory buffer.

The program excerpt in Figure 1 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 selects 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. The following figure shows the user input and the output from the cat_descr column of the stores7 demonstration database.

Figure 2. Sample output from the getcd_me sample program

GETCD_ME Sample ESQL Program running.

Connected to stores7

This program requires you to enter a catalog number from the catalog
table. For example: '10001'. It then displays the content of the
cat_descr column for that catalog row. The cat_descr value is stored
in memory.

Enter a catalog number: 10004
Description for 10004:

Jackie Robinson signature glove. Highest professional quality, 
used by National League.

**** More? (y/n) …