• An open file is one that has already been opened before the program accesses the simple-large-object data. The program provides a file descriptor as the location of the simple-large-object data.
• A named file is one that your program has not yet opened. The program provides a filename as the location of the simple-large-object data.

Figure 8-10
Fields in lc_union.lc_file Structure Used for Simple Large Objects Located in Files

Field	Data Type	Description
lc_fname	char *	The address of the pathname string that contains the file for the simple-large-object data. The program sets this field when it uses named files for simple-large-object locations.
lc_mode	int	The permission bits to use to create a new file. This value is the third argument passed to the system open() function. For valid values of lc_mode, refer to your system documentation.
lc_fd	int	The file descriptor of the file that contains the simple-large-object data. The program sets this field when it uses open files.
lc_position	long	The current seek position within the opened file. This is an internal field and must not be modified by the ESQL/C program.

The locator.h file provides the following macro shortcuts to use when you access simple large objects stored in files:

#define loc_fname       lc_union.lc_file.lc_fname

#define loc_fd          lc_union.lc_file.lc_fd

#define loc_position    lc_union.lc_file.lc_position

Tip: Informix recommends that you use these shortcut names when you access the locator structure. The shortcut names improve code readability and reduce coding errors. This manual uses these shortcut names when it refers to the lc_fname, lc_fd, and lc_position fields of the lc_union.lc_file structure.

• LOC_RONLY is a mask for read-only mode. Use this value when you insert a simple large object into a file.
• LOC_WONLY is a mask for write-only mode. Use this value when you select a simple large object into a file and you want each selected simple large object to write over any existing data.
• LOC_APPEND is a mask for write mode. Use this value when you select a simple large object into a file and you want to append the value to the end of the file.

Locating Simple Large Objects in Open Files

EXEC SQL BEGIN DECLARE SECTION;

    loc_t my_simple_lo;

EXEC SQL END DECLARE SECTION;
.

.

.


my_simple_lo.loc_loctype = LOCFILE; 

The demo directory contains the following two sample ESQL/C programs that demonstrate how to handle simple-large-object data located in an open file:

• The getcd_of.ec program selects a simple large object into an open file.
• The updcd_of.ec program inserts a simple large object from an open file.

getcd_of mystores

Selecting a Simple Large Object into an Open File

	EXEC SQL BEGIN DECLARE SECTION;

		long cat_num;

		loc_t cat_descr;

	EXEC SQL END DECLARE SECTION;
	.

	.

	.


	if((fd = open(descfl, O_WRONLY)) < 0)

		{

		printf("\nCan't open file: %s, errno: %d\n", descfl, errno);

		EXEC SQL disconnect current;

		printf("GETCD_OF Sample Program over.\n\n"):

        exit(1);

		}

    /*

     * Prepare locator structure for select of cat_descr

     */

	cat_descr.loc_loctype = LOCFILE;           /* set loctype for open file */

	cat_descr.loc_fd = fd;                     /* load the file descriptor */

	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) != 100)    /* if not found */

		printf("\nCatalog number %ld not found in catalog table\n", 

			cat_num);

	else

		{

		if(ret < 0)

			{
			.

			.

			.


			exit(1);

			}

		}

To prepare the locator structure for the SELECT statement, the getcd_of program sets the cat_descr locator structure fields as follows:

• The loc_loctype field is set to LOCFILE to tell ESQL/C to place the text for the cat_descr column in the open file.
• The loc_fd field is set to the fd file descriptor to identify the open file.
• The loc_oflags field is set to LOC_APPEND to specify that the data is to be appended to any data that already exists in the file.

cat_descr.lc_union.lc_file.lc_fd

After ESQL/C writes data to an open file, it sets the following fields of the locator structure:

• The loc_size field contains the number of bytes written to the open 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 page 8-20.

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

.

.

EXEC SQL BEGIN DECLARE SECTION;

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

The updcd_of program is then able to perform the database update. After ESQL/C reads data from the open file and sends it to the database server, ESQL/C updates the loc_size field with the number of bytes read from the open file and sent to the database server. 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 page 8-20.

Locating Simple Large Objects in Named Files

EXEC SQL BEGIN DECLARE SECTION;

    loc_t my_simple_lo;

EXEC SQL END DECLARE SECTION;
.

.

.


my_simple_lo.loc_loctype = LOCFNAME; 

To open a named file, ESQL/C opens the file named in the loc_fname field with the mode flags that the loc_oflags field specifies. If this file does not exist, ESQL/C creates it. ESQL/C then puts the file descriptor of the open file in the loc_fd field and proceeds as if your program opened the file. If ESQL/C cannot open this file, it sets the loc_status field (and SQLCODE) to -461. When the transfer is complete, ESQL/C closes the file, which releases the file descriptor in the loc_fd field.

The demo directory contains the following two sample ESQL/C programs that demonstrate how to handle simple-large-object data located in a named file:

• The getcd_nf.ec program selects a simple large object into a named file.
• The updcd_nf.ec program inserts a simple large object from a named file.

getcd_of mystores

Selecting a Simple Large Object into a Named File

Figure 8-13 shows a code excerpt from the getcd_nf sample program.

EXEC SQL BEGIN DECLARE SECTION; long 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"); }

Figure 8-13 Code Excerpt from the getcd_nf Sample Program

The program sets the cat_descr locator structure fields as follows:

• The loc_loctype field contains LOCFNAME to tell 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 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 ESQL/C to append selected data to the existing file.

• The loc_size field contains the number of bytes written to the file. If the ESQL/C program fetches a null (or empty) simple-large-object column into a named file that already 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 page 8-20.

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

EXEC SQL BEGIN DECLARE SECTION;

	long cat_num;

	loc_t cat_descr;

EXEC SQL END DECLARE SECTION;
.

.

.


	cat_descr.loc_loctype = LOCMEMORY;         /* set loctype for in memory */

	cat_descr.loc_bufsize = -1;                /* let server get memory */

	EXEC SQL select catalog_num, cat_descr     /* verify catalog number */

		 into :cat_num, :cat_descr from catalog

		where catalog_num = :cat_num;



	/* if error,display and quit */

	if ((ret = exp_chk2("SELECT", WARNNOTIFY)) == 100) 

		{

		printf("\nCatalog number %ld not found in catalog table\n",

			cat_num);

		EXEC SQL disconnect current;

		printf("UPDCD_NF Sample Program over.\n\n");

		exit(1);

		}

	if(ret<0)

		{

		EXEC SQL disconnect current;

		printf("UPDCD_NF Sample Program over.\n\n");

		exit(1);

		}

	prdesc();                                   /* print current cat_descr */



	/* Update? */

	ans[0] = '  ';

	while((ans[0] = LCASE(ans[0]))  != 'y' && ans[0]  != 'n')

		{

		printf("Update this description? (y/n) ... ");

		scanf("%1s", ans);

		}

	if(ans[0] == 'y')

		{

		cat_descr.loc_loctype = LOCFNAME;       /* set type to named file */

		cat_descr.loc_fname = descfl;           /* supply file name */

		cat_descr.loc_oflags = LOC_RONLY;       /* set file-open mode (read) */

		cat_descr.loc_size = -1;                /* set size to size of file */

		EXEC SQL update catalog

			set cat_descr = :cat_descr           /* update cat_descr column */

			where catalog_num = :cat_num;

		if(exp_chk2("UPDATE", WARNNOTIFY) < 0)   /* check status */

			{

			EXEC SQL disconnect current;

			printf("UPDCD_NF Sample Program over.\n\n");

			exit(1);

			}

		printf("Update complete.\n");

		}

The updcd_nf program in Figure 8-14 first performs a SELECT statement on the catalog table for a catalog number that the user enters in response to a prompt. The SELECT statement returns the catalog_num and cat_descr columns. The prdesc() function (page 8-66) displays the current content of cat_descr.

The program then asks whether the user wants to update this description. If the user answers yes (ans[0] == 'y'), the updcd_nf program prepares the locator structure as follows to update the cat_descr column from text in a file that the user has specified:

• The cat_descr.loc_loctype field is set to LOCFNAME to indicate that the source of the update text is a named file.
• The cat_descr.loc_fname field is set to descfl, the name of the file that contains the simple-large-object data.
• The cat_descr.loc_oflags field is set to LOC_RONLY to tell ESQL/C to open the file in read-only mode.
• The cat_descr.loc_size field is set to -1 to tell ESQL/C to transfer the simple large object all at once, not to transfer it in smaller pieces, one piece at a time. You can also set the loc_oflags field to the LOC_USEALL mask to perform this operation.

After ESQL/C reads data from the named file and sends it to the database server, ESQL/C updates the loc_size field with the number of bytes read from the named file and sent to the database server. 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. See page 8-20 for possible causes of the error.