Was this helpful?
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, server‑only, 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:
This command…
Is the same as this command…
apiademo dbname
apiademo -s -c -t dbname 5
apiademo -c dbname
apiademo -c dbname 5
apiademo -t dbname
apiademo -c -t db 0
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.
 
Last modified date: 08/28/2024