The user-defined open function

To define how to prepare the user-defined location for a transfer operation (read or write), you create a C function called a user-defined open function.

Before you begin a transfer of simple-large-object data to or from the database server, IBM® Informix® ESQL/C calls the open function supplied in the loc_open field of the locator structure.

This user-defined open function must receive the following two arguments:

The address of the locator structure, ifx_loc_t *loc_struc, where loc_struc is the name of a locator structure that your user-defined open function declares
The open-mode flags, int oflags, where oflags is a variable that contains the open-mode flag
This flag contains LOC_RONLY if Informix ESQL/C calls the open function to send the simple large object to the database, or LOC_WONLY if Informix ESQL/C calls the function to receive data from the database.

The user-defined open function must return the success code for the open operations as follows:

0: The initialization was successful.
-1: The initialization failed. This return code generates a loc_status (and SQLCODE) error of -452.

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

Figure 1. A sample user-defined open function

open_simple_lo(adloc, oflags)
ifx_loc_t *adloc;
int oflags;
{
   adloc->loc_status = 0;
   adloc->loc_xfercount = 0L;
   if (0 == (oflags & adloc->loc_oflags)) 
      return(-1);
   if (oflags & LOC_RONLY)
      /*** prepare for store to db ***/
   else
      /*** prepare for fetch to program ***/
   return(0);
}