Application Instrumentation and Control (AIC) API, Version 1.0
Copyright © 1999 The Open Group
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.
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
functions against properties of management objects
Registration of user written
functions against objects (
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
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.
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
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
shuts down the AIC library. It is not possible to restart
AIC again after a
Creation and Deletion of Management Objects
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
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
API functions perform an operation on an object, setting its
value, a threshold value or another property of the object. Attempting
to use a
function on an object of the wrong type is not allowed and
will give an error return code.
- The AIC-AL
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
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
type, so for example an
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
function by an external client application. The default value for
operations for all objects is denied. The security levels must be
specifically set by the application programmer using the above calls
operations are to be enabled.
AIC AL Get Functions
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
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.
function is only ever called when the
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
The three functions that can be registered against a management object
are presented in the table below.
Table: Polling/Threshold/DoAction User-Written Functions
||Polling mechanism inside the application (AIC-AL)
>> Called AUTOMATICALLY
|Regular update of a property of a management object
||Polling mechanism inside the application (AIC-AL)
>> Called AUTOMATICALLY
|Regular comparison of threshold data to value - with some action
if thresholds exceeded
||API call to
(either AIC-AL or AIC-CL)
>> Called MANUALLY
|Generic callback function
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
to change an object's value.
is similar to
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.
is used to register a
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
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.
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
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
Strategies for Updating Management Objects
Polling functions are an important mechanism for updating management
It is envisaged there are likely to be two main ways to update
management objects within a business application. These are outlined
Updating Management Objects.
Table: Updating Management Objects
internal application event or transaction cycle, add
calls to the code.
Ensures a set per transaction.
too many (application processes 50 transactions per second) or too few
calls (transaction not received in 5 hours).
|Write a polling function to get the value, which the polling function
then inserts into the management object using
Function is called in the background on a regular basis, independent of
the application event loop.
Regular updates of management object data.
Added complexity of writing a function per management
object (which must be thread-safe - less of a problem if data is only
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,
Events can be directed to a log file, or to a Systems Management
for more details.
Library Wide Functions
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
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
returns all objects at the same level as the named object. For
example, if you supplied the name
all objects with the name
are returned, but those with additional
after the single symbol are not.
returns a list of objects from the supplied object down
the number of levels given by
parameter of 0 is the same as a list call.
As an example, a call to traverse with an
parameter of 2 and a
location in structure of
will return all objects with
in their name plus up to and including an
additional two symbols, that is -
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.
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
takes the list returned from one of list generating
and moves down the list on successive calls.
function returns a reference to an object which
can then processed by a group of functions such as
They are designed to provide strongly typed
access to object attributes.
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
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
is always required, then before any
call is made, the function
must be used to register the
Thereafter, the plug-in will always send the last registered
combination in all future
With the DCE/GSSAPI plug-in, the call
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
operations thereafter use it.
The user of
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.