Sample Code

The Ingres installation includes OpenAPI sample code that demonstrates synchronous and asynchronous execution of OpenAPI functions. The sample code provides an example of how an application uses OpenAPI functions are and combines them to access database information.

The sample code is located in the API directory, which is under the Ingres demo directory. Makefiles for compiling and linking the demo programs are provided for UNIX (Makefile) and Windows NT (makefile.wnt) environments.

How the Synchronous Sample Code Works

The synchronous sample code consists of a number of sources files whose names begin with the prefix "apis". Each source file demonstrates a single aspect of the OpenAPI interface and compiles into its own executable demo program.

OpenAPI functions are called synchronously: each OpenAPI function call is followed by a loop that calls IIapi_wait() repeatedly until the original OpenAPI call completes.

Note: Database event processing is inherently asynchronous and is not demonstrated in the synchronous sample code. The asynchronous sample code provides an extensive example of database event handling using OpenAPI.

main() Function

The main() function at the beginning of the source file usually contains the specific aspect being demonstrated. OpenAPI function calls that support the demonstration, such as connection or transaction management, are at the end of the file. Sometimes, when the demonstration calls for multiple executions of an OpenAPI function, you can place the OpenAPI function call in its own function following main().

Error Checking

Typically, the sample programs do not perform error checking on the results of OpenAPI function calls. Error processing is demonstrated in one of the sample programs.

In general, these source files show:

• How OpenAPI function parameters are established
• The order in which OpenAPI functions are called to perform a specific action
• How OpenAPI function output is processed

While the samples can be compiled and executed, the actual runtime actions performed provide little useful information.

How You Can Run a Program

Each sample program takes a single command line argument, which is the target database to run against. For example:

apisconn mydb

Source File Descriptions

The following list identifies the synchronous sample source files and the OpenAPI functionality they demonstrate.

• apisinit.c

  Demonstrates OpenAPI initialization, termination, and handling of environment handles.

• apisdata.c

  Demonstrates data conversion using IIapi_convertData() and IIapi_formatData().

• apiserr.c

  Demonstrates processing OpenAPI status results and error handling.

• apisconn.c

  Demonstrates establishing, terminating, and aborting connections.

• apiscomm.c

  Demonstrates committing transactions.

• apisroll.c

  Demonstrates rolling back transactions, setting savepoints, and rolling back to a savepoint.

• apisauto.c

  Demonstrates starting and ending autocommit transactions.

• apis2ph1.c

  Demonstrates distributed transactions (part 1): register transaction ID and prepare to commit.

• apis2ph2.c

  Demonstrates distributed transactions (part 2): connect to transaction, rollback, release transaction ID.

• apisparm.c

  Demonstrates handling of query parameters.

• apissell.c

  Demonstrates retrieving data using a select loop and canceling a query.

• apisselc.c

  Demonstrates retrieving data using a cursor.

• apiscdel.c

  Demonstrates deleting rows using a cursor.

• apiscupd.c

  Demonstrates updating rows using a cursor.

• apisproc.c

  Demonstrates executing database procedures.

• apisprbr.c

  Demonstrates executing database procedures with BYREF parameters.

• apisprrp.c

  Demonstrates executing row-producing database procedures.

• apisprgt.c

  Demonstrates executing database procedures with global temporary table parameters.

• apiscopy.c

  Demonstrates using COPY TABLE statement to transfer data between application and DBMS.

• apisrept.c

  Demonstrates defining and executing repeat statements.

• apisblob.c

  Demonstrates processing BLOB parameters and results.

• apisname.c

  Demonstrates accessing Name Server VNODE information.

How the Asynchronous Sample Code Works

The asynchronous sample code consists of a number of sources files whose names begin with the prefix "apia". The source files are compiled and linked to produce a single comprehensive demo program that provides a real-life example of using OpenAPI in a client/server environment. OpenAPI functions are called asynchronously: each OpenAPI function call is provided with a callback function, which notifies the demo program of the completion of the function call.

Though single-threaded, the demo program consists of two independent execution units: a server unit, which creates, registers, and waits for database events, and a client unit, which periodically raises database events. The main processing control in the demo program initializes one, the other, or both of the execution units, then loops calling IIapi_wait() until all asynchronous activity has ended. Each execution unit, when initialized, issues its first asynchronous request. The units regain execution control when their requests complete and continue issuing new requests until they reach their termination conditions.

How the Client Execution Unit Works

The client execution unit demonstrates asynchronous processing using unique callbacks. Each asynchronous OpenAPI call is given a unique callback function, which determines the next action to be performed when the call completes. Each callback function checks the OpenAPI function call status, processes any result data, and determines the next action to be performed. Operation continues by making a new asynchronous OpenAPI function call and providing the next function in the processing sequence as the callback function. After all requested database events have been raised (including the optional server termination event), the client unit stops making asynchronous OpenAPI requests.

How the Server Execution Unit Works

The server execution unit demonstrates asynchronous processing using a Finite State Machine. A single callback function is used for all asynchronous OpenAPI calls. A control block passed with the asynchronous call contains the information necessary, including the current state, to process the call results and determine the next state and actions to be performed. The server unit continues waiting for and processing database events until the termination event is received. Upon receiving the termination event, the server unit cancels any active requests, frees resources, and terminates.

How You Can Run the Demo Program

You can run the demo program in a variety of configurations: client-only, serveronly, and client and server. You can run multiple instances of the demo program simultaneously. Each server instance receives and displays events raised by each client instance.

You run the demo program with the following command line syntax:

apiademo [-s] [-c] [-t] [-i] db [n]

This command uses the following parameters:

• -s

  Runs the server execution unit.

• -c

  Runs the client execution unit.

• -t

  Sends termination indication to demonstration servers.

• db

  Specifies the name of the target database.

• n

  Specifies the number of events to be raised by the client.

  Default: 5

Examples: apiademo command

The following commands are equivalent:

Source File Descriptions

The asynchronous sample source files are as follows:

• apiademo.c

  Demonstrates main processing control.

• apiaclnt.c

  Demonstrates client execution unit.

• apiasvr.c

  Demonstrates server execution unit.

• apiautil.c

  Demonstrates utility functions.