The user-defined read function

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

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

This user-defined read 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 read function uses
  • The address of the buffer to send data to the database server, char *buffer, where buffer is the buffer that your program allocates
  • The number of bytes to be read from the user-defined location, int nread, where nread is a variable that contains the number of bytes

This function must transfer the data from the user-defined location to the character buffer that buffer indicates. Informix ESQL/C might call the function more than once to read a single simple-large-object value from 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 read function. You might want to use the loc_position or loc_currdata_p fields for this purpose. You can also use the loc_xfercount field to track the amount of data that was read.

The user-defined read function must return the success code for the read operation as follows:
>0
The read operation was successful. The return value indicates the number of bytes actually read from the locator structure.
-1
The read operation failed. This return code generates a loc_status (and SQLCODE) error of -454.
The following figure shows a skeleton function of a user-defined read function.
Figure 1: A sample user-defined read function
read_simple_lo(adloc, bufp, ntoread)
ifx_loc_t *adloc;   
char *bufp;
int ntoread;
{
   int ntoxfer;

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

   /*** transfer "ntoread" bytes to *bufp ***/

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