Setting up IP source and schema

You can develop an IP for your data source by starting with the installed template IP, one of the installed examples.

The steps in this section assume you are starting from the template IP installed at install_dir/ip/oac/template_c. The template IP consists of stubs for each of the IP functions that you must implement.

If you start from one of the examples, the steps are the same as if you start from a template IP, except that you replace references to template with example. For code samples downloaded from the Progress DataDirect code library, follow the instructions provided with the sample. If you are coding in C++, then use template_cpp instead of template_c.

The template IP directory install_dir/ip/oac/template_c shipped with OpenAccess SDK contains the following files:

• damip.c - defines the IP functions such as OAIP_connect
• damip_ascii.def - export definitions to be used on Windows for an ASCII IP
• damip_unicode.def - export definitions to be used on Windows for a Unicode IP
• oadamip.vcxproj - Visual Studio project file for Windows
• makefile - makefile for use on Linux/UNIX

OpenAccess SDK also provides the following schema directories:

• install_dir/ip/schema/template_static
• install_dir/ip/schema/template_dynamic

The ip/schema/template_static directory contains the minimal OA_TABLES, OA_COLUMNS, OA_STATISTICS, and OA_FKEYS configuration required to use the OpenAccess SDK SQL engine schema manager.

The ip/schema/template_dynamic directory contains the minimal OA_TABLES and OA_COLUMNS required to support views over dynamic schema and are used when the IP is implementing the schema management.

To set up the source and schema for a new IP:

1. Copy the contents of the ip/oac/template_c directory and all subdirectories and files to a directory ip/oac/yourip and rename the template files. For example, on UNIX, perform the following commands, replacing yourip with the name you have chosen for your IP:
   a. cd install_dir/ip/oac
   b. mkdir yourip
   c. cp -r template/yourip
   d. cd yourip
   e. mv damip.c yourip_drv.c

2. Edit the project file on Windows or the makefile on UNIX to reference your IPfiles.

   • For building on Windows:

   1. Open Visual Studio project ip\oac\yourip\oadamip.vcxproj.

   2. Remove damip.c files from the Source Files folder and add in yourip_drv.c files and any other files required to build your IP.

      • If the IP project is being created from the template project provided by OpenAccess SDK, skip to step 3.
      • If the IP is implemented from scratch on OpenAccess SDK 8.1 or is being upgraded from OpenAccess SDK 6.0 SP3 to OpenAccess SDK 8.1, add the xxx_info.c file explicitly in the IP project.

   3. Add references to any other libraries required to build your IP. The Library Files group contains a reference to the oadsdam.lib and must not be removed.

   4. The project is set up to output the generated DLL to install_dir\ip\bin folder and must not be changed. The name of the file can be changed, and this name will be used as the value for ServiceIPModule service attribute when setting up the OpenAccess SDK Service to access your data source.

   5. The project is set up to use the damip_ascii.def file for exporting the IP API functions. Use the damip_unicode.def file if you are exposing Unicode IP functions, such as OAIP_schemaW. This file must be edited to include all the IP API functions that are being exported. For example, if you are implementing dynamic schema, then you must have an entry called OAIP_schema or OAIP_schemaW in the file.

   6. Perform a build and make sure your IP DLL builds without any issues and is placed in the install_dir\ip\bin folder.

• For building on UNIX:

  1. Change to your installation directory.

  2. Set up required environment variable:

     • If working in Korn Shell then use the command:

     unixKshPrompt> . ip/cfg/setenv.sh

     • If working in C shell then use the command:

     unixCshPrompt> source ip/cfg/setenv.csh

  3. Change to directory ip/oac/yourip.

  4. Edit the makefile to add source files and required libraries for your IP.

     Add any additional files required to build and link your IP. The supplied makefile is set up to create a shared library and to place it in install_dir/ip/bin folder. The name of the output file can be changed. This name will be used as the value for ServiceIPModule attribute when setting up the OpenAccess SDK service to access your data source.

     The supplied makefile references install_dir/ip/cfg/env.mk for compiler and linker commands and options. Modify this env.mk file as required for your compiler and system environment.

     Compile your IP into a shared library by issuing the build command:

     unixCshPrompt> make

For schema support, do one of the following steps:

• Static schema: If you want to use the static schema feature where the OpenAccess SDK SQL engine manages the schema, set up the required schema storage files by copying the contents of ip/schema/template_static directory to directory ip/schema/yourip.
• Dynamic schema: If you are implementing a dynamic schema where the IP implements the SCHEMA function and you want to take advantage of SQL views, then copy the contents of ip/schema/template_dynamic directory to directory ip/schema/yourip.

The schema directory you create in this step will be used as the DataSourceIPSchemaPath when configuring the data source for the OpenAccess SDK service using this IP.

On UNIX, for example, perform the following commands to set up a static schema:
a. cd ip/schema
b. mkdir yourip
c. cp -r template_static/\ yourip

The development environment and the schema folder for your IP are now set up. Next, set up the OpenAccess SDK service to access your data source. Refer to Debugging an OpenAccess SDK Interface Provider on the Progress DataDirect web site for details on how to debug an IP on Linux, UNIX, and Windows.

Important: By default, the files xxx_info.c and xxx_info.h are already included in the projects of samples and template. If you implement your IP from scratch on OpenAccess SDK 8.1 or if you are migrating from OpenAccess SDK 6.0 SP3 to OpenAccess SDK 8.1, you must include these files explicitly in your projects. Inclusion of these files is mandatory.