Insert a simple large object from an open file

The updcd_of sample program from the demo directory shows how to insert a simple large object from an open file into the database. The program updates the cat_descr TEXT column of the catalog table from an open file that contains a series of records; each consists of a catalog number and the text to update the corresponding cat_descr column. The program assumes that this input file has the following format:

\10001\
Dark brown leather first baseman's mitt.  Specify right-handed or 
left-handed.

\10002\
Babe Ruth signature glove. Black leather. Infield/outfield style. 
Specify right- or left-handed.
⋮

The following figure shows a code excerpt that illustrates how to use the locator structure to update the cat_descr column of the catalog table from an open file.

Figure 1. Code excerpt from the updcd_of sample program

EXEC SQL BEGIN DECLARE SECTION;
   mlong cat_num;
   loc_t cat_descr;
EXEC SQL END DECLARE SECTION;
⋮

if ((fd = open(descfl, O_RDONLY)) < 0) /* open input file */
   {
   
⋮

   }
while(getcat_num(fd, line, sizeof(line)))   /* get cat_num line from file */
   {
   
⋮

   printf("\nReading catalog number %ld from file...\n", cat_num);
   flpos = lseek(fd, 0L, 1);
   length = getdesc_len(fd);
   flpos = lseek(fd, flpos, 0);

   /* lookup cat_num in catalog table */
   EXEC SQL select catalog_num 
      into :cat_num 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.", 
         cat_num);
      
⋮

      }
   /*if found */
   cat_descr.loc_loctype = LOCFILE;        /* update from open file */
   cat_descr.loc_fd = fd;                  /* load file descriptor */
   cat_descr.loc_oflags = LOC_RONLY;       /* set file-open mode (read) */
   cat_descr.loc_size = length;            /* set size of simple large obj */

   /* update cat_descr column of catalog table */
   EXEC SQL update catalog set cat_descr = :cat_descr
      where catalog_num = :cat_num;
   if(exp_chk2("UPDATE", WARNNOTIFY) < 0)
      {
      EXEC SQL disconnect current;
      printf("UPDCD_OF Sample Program over.\n\n");
      exit(1);
      }
   printf("Update complete.\n");
   }

The updcd_of program opens the input file (descfl) that the user specified in response to a prompt, calls the getcat_num() function to read a catalog number from the file, and then calls the getdesc_len() function to determine the length of the text for the update to the cat_descr column. The program performs a SELECT statement to verify that the catalog number exists in the catalog table.

If this number exists, the updcd_of program prepares the locator structure as follows to update cat_descr from the text in the open file:

The loc_loctype field is set to LOCFILE to tell IBM® Informix® ESQL/C that the cat_descr column is to be updated from an open file.
The loc_fd field is set to fd, the file descriptor for the open-input file.
The loc_oflags field is set to LOC_RONLY, the file-open mode flag for read-only mode.
The loc_size field is set to length, the length of the incoming text for cat_descr.

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

The updcd_of program is then able to perform the database update. After Informix ESQL/C reads data from the open file and sends it to the database server, Informix ESQL/C updates the loc_size field with the number of bytes read from the open file and sent to the database server. Informix ESQL/C 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 possible causes of the error, see Error returns in loc_status.