Previous section.

Application Instrumentation and Control (AIC) API, Version 1.0
Copyright © 1999 The Open Group

Fundamental Management Object

AIC Managed Objects

The AIC specification is based upon the concept of a management object. This object has a set of properties, but its value must be one of the following four types:

Management Object "Type" Based upon data Type Default Value
AICBusLong AIC_Long 0
AICBusVarChar AIC_String empty
AICBusDouble AIC_Double 0.0
AICBusTimeDate AIC_DateTime
Year = 9999
Month = 1
Day = 1
Hours = 0
Mins = 0
Seconds = 0

Table: Managed Object Types

All API calls referring to management objects use the 4 reserved words on the left in the above table (for example, AICBusVarChar).

Properties of any Management Object

Each management object has all of the following properties. In the table below, the default value for a given property is in bold typeface.

Int Status {unknown; normal; warning; critical; down}
AIC_String Location not null
AIC_String Semantics null
<Type> Value  
Int SecDoAction {level1, level2, level3, level4, level5, level6, denied, none}
Int SecGet {level1, level2, level3, level4, level5, level6, denied, none}
Int SecSet {level1, level2, level3, level4, level5, level6, denied, none}
<Type>
ThresholdOne-Value
ThresholdTwo-Value
ThresholdThree-Value
ThresholdFour-Value
AIC_String ThreshSemantics null
Int Visibility {local, domain, enterprise}
ThreshFunc void *ThresholdFunction null
AIC_String ThreshDescription "*"
PollingFunc void *PollingFunction null
AIC_String PollingDescription "*"
DoActionFunc void *DoActionFunction null
AIC_String DoActionDescription "*"

Table: Properties of any Management Object

The Status property of an object is similar to the status of an object in a management framework. The analogy is the traffic light high level view of the current status of the object.

The Location property is a string listing the location of the object in the object tree. See Object Naming Conventions on Object Naming. An example for this property would be the string: 



 

/stats/tradesreceived

This value is unique within a given process. The value is assigned at object creation time, by a parameter supplied to the call AICAL_Create().

The Semantics property is used for forward compatibility with CIM and other possible data models outside the application. It is expected in a future revision of the specification that a formal syntax for the population of this property will be defined.

The Value property is where the actual value of the appropriate type is held (for example, the number for a AICBusLong).

The SecDoAction, SecGet and SecSet properties all hold security levels associated with this unique object. Each is a security setting against a particular operation. The operations are shown in Security Properties for DoAction/Get/Set Operations below (note that a DoAction is AIC terminology for a generic callback function).

Property External Action Default
SecDoAction Invoke a callback function Blocked
SecGet Get (query) a value Pass
SecSet Set (change) a value Blocked

Table: Security Properties for DoAction/Get/Set Operations

Each object has four threshold values (.B ThresholdOne , ThresholdTwo, ThresholdThree, ThresholdFour) that can be changed via supplied APIs. The threshold values are of the same type as the object value (for example, if the object type is AICBusLong, each of the four threshold values are also AICBusLong). Threshold values are provided so that the acceptable limits for the value of an object can be defined, and action taken within a threshold function if its value becomes unacceptable (for example, threshold one might hold an upper bound for a value, threshold two might hold the lower bound for a value).

Note:
There are no fixed semantics around what the threshold values represent. The programmer assigns values to them, and by writing a function assigns semantics to those values. Within this specification they are totally generic.

The Visibility property controls whether or not the object is "published". AIC provides the facility for an object to be published externally. By default, this features is off. The feature is controlled by this property within any given object. The exact nature of where the object is published to is implementation defined. It is expected the destination will be into a management framework, at potentially different levels of the framework. When the visibility parameter is set to something other than "local" then the object is published. Changes to the value and status of the object are propagated outside of the current application process.

Further values will be defined later as part of the AIC Host Service: Management FrameWork Gateway definition. Care is necessary when making an object visible outside of local level, because every time the value or status of a published object changes, a message is sent out of the application, through to the Management Framework Gateway. This facility is provided for the sole purpose of "publishing" the value or status of important objects to a management framework.

Registered Functions against a Management Object

When a management object is created, there are three placeholders for functions to be registered against that object. Each has an intended purpose. However, because they are programmer written, the functions could be used for any purpose.

A more detailed explanation is available in AIC API Overview.

API calls are provided to register these functions. Re-registering with NULL will clear the registration.

Standard Management Objects

When the AIC library is started, several management objects are created automatically and populated with data. There are two sets of standard objects:

To create these objects, the AICAL_Create() call is used. The values are populated by the implementation. They are traditional management objects in every respect except one - once created, they have WORM semantics.

A minimum subset of these objects must be provided by an implementation unless the operating system does not support the concept (for example, no working directory). If they cannot be implemented, the objects must be created, but initialized with the string "Not Supported".

Type Location in Object Tree Description
AICBusVarChar /MachineData/ ** special **
AICBusVarChar /MachineData/AICVersion Version of AIC library
AICBusVarChar /MachineData/ApplicationName AIC application name
AICBusVarChar /MachineData/DateAndTimeStarted Date/time application started
AICBusVarChar /MachineData/UserId User ID of application owner
AICBusVarChar /MachineData/ProcessId Process ID of the application
AICBusVarChar /MachineData/ProcessName OS name of the application
AICBusVarChar /MachineData/CommandLine Command line starting the application
AICBusVarChar /MachineData/LibraryPath Path containing DLL/SO files
AICBusVarChar /MachineData/WorkingDirectory Directory the application is working in
AICBusVarChar /ProcessData/ ** special **
AICBusVarChar /ProcessData/OSPlatform Operating system name and version
AICBusVarChar /ProcessData/TimeZone The local time zone
AICBusVarChar /ProcessData/HostName machine name of the host
AICBusVarChar /ProcessData/Ip1 ip address 1

Table: Standard Management Objects

The two objects /MachineData and /ProcessData are special management objects. External to the application in the AIC Host Services cache, a special value is attached to these objects. When the AIC Host Services on a given node is in contact with the application (through the heartbeat mechanism) the value displayed will be Running for both objects. If the application has just been tagged as not responding to the Heartbeat mechanism, for a small time period (referred to as the "dead cache timeout") the data is available but these special objects display the value Down.

The AICVersion object is a 3-character string conforming to the shared library version as specified in Swapping Implementations.

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