The user-defined write function

To define how to write to the user-defined location, you create a C function called a user-defined write function.

When IBM® Informix® ESQL/C receives data from the database server, it stores this data in a character buffer. To transfer the data from the buffer to a user-defined location, Informix ESQL/C calls the user-defined write function. Your Informix ESQL/C program must supply the address of your user-defined write function in the loc_write field of the locator structure.

This user-defined write function must receive the following three arguments:

The address of the locator structure, ifx_loc_t *loc_struc, where loc_struc is a locator structure that your user-defined write function uses
The address of the buffer to receive the data from the database server, char *buffer, where buffer is the buffer that your program allocates
The number of bytes to be written to the user-defined location, int nwrite, where nwrite is a variable that contains the number of bytes

The user-defined write function must transfer the data from the character buffer that buffer indicates to the user-defined location. Informix ESQL/C might call the function more than once to write a single simple-large-object value to the user-defined location. Each call receives the address and length of a segment of data. Track the current seek position of the user-defined location in your user-defined write function. You might want to use the loc_position or loc_currdata_p field for this purpose. You can also use the loc_xfercount field to track the amount of data that was written.

The user-defined write function must return the success code for the write operation as follows:

>0: The write operation was successful. The return value indicates the number of bytes written to the user-defined location
-1: The write operation failed. This return code generates a loc_status (and SQLCODE) error of -455.

The following figure shows a skeleton function of a user-defined write function.

Figure 1. A Sample User-Defined Write Function

write_simple_lo(adloc, bufp, ntowrite)
ifx_loc_t *adloc;
char *bufp;
int ntowrite;
{
    int xtoxfer;

   ntoxfer = ntowrite;
   if (adloc->loc_size != -1)
      ntoxfer = min(ntowrite,
         (adloc->loc_size) - (adloc->loc_xfercount));

   /*** transfer "ntowrite" bytes from *bufp ***/

   adloc->loc_xfercount += ntoxfer;
   return(ntoxfer);
}