Introduction to writing C-language routines
If your repository contains user-defined fields—fields created as user type fields in S/DE Repository—you can write C language routines to manipulate user-defined field data as it’s read from and written to the database. (This is similar to creating user-overloadable ReportWriter routines.) For example, if a user-defined field stores street addresses in mixed-case characters, and you want the xfODBC driver’s output to be in all uppercase characters, you can create a routine to convert the addresses as they’re read from the database. And if you want the addresses converted to mixed-case characters as they’re input, you can also create a routine to do that.
To create a user-defined data routine,
- on Windows, you’ll create a DLL named xfodbcusr.dll in the connect subdirectory of the main Synergy/DE installation directory.
- on UNIX, you’ll create a shared library, XFODBCUSR.so, in the connect subdirectory of the main Synergy/DE installation directory.
- on OpenVMS, you’ll create a shared image, xfodbcusr_so.exe. The logical XFODBCUSR_SO (set in CONNECT_STARTUP.COM) will point to the location of this shared image.
These are the files that the xfODBC driver calls for user-defined data routines. The bitness of the file (32 or 64) must correspond to the bitness of the Connectivity Series installation. These files must reside on the same machine as the data. For client/server configurations, the file must reside on the server.
To help you learn to create your own user-defined data routines, we’ve created a tutorial that steps you through the process; see Tutorial: Using xfodbcusr.c as an example. And see Using xfodbcusr.c as a template to create user-defined data routines for information on xfodbcusr.c, a C language source file that you can use as a template for your user-defined data routines. Note the following:
- User-defined data routines are called for all user type fields except those that have ^CLASS^ embedded within the user data string. ^CLASS^ is reserved for a subset of date storage formats supported by xfODBC. For more information, see Date and time fields.
- For information on using user-defined fields as tags or keys, see Setting up a repository and Optimizing with keys.
- The Connectivity Series distribution includes base and working versions of the files used for user-defined data type routines. The base versions are in the connect\synodbc\usr\base directory. Do not make changes to these files! They are included so you always have original versions. The working versions are in the connect\synodbc\user directory (except for xfodbcusr.dll on Windows, XFODBCUSR.so on UNIX, or xfodbcusr_so.exe on OpenVMS—these are in the connect directory). When you install Connectivity Series, the installation replaces base versions of these files to ensure you always have the latest versions. To preserve your changes, however, working versions are replaced only if they are unchanged.