Insert a simple large object from memory

The updcd_me sample program from the demo directory shows how to insert a simple large object from memory into the database.

The program updates the cat_descr TEXT column of the catalog table from a memory buffer that contains text that the user enters. The following figure shows sample output as the user updates the cat_descr column of the stores7 database.

Figure 1. Sample output from the updcd_me sample program

Enter catalog number: 10004
Description for 10004:

Jackie Robinson signature ball. Highest professional quality, 
used by National League.
   
Update this description? (y/n) …y

Enter description (max 255 chars):and press RETURN
Jackie Robinson home run ball, signed, 1955.

*** Update complete.
**** More?(y/n).... n

The following figure shows a code excerpt that illustrates how the updcd_me program uses the locator structure to update the cat_descr column from the text that is stored in memory.

Figure 2. Code excerpt from the updcd_me sample program

/* Update? */
   ans[0] = ' ';
   while((ans[0] = LCASE(ans[0])) != 'y' && ans[0] != 'n')
      {
      printf("\nUpdate this description? (y/n) …"); 
      getans(ans, 1);
      }
   if(ans[0] == 'y')                       /* if yes */
      {
      printf("Enter description (max of %d chars) and press RETURN\n", 
         BUFFSZ - 1);
      /* Enter description */
      getans(ans, BUFFSZ - 1);
      cat_descr.loc_loctype = LOCMEMORY;  /* set loctype for in memory */
      cat_descr.loc_buffer = ans;         /* set buffer addr */
      cat_descr.loc_bufsize = BUFFSZ;     /* set buffer size */
      /* set size of data *
      cat_descr.loc_size = strlen(ans);
      /* Update */
      EXEC SQL update catalog
         set cat_descr =:cat_descr
         where catalog_num = :cat_num;
      
⋮

      }

The program sets the cat_descr locator structure fields as follows:

The loc_loctype field is set to LOCMEMORY so that IBM® Informix® ESQL/C reads the cat_descr text from a memory buffer.
The loc_buffer field is set to ans, the address of the memory buffer that holds the simple-large-object value to be inserted.
The loc_bufsize field is set to BUFFSZ, the size of the allocated ans memory buffer.
The loc_size field is set to strlen(ans) + 1, the number of bytes in the memory buffer that currently holds the new simple-large-object value.

If you insert a null simple-large-object value, your program also needs to set the loc_indicator field to -1.

The following figure shows a code excerpt that illustrates how to use a locator structure in an INSERT statement.

Figure 3. Sample INSERT operation from primary memory

char photo_buf[BUFFSZ];

EXEC SQL BEGIN DECLARE SECTION;
   char name[20];
   loc_t photo;
EXEC SQL END DECLARE SECTION;

photo.loc_loctype = LOCMEMORY; /* Photo resides in memory */
photo.loc_buffer = photo_buf; /* pointer to where it is */
photo.loc_size = BUFFSZ - 1;                   /* length of image*/

EXEC SQL insert into employee (name, badge_pic) 
      values (:name, :photo);

After the UPDATE or INSERT statement, Informix ESQL/C updates the loc_size field with the number of bytes read from the memory buffer and sent to the database server. It also sets the loc_status field to indicate 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.