Select a simple large object into a named file

The getcd_nf sample program from the demo directory shows how to select a simple large object from the database into a named file. The following code excerpt prompts the user to enter a catalog number for the catalog table and the name of the file to which the program writes the contents of the cat_descr column for that row. The program stores the name of the file in the descfl array. It then executes a SELECT statement to read the cat_descr TEXT column from the catalog table and write it to a file that the user specifies in response to a prompt.

The following figure shows a code excerpt from the getcd_nf sample program.

Figure 1. Code excerpt from the getcd_nf sample program

EXEC SQL BEGIN DECLARE SECTION;
   char db_name[30];
   mlong cat_num;
   loc_t cat_descr;
EXEC SQL END DECLARE SECTION; 
⋮

      printf("\nEnter a catalog number: ");    /* prompt for catalog number */
      getans(ans, 6);
      if(rstol(ans, &cat_num))                /* cat_num string too long */
         {
         printf("\tCannot convert catalog number '%s' to integer\n", ans);
         continue;
         }
      while(1)
         {
         printf("Enter the name of the file to receive the description: ");
         if(!getans(ans, 15))
            continue;
         break;
         }
      strcpy(descfl, ans);
      break;
      }

   /*
     *  Prepare locator structure for select of cat_descr
    */
   cat_descr.loc_loctype = LOCFNAME;           /* set loctype for in memory */
   cat_descr.loc_fname = descfl;              /* load the addr of file name */
   cat_descr.loc_oflags = LOC_APPEND;          /* set loc_oflags to append */
   EXEC SQL select catalog_num, cat_descr       /* verify catalog number */
      into :cat_num, :cat_descr from catalog
      where catalog_num = :cat_num;
   if(exp_chk2("SELECT", WARNNOTIFY)  !=  0 )   /* if error, display and quit */
      printf("\nSelect for catalog number %ld failed\n", cat_num);

   EXEC SQL disconnect current;
   printf("\nGETCD_NF Sample Program over.\n\n");
}

The program sets the cat_descr locator structure fields as follows:

The loc_loctype field contains LOCFNAME to tell Informix® ESQL/C to place the text for the cat_descr column in a named file.
The loc_fname field is the address of the descfl array to tell Informix ESQL/C to write the contents of the cat_descr column to the file named in descfl.
The loc_oflags field, the file-open mode flags, is set to LOC_APPEND to tell Informix ESQL/C to append selected data to the existing file.

The getcd_nf program then executes the SELECT statement to retrieve the row. After Informix ESQL/C writes data to the named file, it sets the following fields of the locator structure:

The loc_size field contains the number of bytes written to the file. If the Informix ESQL/C program fetches a null (or empty) simple-large-object column into a named file that exists, it truncates the file.
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 possible causes of the error, see Error returns in loc_status.