Using xfodbcusr.c as a template to create user-defined data routines

To make creating user-defined data routines convenient, we’ve included a template file, xfodbcusr.c, in the xfODBC installation. This file has the source code, written in C, for the file that the xfODBC driver calls for user-defined data routines.

On Windows, this file is a DLL, xfodbcusr.dll.
On Unix, this file is a shared library, XFODBCUSR.so.
On OpenVMS, this file is a shared image, xfodbcusr_so.exe.

Until you overwrite it, this DLL, shared library, or shared image simply returns a value of 1, which tells the xfODBC driver that there’s no data manipulation to be done. (If, in Repository, you’ve changed the user-defined fields from alpha to numeric or date, the return value of 1 will indicate an error.) However, if you want to add user-defined data routines, you can do so by adding the code for these routines to xfodbcusr.c and then creating a new version of the DLL, shared library, or shared image from this source file. The following section describes the routines included in xfodbcusr.c. To see an example of how xfodbcusr.c can be used to create user-defined data routines, see Tutorial: Using xfodbcusr.c as an example.

Functions in xfodbcusr.c

xfodbcusr.c includes the four functions listed below. Unless you’ve modified xfodbcusr.c, these functions already have code that’s been commented out by #ifdef statements. (You’ll need this code to complete the example in Tutorial: Using xfodbcusr.c as an example.) To add your own data-manipulation routines, replace this code with the routines you’ve written.

user_to_alpha()

Code added to this function manipulates alpha user type field data as it’s read from a database.

int user_to_alpha(char *tablename, char *columnname, char *userstr, 
    char *recdata, char *indata, int inlen, int maxoutlen, char *outdata, 
    int *outlen);

user_to_number()

Code added to this function manipulates numeric and date user type field data as it’s read from a database.

int user_to_number(char *tablename, char *columnname, char *userstr, 
    char *recdata, char *indata, int inlen, char *outdata);

alpha_to_user()

Code added to this function manipulates alpha user type field data as it’s written to a database.

int alpha_to_user(char *tablename, char *columnname, char *userstr, 
    char *recdata, char *indata, int inlen, int maxoutlen, char *outdata, 
    int *outlen);

number_to_user()

Code added to this function manipulates numeric and date user type field data as it’s written to a database.

int number_to_user(char *tablename, char *columnname, char *userstr, 
    char *recdata, char *indata, char *outdata);

Arguments

tablename

The name of the table. (null-terminated string)

columnname

The name of the column. (null-terminated string)

userstr

The string from the User data field in a Repository field definition. (null-terminated string)

recdata

The full record. This is passed so the routine can use other values in the record.

indata

Input data string. This is the string that the routine will convert.

For user_to_alpha(), indata is an alpha string.
For user_to_number(), the format of indata is determined by the format of the user-defined field in your system catalog.
For alpha_to_user(), indata is an alpha string.
For number_to_user(), indata is formatted as a 28.10 DBL zoned decimal for user-defined numeric fields and is formatted as a YYYYMMDD date for user-defined date fields.

inlen

The length of the input data string.

maxoutlen

Maximum output data length. Not currently used.

outdata

Output data string. This is the string produced by the routine.

For alpha_to_user() and number_to_user(), your routine determines the format of outdata.
For user_to_alpha(), outdata must be formatted as an alpha string.
For user_to_number(), if the string is from a user-defined numeric field, outdata must be formatted as a 28.10 DBL zoned decimal. If the string is from a user-defined date field, outdata must be formatted as a YYYYMMDD date.

outlen

Output data string length. Not currently used.

Return values

The functions in xfodbcusr.c return these values:

> 0 = Instructs the driver not to use outdata. If the data is from a numeric or date field, a number greater than zero indicates an error (as does any number other than zero).

0 = Instructs the driver to use outdata.

< 0 = Indicates that there has been a data conversion error. Note that the application that’s accessing the data may not display an error and may not continue to process data.

If your system catalog was generated from a repository with numeric or date user-defined fields, your routines must include conditional statements that set the outdata value. The tutorial uses column and table names, but you can also use userstr or recdata. In addition, outdata must have a value, and the routine must return a value of 0.

A routine for user-defined data can return a null date for a SELECT operation. To do this, fill the user_to_number() outdata argument with either eight zeros or eight spaces. Both designate a null date value.