AIC API Overview

AIC is an API specification plus supporting facilities. This Chapter gives an overview of the API.

Some of the calls are identical in name and function, whether they are used from the client library (CL) or the application library (AL). The difference is that using the call from the AIC-CL will initiate inter-process communication, whereas using the call from AIC-AL will be handled within the same process.

API Definitions includes summary tables for the whole API, followed by the formal definition for each API call.

AIC AL Functions

The AIC-AL library provides an API that is linked into the business application. This provides features for:

Starting and stopping the AIC library
Creation and deletion of management objects
get and set functions against properties of management objects
Registration of user written functions against objects ( polling, threshold, doAction)
Sending alarms from within the application.

The only mechanism provided for programmer access to management objects is the reference to the management object's location in the object tree structure. For this reason, most of the API calls require this "object specification" as part of the call. It is a core principal to eliminate the use of pointers and handles and improve stability of code (see Object Naming Conventions, on Object Naming Conventions).

However it is recognized that several operations may be required against the same object. For this reason a single object caching mechanism is provided internally within the AIC-AL library.

All the AL functions return a status value on completion (see C Language Header File, which gives the C Language Header File).

The AIC API has been designed to be easy to use. Whilst the API has a large set of calls, only a very small subset are required to instrument the application. See AIC-AL Function and Use, which describes the AIC Library Function and Use, for a brief overview of the 6 calls required to use AIC effectively within a business application. It is expected that these 6 calls will be sufficient to satisfy the needs of many users of the AIC API.

Starting and Stopping the AIC-AL Library

AICAL_LibStart() is the first AIC function that a programmer must call before AIC is ready for use. It handles all initialization. The programmer requests an application name (which is a parameter to the call). This name may be accepted by AIC or may be slightly modified if it is already in use (see Unique Name Generator for details on the Unique Name Generator). The final assigned name is returned by the one call.

The eOpenedBy parameter is only permitted to be main program currently, but in future will allow for opening AIC from a library. This is provided to allow AIC to be linked into a library and a main program separately, but without causing conflict at execution time.

By starting the AIC library, a set of management objects is created automatically for information related to the machine the program is running on, and information on the process that AIC is running inside (see Standard Management Objects). When the call returns, these objects will have been created and populated.

On successful completion, AIC AL is initialized and the return code is AIC_OK.

AICAL_Close() shuts down the AIC library. It is not possible to restart AIC again after a close operation.

Creation and Deletion of Management Objects

AICAL_Create() creates and initializes a new management object (to default value). There are 4 fundamental management object types (see AIC Managed Objects).

The opposite function is AICAL_DeleteObject() which immediately deletes a management object. Management objects can be created and deleted at will (the API is designed to be dynamic).

AIC AL Set Functions

The set API functions perform an operation on an object, setting its value, a threshold value or another property of the object. Attempting to use a set function on an object of the wrong type is not allowed and will give an error return code.

Note:: The AIC-AL set functions do not pass through the security model of AIC. It is assumed that having access to the source code of the application is trusted.

There are three functions used for setting threshold values on objects. They are slightly different from the other set functions. They take an enumerated value which indicates which one of the four threshold values is to be set. Obviously, an object of a given type has thresholds of the same type, so for example an AICBusLong object has AICBusLong threshold values.

AICAL_SetSecuritySet() and AICAL_SetSecurityDoAction() each set one of the security attributes of an object, that is, the level of permission required to either set the value of the object or invoke it's DoAction callback function by an external client application. The default value for set operations for all objects is denied. The security levels must be specifically set by the application programmer using the above calls if set operations are to be enabled.

AIC AL Get Functions

The AL get API functions take the location in structure (to identify the object) and provide an area of memory for the acquired value. This will normally be a pointer to a fixed size variable, but in the case of strings and threshold data it is a sized buffer. They all return a status value on completion. In common with the set functionality, all of these calls are strongly typed.

Registration of Polling/Threshold/DoAction Functions

In the AIC-AL, there are three different user written functions that can be registered against an object. Each function has a purpose in mind. However, given that they are user written, they could be used for anything.

Central to the design of the AIC-AL library is a Background Polling Mechanism. Once the library has been started within a business application, the polling mechanism is started. The polling frequency can be changed using the API call AICAL_SetPollingTime(). This mechanism sleeps a pre-defined period of time. When it wakes, it walks through the object tree within the application, looking for either polling functions or threshold functions which have been registered against management objects. Any functions that are found are started up immediately (asynchronously). When all objects have been interrogated, the mechanism sleeps for the defined period of time. The mechanism is intended to be intelligently deterministic in the frequency with which it runs the functions.

The DoAction function is only ever called when the AICXX_DoAction() function is called (by either the AIC-AL application or from some client application with AIC-CL).

The phrase "DoAction function" is AIC terminology for a generic callback function.

The three functions that can be registered against a management object are presented in the table below.

Type When called Role
Polling Polling mechanism inside the application (AIC-AL)
>> Called AUTOMATICALLY Regular update of a property of a management object
Threshold Polling mechanism inside the application (AIC-AL)
>> Called AUTOMATICALLY Regular comparison of threshold data to value - with some action if thresholds exceeded
DoAction API call to AICxx_DoAction() (either AIC-AL or AIC-CL)
>> Called MANUALLY Generic callback function

Type	When called	Role
Polling	Polling mechanism inside the application (AIC-AL) >> Called AUTOMATICALLY	Regular update of a property of a management object
Threshold	Polling mechanism inside the application (AIC-AL) >> Called AUTOMATICALLY	Regular comparison of threshold data to value - with some action if thresholds exceeded
DoAction	API call to AICxx_DoAction() (either AIC-AL or AIC-CL) >> Called MANUALLY	Generic callback function

Table: Polling/Threshold/DoAction User-Written Functions

AICAL_RegPollSetValue() registers a polling function to be associated with the given object. The polling function just takes the object name as a parameter when it is invoked and returns no result. The polling function is supplied by the application programmer and is expected to use other API calls like AICAL_SetValuexxx() to change an object's value.

AICAL_RegThresholdFunction() is similar to AICAL_RegPollSetValue(), but with a threshold function. The functions (two examples of which are provided with AIC) take the object name and a function description as parameters. The purpose of threshold functions is to check the current value of an object against its threshold attributes and possibly change its status as a result. Threshold functions are called after polling functions, so any changes in value should be caught in the same polling cycle - although if the polling function runs longer than the threshold function, changes will more likely be seen on the next polling interval.

AICAL_RegDoAction() is used to register a DoAction function (generic function). The purpose of a "do action" function is to perform a one off action on request of either the application programmer or from a client function (subject to the security model). The DoAction function prototype takes the name of the object and an area of memory as parameters. This area of memory can be used to pass additional parameters or commands to the function.

AICxx_DoAction() is used to invoke the registered function with a single string for parameter passing to the function. Although important within the AL, it is more significant when used from the CL because string data can be passed from the AIC-CL program to the function residing within the application. An example might be passing a path and filename to a function which writes some diagnostic information to disk.

There is an API call in the AIC-CL API to find out what functions have been registered against a management object. This call is AICCL_GetRegFunctions().

Strategies for Updating Management Objects

Polling functions are an important mechanism for updating management objects.

It is envisaged there are likely to be two main ways to update management objects within a business application. These are outlined in Updating Management Objects.

Option Description Comparison
Application
Event Loop Within the internal application event or transaction cycle, add AICAL_SetValuexxx() calls to the code. Advantage:
Ensures a set per transaction.
Disadvantages:
Could be too many (application processes 50 transactions per second) or too few calls (transaction not received in 5 hours).
Background
mechanism Write a polling function to get the value, which the polling function then inserts into the management object using AICAL_SetValuexxx() call.
Function is called in the background on a regular basis, independent of the application event loop. Advantage:
Regular updates of management object data.
Disadvantage:
Added complexity of writing a function per management object (which must be thread-safe - less of a problem if data is only being READ).

Option	Description	Comparison
Application Event Loop	Within the internal application event or transaction cycle, add AICAL_SetValuexxx() calls to the code.	Advantage: Ensures a set per transaction. Disadvantages: Could be too many (application processes 50 transactions per second) or too few calls (transaction not received in 5 hours).
Background mechanism	Write a polling function to get the value, which the polling function then inserts into the management object using AICAL_SetValuexxx() call. Function is called in the background on a regular basis, independent of the application event loop.	Advantage: Regular updates of management object data. Disadvantage: Added complexity of writing a function per management object (which must be thread-safe - less of a problem if data is only being READ).

Table: Updating Management Objects

It is expected both mechanisms will be used in a large application.

Sending Alarms from an Application

The event API is a mechanism to generate an alarm from within the business application to the outside world. There is just one call, AICAL_RaiseEvent.()

Events can be directed to a log file, or to a Systems Management Framework.

See AIC Events for more details.

Library Wide Functions

Context

Some functions are specific to the client or application libraries of AIC, but others are generic between the two. AIC AL calls are in memory calls. AIC CL calls require using a data transport mechanism.

In order to provide a consistent and "year 2000" (Y2k) approach to date and time data types, a number of API calls are also provided for setting date and time value, formatting them, and doing arithmetic on them. Each of the functions will take an AIC_DateAndTime() as a parameter.

Dynamic Query Functions

Given the object tree is a dynamic structure, a key part of AIC is a query capability, which can return a result set at a point in time.

The following three functions are designed to search the object structure and return a list of objects meeting the given criteria. When called from the business application, these functions access the object structure of the application directly. When called from the AIC-CL library, access is made to the AIC Host Service: Cache on that node.

The three calls refer to the object tree as a hierachial tree with successive levels in the tree denoted by another "/".

Figure: Dump/List/Traverse Functions

AIC_List() returns all objects at the same level as the named object. For example, if you supplied the name /root/trades, all objects with the name /root/<single symbol> are returned, but those with additional / after the single symbol are not.

AIC_Traverse() returns a list of objects from the supplied object down the number of levels given by iLevels. A Traverse with an iLevels parameter of 0 is the same as a list call.

As an example, a call to traverse with an iLevels parameter of 2 and a location in structure of /root/trades will return all objects with the string /root/trades in their name plus up to and including an additional two symbols, that is - /root/trades/<symbol1>/<symbol2>.

AIC_Dump() is more of a wildcard match function. It returns all objects from the supplied object down, and can match on incomplete names. So performing a dump with the location in structure of / will return ALL the management objects within that application.

The three functions return a list of objects. AIC_FreeMemory() frees all the memory associated with the object list. Any information extracted from a list must therefore be copied if it is needed to be accessible after the memory is released.

Figure: Results of Dump/List/Traverse Functions

AIC_GetNextObject() takes the list returned from one of list generating functions ( AIC_List(), AIC_Dump(), AIC_Traverse()) and moves down the list on successive calls.

The AIC_GetNextObject() function returns a reference to an object which can then processed by a group of functions such as AIC_GetBusinessLongV(). They are designed to provide strongly typed access to object attributes.

AIC_GetAllAttributes() is a catchall function that returns all of the available attributes of an object in one go. This has attendant risks because some of the arguments have to be void pointers that the programmer must then cast back to the appropriate type.

AIC CL Functions

The CL provides the API for access to the management interface created in the application (albeit via the AIC Host Services). Many of the functions within the AIC-AL library are available within the AIC-CL library (for example, all the get and set functions). The description of these functions is not repeated here.

AIC CL Administration Calls

These are provided for controlling the operation of the AIC Host Services dynamically and remotely. Each of them take the name of the host as a parameter and then send a message to the Host Services on that node. One of the possible operations is to query a list of applications running with AIC on a given host.

Setting Security for CL Set Functions

Before a set function is invoked within an AIC-CL application (for example, a graphical user interface (GUI), it may be necessary to register security information. The paradigm is different depending on the security plug-in.

With the OS security plug-in, where a userid and password is always required, then before any set call is made, the function AICCL_SetUserCredentials() must be used to register the userid and password. Thereafter, the plug-in will always send the last registered userid/password combination in all future set operations.

With the DCE/GSSAPI plug-in, the call AICCL_SetUserCredentials() is again required to register the name of the DCE principal that the AIC Host Service: Security is running as. Once called, this value is known and all set operations thereafter use it.

The user of AICCL_SetUserCredentials() is totally dependent on the implementation of the security plug-in, and therefore requires good documentation for the developer to work from.

Why not acquire a nicely bound hard copy?
Click here to return to the publication details or order a copy of this publication.

Contents

Next section

Index