Previous section.

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

API Definitions

This Chapter gives the detailed definitions for the API and the individual calls within it.

Introduction

All AIC functions have a return value that is an integer. The file <libaic.h> contains a list of return values, each of which has an associated comment explaining the problem. See C Language Header File for the C language header file). There are currently 164 different error messages/return codes. If additional values are required, they are returned by using typed pointer arguments. All AIC functions also follow the Hungarian notation for arguments.

All functions returning string or dynamic values take two parameters of a buffer and the size of the buffer provided. The return code indicates whether the return data fits into the buffer or not.

Within the API functions, AIC is memory safe in the sense that it does not deallocate memory passed to it, nor does it allocate memory internally and pass it back to the calling program.

Function Naming Conventions

The AIC specification reserves the following name spaces for functions and data structures: Prefixes AIC_ , AICAL_ and AICCL_. The prefix AIC_ indicates that the functionality is globally constant through AIC and its internal functionality will be the same regardless of whether it is invoked from the application side or the client side. AICAL_ indicates that the functionality is available through the application library and AICCL_ indicates that the functionality is available from the client library of AIC. Note that there can be functions such as GetValueLong that could have either the AICAL_ or AICCL_ prefix. This simply indicates that although the external interface will be the same, the internal functionality could vary extensively (the client functionality implies the need for interhost communication whereas the application library functionality does not).

Debugging and Error Reporting

The following debug levels are to be supported in this version of the AIC specification:

AIC_LOG_NONE AIC_LOG_FATAL AIC_LOG_CRITICAL AIC_LOG_WARNING AIC_LOG_INFO AIC_LOG_DEBUG AIC_LOG_DEBUG1 AIC_LOG_DEBUG2 AIC_LOG_DEBUG3

The debug levels are exposed to the application programmer, so that a vendor of an implementation can provide a debug version in which logging can easily be activated and a release version which contains no logging call outs. API calls are provided to activate and configure the logging (for example AIC_SetLevel()). The rationale is that in a stable implementation, logging may not be required and its absence will increase the performance of the implementation.

By convention, as the ordinal value increases, a larger volume of debug information is generated. For general debugging purposes, AIC_LOG_DEBUG is the best level to use.

Summary of Calls and Availability in AL and CL

Startup and Shutdown AIC-AL AIC-CL
AICAL_LibStart x  
AICAL_Close x  
AICCL_Close   x

Object Create and Deletion AIC-AL AIC-CL
AICAL_Create x  
AICAL_DeleteObject x  

SET API Calls AIC-AL AIC-CL
AICAL_SetValueLong x  
AICAL_SetValueVarChar x  
AICAL_SetValueDouble x  
AICAL_SetValueDateAndTime x  
AICAL_SetStatus x  
AICAL_SetVisibility x  
AICAL_SetThresholdLong x  
AICAL_SetThresholdDateAndTime x  
AICAL_SetThresholdDouble x  
AICAL_SetSecurityGet x  
AICAL_SetSecuritySet x  
AICAL_SetSecurityDoAction x  
AICAL_SetSemantics x  
AICAL_SetThreshSemantics x  
AICCL_SetValueLong   x
AICCL_SetValueVarChar   x
AICCL_SetValueDouble   x
AICCL_SetValueDateAndTime   x
AICCL_SetStatus   x
AICCL_SetVisibility   x
AICCL_SetThresholdLong   x
AICCL_SetThresholdDateAndTime   x
AICCL_SetThresholdDouble   x
AICCL_SetSecurityGet   x
AICCL_SetSecuritySet   x
AICCL_SetSecurityDoAction   x

GET API Calls AIC-AL AIC-CL
AICAL_GetValueLong x  
AICAL_GetValueVarChar x  
AICAL_GetValueDouble x  
AICAL_GetValueDateAndTime x  
AICAL_GetStatus x  
AICAL_GetVisibility x  
AICAL_GetThresholdLong x  
AICAL_GetThresholdDateAndTime x  
AICAL_GetThresholdDouble x  
AICAL_GetSecurityGet x  
AICAL_GetSecuritySet x  
AICAL_GetSecurityDoAction x  
AICAL_GetSemantics x  
AICAL_GetThreshSemantics x  
AICAL_QueryObjectType x  
AICAL_GetRegFunctions x  
AICCL_GetValueLong   x
AICCL_GetValueVarChar   x
AICCL_GetValueDouble   x
AICCL_GetValueDateAndTime   x
AICCL_GetStatus   x
AICCL_GetVisibility   x
AICCL_GetThresholdLong   x
AICCL_GetThresholdDateAndTime   x
AICCL_GetThresholdDouble   x
AICCL_GetSecurityGet   x
AICCL_GetSecuritySet   x
AICCL_GetSecurityDoAction   x
AICCL_GetSemantics   x
AICCL_GetThreshSemantics   x
AICCL_QueryObjectType   x
AICCL_GetRegFunctions   x

Multi-Value GET - returns a result set in memory AIC-AL AIC-CL
AICAL_List x  
AICAL_Traverse x  
AICAL_Dump x  
AICCL_List   x
AICCL_Traverse   x
AICCL_Dump   x

Processing through a result set AIC-AL AIC-CL
AIC_GetBusinessLongV x x
AIC_GetBusinessLongT x x
AIC_GetBusinessVarChar x x
AIC_GetBusinessDoubleV x x
AIC_GetBusinessDoubleT x x
AIC_GetBusinessDateAndTimeV x x
AIC_GetBusinessDateAndTimeT x x
AIC_GetNextObject x x
AIC_GetLocationInStructure x x
AIC_GetEnumeratedValue x x
AIC_GetAllAttributes x x
AIC_GetRegFunctions x x
AIC_FreeMemory x x

Function Registration APIs AIC-AL AIC-CL
AICAL_RegPollSetValue x  
AICAL_RegDoAction x  
AICAL_RegThresholdFunction x  

Raise Event API AIC-AL AIC-CL
AICAL_RaiseEvent x  

Function Invocation API AIC-AL AIC-CL
AICAL_DoAction x  
AICCL_DoAction   x

Date and Time Utility APIs AIC-AL AIC-CL
AIC_GetDateTime x x
AIC_SetTimeStmpNull x x
AIC_TimeStmpCmp x x
AIC_TimeStmpToStr x x
AIC_SetTimeStmp x x
AIC_IsTimeStmpNull x x
AIC_ChgTimeStmp x x

Library Configuration APIs AIC-AL AIC-CL
AICAL_SetLogFileName x  
AICAL_SetLevel x  
AICAL_ToScreen x  
AICAL_SetPollingTime x  
AICCL_SetLogFileName   x
AICCL_SetLevel   x
AICCL_ToScreen   x
AICCL_SetReceiveTimeOut   x

Security Setup AIC-AL AIC-CL
AICCL_SetUserCredentials   x

Administration APIs AIC-AL AIC-CL
AICCL_ChangeServicesLogging   x
AICCL_ServicesShutdown   x
AICCL_RequestServicesStatistics   x
AICCL_GetAppInfo   x
AICCL_ServicesStatisticsReset   x
AICCL_FlushAppCacheToFile   x

Function Call Definitions

The remainder of this Chapter presents the AIC API function call definitions in the well-known man-page format.
Previous section.


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

NAME

AICCL_ChangeServicesLogging

SYNOPSIS


#include <libaic.h>

int AICCL_ChangeServicesLogging (
    AIC_String szHostName, 
    AIC_String pszFileName, 
    int iLevel,
    int iToScreen 
    );


DESCRIPTION

Changes the logging behavior of the Services when it is running compiled in debug mode. The log file, log level and print to screen flag can all be changed with one call to this function. Some care is needed to make sure that the correct result is obtained. For example, setting the level to 0 will result in only critical errors being logged, regardless of any other setting used. Level 7 will generate a of debug information, and should be avoided unless absolutely necessary.

PARAMETERS

ID Type Description
szHostName AIC_String Services host machine name
pszFileName AIC_String Log file name (NULL for no name)
iLevel Int Debug level from 1 to 7
iToScreen Int Print to screen flag:
1=print to screen
0=do not print to screen

RETURN VALUE

AIC_OK

The operation succeeded

AIC_NOK

An error occurred

AIC_NULL_POINTER_ARG

Null pointer argument supplied to function

AIC_LOCATION_NULL

The location name given is empty

AIC_ENUMORD_OUTOF_RANGE

The ordinal value of a supplied enum is outside of range

AIC_UNEXPECTED_FUNC_RES

Unexpected function return type

AIC_TIMEOUT

Timeout on request to remote application

AIC_NULL_POINTER_ARG

Null pointer argument supplied to function

AIC_IN_STRUC_NAME_SHORT

The location in structure name is too short to be a sensible name

AIC_BADLY_FORMED_LOCATIONSTRING

Something wrong with the supplied location in structure string

AIC_CANT_ALLOCATE_MEMORY

General failure to allocate memory

AIC_HOST_NAME_TOO_LONG

Trying to get short version of a fully qualified name which is too long

AIC_APP_NAME_TOO_LONG

The application name is too long.

EXAMPLE


iStatus = AICCL_ChangeServicesLogging("Krone", "newlog.log", 4, 1 );


Previous section.

NAME

AIC_ChgTimeStmp

SYNOPSIS


#include <libaic.h>

int AIC_ChgTimeStmp (
    AIC_DateAndTime *pDateTimeStmp, 
    double *pdDeltaSeconds 
);


DESCRIPTION

Modifies a DateAndTime variable forward the passed number of seconds. Note that the number of seconds can be a negative number, so subtraction is also possible.

PARAMETERS

ID Type Description
pDateTimeStmp AIC_DateAndTime * Address of DateTime variable
pdDeltaSeconds double * Seconds to modify time forward

RETURN VALUE

AIC_OK

The operation succeeded

AIC_NOK

An error occurred

EXAMPLE


//Increment the time stamp by one hour

iStatus = AICAL_GetDateTime( &sTime1 );
iStatus = AIC_ChgTimeStmp( &sTime1, 3600 );


Previous section.

NAME

AICAL_Close, AICCL_Close

SYNOPSIS


#include <libaic.h>

int AICAL_Close ( 
    AIC_OpenType eClosedBy 
    );

int AICCL_Close ( 
    ); 


DESCRIPTION

The defined behaviour of both these functions is to make a clean shutdown of the application library and the client library respectively. When the AICAL_Close() function is invoked it is not then possible to re-start the library. AICAL_Close() takes just one parameter that indicates whether the close is being invoked from a library or from the mainProgram. The only value required to be supported in this version of the standard is mainProgram. AICCL_Close() performs a clean shutdown of the AICCL library.

PARAMETERS

ID Type Description
eClosedBy AIC_OpenType Calling program status. Options:
mainProgram
Library

RETURN VALUE

AIC_OK

The operation suceeded

AIC_ENUMORD_OUTOF_RANGE

The ordinal value of a supplied enum is outside of range

AIC_LIB_NOTINITIALISED

The library is not currently initialised

AIC_NOK

An error occurred

EXAMPLE


iStatus = AICCL_Close( );

iStatus = AICAL_Close(mainProgram);


Previous section.

NAME

AICAL_Create

SYNOPSIS


#include <libaic.h>

int AICAL_Create ( 
    AIC_ObjectType eObjectType, 
    AIC_String szLocation_in_Structure
    );


DESCRIPTION

Creates a management object at the specified location in the object structure, of the required type. The call is required to verify that the name of the object is unique and follows the naming conventions defined in this standard.

When created, the object has default values (see AIC Managed Objects, Fundamental Management Object.

The naming convention adopted in this standard can be interpreted as a tree like structure. See Object Naming Conventions, (Object Naming Conventions) for details.

PARAMETERS

ID Type Description
EObjectType AIC_ObjectType
Requested type of new object.
Options:
AICBusLong
AICBusVarChar
AICBusDouble
AICBusTimeDate
szLocation_in_structure AIC_String Location in the object tree

RETURN VALUE

AIC_OK

The operation succeeded

AIC_NOK

An error occurred

AIC_ENUMORD_OUTOF_RANGE

The ordinal value of a supplied enum is outside of range

AIC_DUPLICATE_OBJECT

Tried to create a duplicate object in the object structure

AIC_OBJECT_NOT_CREATED

The requested object was not created

EXAMPLE


sprintf( szBuffer, "/statistics/trades_per_day");
iStatus =  AICAL_Create(AICBusLong, szBuffer );


Previous section.

NAME

AICCL_ServicesShutdown

SYNOPSIS


#include <libaic.h>

int AICCL_ServicesShutdown ( 
    AIC_String szHostName
    );


DESCRIPTION

Makes a request to the AIC Services for them to stop running. A successful call to this function will result in the controlled shutdown of the host services, but does not imply that any connected application libraries need be notified of the shutdown.

PARAMETERS

ID Type Description
SzHostName AIC_String Services host machine name

RETURN VALUE

AIC_OK

The operation succeeded

AIC_NOK

An error occurred

AIC_NULL_POINTER_ARG

Null pointer argument supplied to function

AIC_LOCATION_NULL

The location name given is empty

AIC_TIMEOUT

Timeout on request to remote application

AIC_NULL_POINTER_ARG

Null pointer argument supplied to function

AIC_IN_STRUC_NAME_SHORT

The location in structure name is too short to be a sensible name

AIC_BADLY_FORMED_LOCATIONSTRING

Something wrong with the supplied location in structure string

AIC_CANT_ALLOCATE_MEMORY

General failure to allocate memory

AIC_HOST_NAME_TOO_LONG

Trying to get short version of a fully qualified name which is too long

AIC_APP_NAME_TOO_LONG

The application name is too long.

EXAMPLE


iStatus = AICCL_ServicesShutdown ("Krone");


Previous section.

NAME

AICCL_ServicesStatisticsReset

SYNOPSIS


#include <libaic.h>

int AICCL_ServicesStatisticsReset ( 
    AIC_String szHostName
    );


DESCRIPTION

Sends a message to the Services on the specified host requesting a reset of the services statistics to zero. This command is useful when running statistics over a number of distinct periods, without needing to stop and restart the services.

PARAMETERS

ID Type Description
SzHostName AIC_String Services host machine name

RETURN VALUE

AIC_OK

The operation succeeded

AIC_NOK

An error occurred

AIC_NULL_POINTER_ARG

Null pointer argument supplied to function

AIC_LOCATION_NULL

The location name given is empty

AIC_UNEXPECTED_FUNC_RES

Unexpected function return type

AIC_TIMEOUT

Timeout on request to remote application

AIC_NULL_POINTER_ARG

Null pointer argument supplied to function

AIC_IN_STRUC_NAME_SHORT

The location in structure name is too short to be a sensible name

AIC_BADLY_FORMED_LOCATIONSTRING

Something wrong with the supplied location in structure string

AIC_CANT_ALLOCATE_MEMORY

General failure to allocate memory

AIC_HOST_NAME_TOO_LONG

Trying to get short version of a fully qualified name which is too long

AIC_APP_NAME_TOO_LONG

The application name is too long.

EXAMPLE


iStatus = AICCL_ServicesStatisticsReset ("Krone");


Previous section.

NAME

AICAL_DeleteObject

SYNOPSIS


#include <libaic.h>

int AICAL_DeleteObject ( 
    AIC_String szLocation_in_Structure
    );


DESCRIPTION

Deletes the specified object from the object tree. Standard Management Objects (which are automatically created when the library is started) have read-only semantics and cannot be deleted (see Standard Management Objects, Standard Management Objects). This functionality is not available from the client API.

PARAMETERS

ID Type Description
szLocation_in_structure AIC_String Location in the object tree

RETURN VALUE

AIC_OK

The operation succeeded

AIC_NOK

An error occurred

AIC_EMPTY_LIST_PTR

Trying to access an empty list pointer

AIC_NOT_DELETABLE_WORM_SEMANTICS

Can't delete this object because it has WORM semantics

AIC_NOT_FOUND

The named object was not found

EXAMPLE


sprintf( szBuffer, "/statistics/trades_per_day" ); 

iStatus = AICAL_DeleteObject(szBuffer );


Previous section.

NAME

AICAL_DoAction, AICCL_DoAction

SYNOPSIS


#include <libaic.h>

int AICAL_DoAction ( 
    AIC_String szLocation_in_Structure, 
    AIC_String pszData, 
    AIC_Long lDataLength
    ); 

int AICCL_DoAction ( 
    AIC_String szLocation_in_Structure, 
    AIC_String pszData, 
    AIC_Long lDataLength
    );


DESCRIPTION

Invokes a previously registered doAction function. The function is invoked simply by naming the management object the function is registered against (the function cannot be called direct). You can pass in data to the function as an AIC_String (note that this can go cross-platform).

Note that calling a DoAction function from the client library (AIC-CL) affects a remote function invocation. The string parameter data is passed across from the AIC-CL to the function (as a parameter) inside the business application. All DoAction functions have the same function prototype (they accept a single string argument).

PARAMETERS

ID Type Description
szLocation_in_structure AIC_String Location in the object tree
pszData AIC_String Data to be passed to the function
lDataLength AIC_Long Length of the data to be passed

RETURN VALUE

AIC_OK

The operation succeeded

AIC_NOK

An error occurred

AIC_NULL_POINTER_ARG

Null pointer argument supplied to function

AIC_UNEXPECTED_FUNC_RES

Unexpected function return type

AIC_TIMEOUT

Timeout on request to remote application

AIC_NULL_POINTER_ARG

Null pointer argument supplied to function

AIC_IN_STRUC_NAME_SHORT

The location in structure name is too short to be a sensible name

AIC_BADLY_FORMED_LOCATIONSTRING

Something wrong with the supplied location in structure string

AIC_CANT_ALLOCATE_MEMORY

General failure to allocate memory

AIC_HOST_NAME_TOO_LONG

Trying to get short version of a fully qualified name which is too long

AIC_APP_NAME_TOO_LONG

The application name is too long.

EXAMPLE


len1=strlen(argv[2]);

iStatus=AICAL_DoAction(gQuery_location,argv[2],len1);


Previous section.

NAME

AICAL_Dump, AICCL_Dump

SYNOPSIS


#include <libaic.h>

int AICAL_Dump ( 
    AIC_String szLocation_in_Structure, 
    AIC_ListPtr *ppDstListPtr
    ); 

int AICCL_Dump ( 
    AIC_String szLocation_in_Structure, 
    AIC_ListPtr *ppDstListPtr
    );


DESCRIPTION

Performs a query against the object tree1. Returns the objects from the specified point down the tree, doing a full tree traversal. The resulting objects are returned as a list which can only be traversed using the AIC_GetNextObject() function. When the list is no longer required, it can be freed using the AIC_FreeMemory() call.

PARAMETERS

ID Type Description
szLocation_in_structure AIC_String Full object tree location specification
PpDstListPtr AIC_ListPtr * Pointer to a list of results

RETURN VALUE

AIC_OK

The operation succeeded

AIC_NOK

An error occurred

AIC_NULL_POINTER_ARG

Null pointer argument supplied to function

AIC_IN_STRUC_NAME_SHORT

The location in structure name is too short to be a sensible name

AIC_BADLY_FORMED_LOCATIONSTRING

Something wrong with the supplied location in structure string

AIC_CANT_ALLOCATE_MEMORY

General failure to allocate memory

AIC_HOST_NAME_TOO_LONG

Trying to get short version of a fully qualified name which is too long

AIC_APP_NAME_TOO_LONG

The application name is too long.

EXAMPLE


int          iStatus;
AIC_ListPtr  pList;
iStatus = AICAL_Dump(query_location, &pList);


Previous section.

NAME

AICCL_FlushAppCacheToFile

SYNOPSIS


#include <libaic.h>

int AICCL_FlushAppCacheToFile ( 
    AIC_String szHostName, 
    AIC_String pszAppName, 
    AIC_String pszFileName
    );


DESCRIPTION

Requests that the host services on the named machine dump the cache of the named application to file. This function is useful for debugging applications because it can be invoked after an application has crashed but before the application cache has timed out. Each object is written on a single line with each of its human readable attributes displayed. Attributes, like registered functions, are not written to this file.

PARAMETERS

ID Type Description
SzHostName AIC_String Daemon host machine name
PszAppName AIC_String Name of the application whose cache will be flushed
PszFileName AIC_String The full filename of the cache dump file

RETURN VALUE

AIC_OK

The operation succeeded

AIC_NOK

An error occurred

AIC_NULL_POINTER_ARG

Null pointer argument supplied to function

AIC_LOCATION_NULL

The location name given is empty

AIC_APPNAME_NOTFOUND

Looking for an app name in a location string, but can't find it

AIC_EMPTY_NAME

A name supplied is empty

AIC_UNEXPECTED_FUNC_RES

Unexpected function return type

AIC_TIMEOUT

Timeout on request to remote application

AIC_IN_STRUC_NAME_SHORT

The location in structure name is too short to be a sensible name

AIC_BADLY_FORMED_LOCATIONSTRING

Something wrong with the supplied location in structure string

AIC_CANT_ALLOCATE_MEMORY

General failure to allocate memory

AIC_HOST_NAME_TOO_LONG

Trying to get short version of a fully qualified name which is too long

AIC_APP_NAME_TOO_LONG

The application name is too long.

EXAMPLE


IStatus = AICCL_FlushAppCacheToFile ("Krone", "Application1", 
          "appcacheFile.txt");


Previous section.

NAME

SYNOPSIS


#include <libaic.h>

int AIC_FreeMemory ( 
    AIC_ListPtr pList
    );


DESCRIPTION

Frees the in-memory result set which is returned from AIC_Traverse(), AIC_Dump() or AIC_List(). If the pointer to the list is NULL, the function returns immediately. If the pointer is corrupted or not initialised by one of the above functions, the result of calling this function is undefined. On successful return from this function, all the memory allocated to the list structure is freed and the pointer no longer refers to a valid memory structure.

PARAMETERS

ID Type Description
Plist AIC_ListPtr Pointer to a list of results

RETURN VALUE

AIC_OK

The operation succeeded

AIC_NOK

An error occurred

AIC_EMPTY_LIST_PTR

Trying to access an empty list pointer

EXAMPLE


iStatus = AIC_FreeMemory(pList);


Previous section.

NAME

AIC_GetAllAttributes

SYNOPSIS


#include <libaic.h>

int AIC_GetAllAttributes ( 
    AIC_ObjectPtr pObjectPtr,
    AIC_VoidPtr pDstValue,
    int iDstBufSizeValue,
    AIC_String szDstBufLoc,
    int iDstBufSizeLoc,
    AIC_VoidPtr pDstThreshold1,
    int iDstBufSizeThreshold1,
    AIC_VoidPtr pDstThreshold2,
    int iDstBufSizeThreshold2,
    AIC_VoidPtr pDstThreshold3,
    int iDstBufSizeThreshold3,
    AIC_VoidPtr pDstThreshold4,
    int iDstBufSizeThreshold4,
    AIC_Status *peStatus,
    AIC_ObjectType *peObjectType,
    AIC_Visibility *peDstVisibility,
    AIC_SecurityLevel *peDstSecSetLevel,
    AIC_SecurityLevel *peDstSecDoActionLevel,
    AIC_SecurityLevel *peDstSecGetLevel,
    int iDstBufSizeSemantics,
    AIC_StringszDstBufSemantics,
    int iDstBufSizeThreshSemantics,
    AIC_String szDstBufThreshSemantics
    );


DESCRIPTION

Returns all meaningful2 attributes for an object in the result set in memory. If the extraction of any single attribute fails, the extraction of all of them is deemed to have failed, and the return parameters will be undefined. This function is intended for use when the majority of object attributes are required. Other functions are defined within the standard to access specific attributes one at a time. The thresholds and values of the object are returned via a void pointer (which can be avoided by using the type specific single attribute calls), and it is the application programmers responsbility to convert them to the type appropriate for the object (the type is one of the returned values).

PARAMETERS

ID Type Description
PobjectPtr AIC_ObjectPtr Pointer to result set
PdstValue AIC_VoidPtr Value
IdstBufSizeValue int Size of memory to contain the value
SzDstBufLoc AIC_String Location in object tree
IDstBufSizeLoc int Length of string holding object location
PDstThreshold1 AIC_VoidPtr Threshold 1
IDstBufSizeThreshold1 int Size of memory to contain the threshold
pDstThreshold2 AIC_VoidPtr Threshold 2
iDstBufSizeThreshold2 int Size of memory to contain the threshold
pDstThreshold3 AIC_VoidPtr Threshold 3
iDstBufSizeThreshold3 int Size of memory to contain the threshold
pDstThreshold4 AIC_VoidPtr Threshold 4
iDstBufSizeThreshold4 int Size of memory to contain the threshold
peStatus AIC_Status Status of the object
peObjectType AIC_ObjectType Type of the object
peDstVisibility AIC_Visibility Visibility level of the object
peDstSecSetLevel AIC_SecurityLevel Security level required to set this value
peDstSecDoActionLevel AIC_SecurityLevel Security level required to invoke a callback registered against this object
peDstSecGetLevel AIC_SecurityLevel Security level required to get information from this object
iDstBufSizeSemantics Int The length of the buffer to receive the semantics value of the object
SzDstBufSemantics AIC_String The buffer to place the object's semantics in
iDstBufSizeThreshSemantics Int The length of the buffer to receive the threshold semantics value of the object
SzDstBufThreshSemantics AIC_String The buffer to place the object's semantics in

RETURN VALUE

AIC_OK

The operation succeeded

AIC_NOK

An error occurred

AIC_INSUFFICIENT_SPACE_FOR_VALUE

There is insufficient space for the value to be returned

AIC_INSUFFICIENT_SPACE_FOR_THRESHOLD

There is insufficient space for the threshold to be returned


EXAMPLE


iStatus = AIC_GetAllAttributes(
        pObjectPtr,
        (void *)(&szValue[0]),       /* value */
        sizeof(szValue),             /* size of value */
        szBuffer,                    /* location */
        sizeof(szBuffer),            /* size of location */
        (void *)(&szThreshold1[0]),  /* threshold 1*/
        sizeof(szThreshold1),        /* size of threshold 1*/
        (void *)(&szThreshold2[0]),  /* threshold 2*/
        sizeof(szThreshold2),        /* size of threshold 2*/
        (void *)(&szThreshold3[0]),  /* threshold 3*/
        sizeof(szThreshold3),        /* size of threshold 3*/
        (void *)(&szThreshold4[0]),  /* threshold 4*/
        sizeof(szThreshold4),        /* size of threshold 4*/
        &eObjectStatus,
        &eObjectType,
        &eDstVisibility,
        &eSecSetLevel,
        &eSecDoActionLevel,
        &eSecGetLevel,
        sizeof(szDstBufSemantics),
        szDstBufSemantics,
        sizeof(szDstBufThreshSemantics),
        szDstBufThreshSemantics
        );

switch (eObjectType)
{
    case AICBusLong :
        memcpy(&lValue, &szValue[0], sizeof(AIC_Long));
        break;
    case AICBusDouble :
        memcpy(&dValue, &szValue[0], sizeof(AIC_Double));
        break;
    case AICBusDateAndTime :
        memcpy(&sValue, &szValue[0], sizeof(AIC_DateAndTime));
        break;
    case AICBusVarChar :
        pszValue = (char *)(&szValue[0]);
        break;
}


Previous section.

NAME

AICCL_GetAppInfo

SYNOPSIS


#include <libaic.h>

int AICCL_GetAppInfo ( 
    AIC_String szHostName, 
    AIC_String szDstBuf, 
    int iDstBufSize
    );


DESCRIPTION

Makes a request to the host services on the specified host, requesting information on all the applications currently connected to it. Returns a formatted string with one entry per line giving the following information for each application:

The application information can be used by external browser programs to discover which applications are running on a given host. With this information it is then possible to query specific applications for relevant objects. This information is not required to have any associated security measures.

PARAMETERS

ID Type Description
SzHostName AIC_String Daemon host machine name
SzDstBuf Char * Buffer for application information
IdstBufSize int Size of buffer for application information

RETURN VALUE

AIC_OK

The operation succeeded

AIC_NOK

An error occurred

AIC_LOCATION_NULL

The location name given is empty

AIC_STRING_SPACE_TOO_SMALL

Area of memory supplied to small for string.

AIC_UNEXPECTED_FUNC_RES

Unexpected function return type

AIC_TIMEOUT

Timeout on request to remote application

AIC_NULL_POINTER_ARG

Null pointer argument supplied to function

AIC_IN_STRUC_NAME_SHORT

The location in structure name is too short to be a sensible name

AIC_BADLY_FORMED_LOCATIONSTRING

Something wrong with the supplied location in structure string

AIC_CANT_ALLOCATE_MEMORY

General failure to allocate memory

AIC_HOST_NAME_TOO_LONG

Trying to get short version of a fully qualified name which is too long

AIC_APP_NAME_TOO_LONG

The application name is too long.

EXAMPLE


iStatus = AICCL_GetAppInfo ("Krone", szBuffer, 100 );


Previous section.

NAME

AIC_GetBusinessDateAndTimeT

SYNOPSIS


#include <libaic.h>

int AIC_GetBusinessDateAndTimeT ( 
    AIC_ObjectPtr pObjectPtr, 
    AIC_Double *pDstValue, 
    AIC_ThresholdType eWhichThreshold
    );


DESCRIPTION

Gets the double threshold from an object in the result set. You must specify which threshold is required (one of oneArgThld, twoArgThld, threeArgThld or fourArgThld) and the object must be of type AICBusDateAndTime. Note that all thresholds have the same type as the object value.

PARAMETERS

ID Type Description
PobjectPtr AIC_ObjectPtr Pointer to object in result set
PtDstDateTime AIC_DateAndTime Pointer to a DateAndTime for result
EwhichThreshold AIC_ThresholdType
Which threshold you want, one of:
oneArgThld
twoArgThld
threeArgThld
fourArgThld

RETURN VALUE

AIC_OK

The operation succeeded

AIC_NOK

An error occurred

AIC_NULL_POINTER_ARG

Null pointer argument supplied to function

AIC_NULL_ATTRIBUTE_POINTER

Got an attribute pointer which is null

AIC_OBJ_TYPE_MISMATCH

Trying the call a value set function on the wrong type of object

EXAMPLE


AIC_DateAndTime sDate;
IStatus = AIC_GetBusinessDateAndTimeT( 
    pObjectPtr, &sDate, oneArgThld 
    );


Previous section.

NAME

AIC_GetBusinessDateAndTimeV

SYNOPSIS


#include <libaic.h>

int AIC_GetBusinessDateAndTimeV ( 
    AIC_ObjectPtr pObjectPtr, 
    AIC_DateAndTime *ptDstDateTime
    );


DESCRIPTION

Gets the date and time value from an object in the result set. The function only applied to objects of type AICBusDateAndTime.

PARAMETERS

ID Type Description
pObjectPtr AIC_ObjectPtr Pointer to object in result set
ptDstDateTime AIC_DateAndTime * Pointer to a DateAndTime for result

RETURN VALUE

AIC_OK

The operation succeeded

AIC_NOK

An error occurred

AIC_NULL_POINTER_ARG

Null pointer argument supplied to function

AIC_NULL_ATTRIBUTE_POINTER

Got an attribute pointer which is null

AIC_OBJ_TYPE_MISMATCH

Trying the call a value set function on the wrong type of object

EXAMPLE


AIC_DateAndTime sDate;
IStatus = AIC_GetBusinessDateAndTimeV( pObjectPtr, &sDate );


Previous section.

NAME

AIC_GetBusinessDoubleT

SYNOPSIS


#include <libaic.h>

int AIC_GetBusinessDoubleT ( 
    AIC_ObjectPtr pObjectPtr, 
    AIC_Double *pdDstValue, 
    AIC_ThresholdType eWhichThreshold
    );


DESCRIPTION

Gets the double threshold from an object in the result set. You must specify which threshold and this function only operates on objects of type AICBusDouble.

PARAMETERS

ID Type Description
pObjectPtr AIC_ObjectPtr Pointer to object in result set
ptDstValue AIC_Double * Pointer to a Double for result
eWhichThreshold AIC_ThresholdType
Which threshold you want, one of:
oneArgThld
twoArgThld
threeArgThld
fourArgThld

RETURN VALUE

AIC_OK

The operation succeeded

AIC_NOK

An error occurred

AIC_NULL_POINTER_ARG

Null pointer argument supplied to function

AIC_NULL_ATTRIBUTE_POINTER

Got an attribute pointer which is null

AIC_OBJ_TYPE_MISMATCH

Trying the call a value set function on the wrong type of object

AIC_VALUE_OVERFLOW

Data overflow

EXAMPLE


AIC_Double dValue;
IStatus = AIC_GetBusinessDoubleT( pObjectPtr, &dValue, oneArgThld );


Previous section.

NAME

AIC_GetBusinessDoubleV

SYNOPSIS


#include <libaic.h>

int AIC_GetBusinessDoubleV ( 
    AIC_ObjectPtr pObjectPtr, 
    AIC_Double *pdDstValue
    );


DESCRIPTION

Gets the double value from an object in the result set. This function only works on objects of type AICBusDouble.

PARAMETERS

ID Type Description
pObjectPtr AIC_ObjectPtr Pointer to object in result set
ptDstValue AIC_Double * Pointer to a DateAndTime for result

RETURN VALUE

AIC_OK

The operation succeeded

AIC_NOK

An error occurred

AIC_NULL_POINTER_ARG

Null pointer argument supplied to function

AIC_NULL_ATTRIBUTE_POINTER

Got an attribute pointer which is null

AIC_OBJ_TYPE_MISMATCH

Trying the call a value set function on the wrong type of object

AIC_VALUE_OVERFLOW

Data overflow

EXAMPLE


AIC_Double dDouble;
iStatus = AIC_GetBusinessDoubleV( pObjectPtr, &dDouble );


Previous section.

NAME

AIC_GetBusinessLongT

SYNOPSIS


#include <libaic.h>

int AIC_GetBusinessLongT ( 
    AIC_ObjectPtr pObjectPtr, 
    AIC_Long *plDstValue, 
    AIC_ThresholdType eWhichThreshold
    );


DESCRIPTION

Gets the long threshold from an object in the result set. You must specify which threshold. The function only operates on objects of type AICBusLong. Note that all thresholds have the same type as the object value.

PARAMETERS

ID Type Description
pObjectPtr AIC_ObjectPtr Pointer to object in result set
plDstValue AIC_Long * Pointer to an AIC_Long for result
eWhichThreshold AIC_ThresholdType
Which threshold you want, one of:
oneArgThld
twoArgThld
threeArgThld
fourArgThld

RETURN VALUE

AIC_OK

The operation succeeded

AIC_NOK

An error occurred

AIC_NULL_POINTER_ARG

Null pointer argument supplied to function

AIC_NULL_ATTRIBUTE_POINTER

Got an attribute pointer which is null

AIC_OBJ_TYPE_MISMATCH

Trying the call a value set function on the wrong type of object

AIC_VALUE_OVERFLOW

Data overflow

EXAMPLE


AIC_Long lValue;
iStatus = AIC_GetBusinessLongT( pObjectPtr, &lValue, oneArgThld );


Previous section.

NAME

AIC_GetBusinessLongV

SYNOPSIS


#include <libaic.h>

int AIC_GetBusinessLonV ( 
    AIC_ObjectPtr pObjectPtr, 
    AIC_Long *plDstValue
    );


DESCRIPTION

Gets the long value from an object of type AICBusLong in the result set.

PARAMETERS

ID Type Description
PobjectPtr AIC_ObjectPtr Pointer to object in result set
PlDstValue AIC_Long * Pointer to a long for result

RETURN VALUE

AIC_OK

The operation succeeded

AIC_NOK

An error occurred

AIC_NULL_POINTER_ARG

Null pointer argument supplied to function

AIC_NULL_ATTRIBUTE_POINTER

Got an attribute pointer which is null

AIC_OBJ_TYPE_MISMATCH

Trying the call a value set function on the wrong type of object

AIC_VALUE_OVERFLOW

Data overflow

EXAMPLE


AIC_Long lValue;
IStatus = AIC_GetBusinessLongV( pObjectPtr, &lValue );


Previous section.

NAME

AIC_GetBusinessVarChar

SYNOPSIS


#include <libaic.h>

int AIC_GetBusinessVarChar ( 
    AIC_ObjectPtr pObjectPtr, 
    AIC_String szDstBuf, 
    int iDstBufSize
    );


DESCRIPTION

Returns the AIC_String value of an object of type AICBusVarChar in the result set. The application programmer is responsible for providing a buffer of adequate size for the returned value. If the buffer is too small, an error will be returned and the value truncated to fit the supplied buffer. The function can be called again with a suitably increased buffer. If any other error is found, the contents of the return buffer will be undefined.

PARAMETERS

ID Type Description
pObjectPtr AIC_ObjectPtr Pointer to object in result set
szDstBuf AIC_Srting Pointer to a text buffer for response
iDstBufSize int Size of your text buffer

RETURN VALUE

AIC_OK

The operation succeeded

AIC_NOK

An error occurred

AIC_NULL_ATTRIBUTE_POINTER

Got an attribute pointer which is null

AIC_OBJ_TYPE_MISMATCH

Trying the call a value set function on the wrong type of object

AIC_TIMEOUT

Timeout on request to remote application

AIC_NULL_POINTER_ARG

Null pointer argument supplied to function

AIC_IN_STRUC_NAME_SHORT

The location in structure name is too short to be a sensible name

AIC_BADLY_FORMED_LOCATIONSTRING

Something wrong with the supplied location in structure string

AIC_CANT_ALLOCATE_MEMORY

General failure to allocate memory

AIC_HOST_NAME_TOO_LONG

Trying to get short version of a fully qualified name which is too long

AIC_APP_NAME_TOO_LONG

The application name is too long.

EXAMPLE


iStatus = AIC_GetBusinessVarChar( pObjectPtr, szBuffer, 200 );


Previous section.

NAME

AIC_GetDateTime

SYNOPSIS


#include <libaic.h>

int AIC_GetDateTime ( 
    AIC_DateAndTime *pDateTimeStmp
    );


DESCRIPTION

Returns the current date and time in a DateAndTime structure. It is intended that the programmer either allocates space for the structure or passes the address of a local AIC_DateAndTime variable.

PARAMETERS

ID Type Description
pDateTimeStmp AIC_DateAndTime * Address of DateTime variable

RETURN VALUE

AIC_OK

The operation succeeded

AIC_NOK

An error occurred

EXAMPLE


AIC_DateAndTime sDateTimeStmp;
iStatus = AIC_GetDateTime( &sDateTimeStmp );


Previous section.

NAME

AIC_GetEnumeratedValue

SYNOPSIS


#include <libaic.h>

int AIC_GetEnumeratedValue ( 
    AIC_ObjectPtr pObjectPtr, 
    AIC_Long *peDstEnum, 
    AIC_AttributeType eEnum
    );


DESCRIPTION

Returns a single property of an object in the result set. The enumerated value is returned as a long that the application programmer is responsible for casting to the appropriate type. One of the most frequently used types will be the object type, and this is necessary if processing all the attributes of an object from a result set at one time.

PARAMETERS

ID Type Description
pObjectPtr AIC_ObjectPtr Pointer to object in result set
peDstEnum AIC_Long * Point to long for result
eNum AIC_AttributeType
The desired attribute, one of the following:
objectTypeA
statusA
secDoActionA
secSetA
secGetA
objectVisibilityA

RETURN VALUE

AIC_OK

The operation succeeded

AIC_NOK

An error occurred

AIC_NULL_POINTER_ARG

Null pointer argument supplied to function

AIC_NULL_ATTRIBUTE_POINTER

Got an attribute pointer which is null

AIC_OBJ_TYPE_MISMATCH

Trying the call a value set function on the wrong type of object

EXAMPLE


AIC_Long lAttributeValue;
iStatus = AIC_GetEnumeratedValue( 
    pObjectPtr, & lAttributeValue, objectTypeA 
    ); 


Previous section.

NAME

AIC_GetLocationInStructure

SYNOPSIS


#include <libaic.h>

int AIC_GetLocationInStructure ( 
    AIC_ObjectPtr pObjectPtr, 
    AIC_String szDstBuf, 
    int iDstBufSize
    );


DESCRIPTION

Returns the object structure location for the current object. This will be returned in the programmer supplied buffer. The buffer contents are undefined on return if there is an error. If the location in structure will not fit into the buffer a truncation error is returned and the truncated value placed in the buffer. The truncated value will not be usable as a location identifier for the desired object, but depending on the truncation point may reference another object. It is therefore important that the return code is checked.

PARAMETERS

ID Type Description
pObjectPtr AIC_ObjectPtr Pointer to object in result set
szDstBuf AIC_String Text buffer for response
iDstBufSize int Size of your text buffer

RETURN VALUE

AIC_OK

The operation succeeded

AIC_NOK

An error occurred

AIC_NULL_POINTER_ARG

Null pointer argument supplied to function

AIC_NULL_ATTRIBUTE_POINTER

Got an attribute pointer which is null

AIC_OBJ_TYPE_MISMATCH

Trying the call a value set function on the wrong type of object

AIC_NOT_FOUND

The named object was not found

EXAMPLE


iStatus = AIC_GetLocationInStructure(
    pObjectPtr, szBuffer, sizeof(szBuffer)
    );


Previous section.

NAME

AIC_GetNextObject

SYNOPSIS


#include <libaic.h>

int AIC_GetNextObject ( 
    AIC_ListPtr pList, 
    AIC_Bool bFirstCall, 
    AIC_ObjectPtr *pObjectPtr
    );


DESCRIPTION

Gets the next object from the result set. If you pass TRUE as the value of bFirstCall, then the internal cursor is reset to the beginning of the result set. Otherwise it moves onto the next in the set and gives you a pointer to that next object. All of the functions for accessing individual object attributes for objects in the result must use an object pointer returned from this function. An error will be returned if the supplied pointer is NULL, but the results of this function are undefined if a list pointer that is not initialised by one AIC_Dump(), AIC_Traverse() or AIC_List() is supplied as a parameter.

PARAMETERS

ID Type Description
pList AIC_ListPtr Pointer to a list of results
bFirstCall AIC_Bool Is this the first call? Pass:
AIC_TRUE
AIC_FALSE
AIC_ObjectPtr AIC_ObjectPtr * Pointer to the object that is returned

RETURN VALUE

AIC_OK

The operation succeeded

AIC_NOK

An error occurred

AIC_NULL_POINTER_ARG

Null pointer argument supplied to function

AIC_END_OF_LIST

End of list reached

EXAMPLE



/* work out longest string */

pSaveList=pList;
iFirst = AIC_TRUE;
iLongestLocation=-1;
do
{
    iStatus = AIC_GetNextObject(pList,iFirst,&pObjectPtr );
    iStatus = AIC_GetLocationInStructure(
        pObjectPtr,szBuffer, sizeof(szBuffer)
        );
    iLocationLen=strlen(szBuffer);
    if (iLocationLen>iLongestLocation)
        iLongestLocation=iLocationLen;
    iFirst=AIC_FALSE;
} while (iStatus == AIC_OK);


Previous section.

NAME

AIC_GetRegFunctions

SYNOPSIS


#include <libaic.h>

int AIC_GetRegFunctions ( 
    AIC_ObjectPtr *pObjectPtr,
    AIC_String szPollingBuf,  
    int iPollBufSize,
    AIC_String szThresholdBuf,
    int iThreshBufSize,
    AIC_String szDoActionBuf, 
    int iActionBufSize
    );


DESCRIPTION

This call allows you to determine if a function has been registered against an object. If a function has been registered, you get the description supplied when the function was registered. If no function of that type is registered, the text "*" will be returned in the supplied buffer (which means not registered).

PARAMETERS

ID Type Description
pObjectPtr AIC_ObjectPtr Pointer to object in result set
szPollingBuf AIC_String Buffer for function description
iPollBufSize int Size of Polling buffer
szThresholdBuf AIC_String Buffer for function description
iThreshBufSize int Size of Threshold buffer
szDoActionBuf AIC_String Buffer for function description
iActionBufSize int Size of doAction buffer

RETURN VALUE

AIC_OK

The operation succeeded

AIC_NOK

An error occurred

AIC_UNEXPECTED_FUNC_RES

Unexpected function return type

AIC_TIMEOUT

Timeout on request to remote application

AIC_NULL_POINTER_ARG

Null pointer argument supplied to function

AIC_IN_STRUC_NAME_SHORT

The location in structure name is too short to be a sensible name

AIC_BADLY_FORMED_LOCATIONSTRING

Something wrong with the supplied location in structure string

AIC_CANT_ALLOCATE_MEMORY

General failure to allocate memory

AIC_HOST_NAME_TOO_LONG

Trying to get short version of a fully qualified name which is too long

AIC_APP_NAME_TOO_LONG

The application name is too long.

EXAMPLE


iStatus = AIC_GetRegFunctions(
    pObjectPtr,
    bufPolling, sizeof(bufPolling),
    bufThreshold, sizeof(bufThreshold),
    bufAction, sizeof(bufAction)
    );


Previous section.

NAME

AICCL_GetRegFunctions, AICAL_GetRegFunctions

SYNOPSIS


#include <libaic.h>

int AICCL_GetRegFunctions ( 
    AIC_String szLocation_in_structure, 
    AIC_String szPollingBuf,  
    int iPollBufSize,
    AIC_String szThresholdBuf,
    int iThreshBufSize,
    AIC_String szDoActionBuf, 
    int iActionBufSize
    );

int AICAL_GetRegFunctions ( 
    AIC_String szLocation_in_structure, 
    AIC_String szPollingBuf,  
    int iPollBufSize,
    AIC_String szThresholdBuf,
    int iThreshBufSize,
    AIC_String szDoActionBuf, 
    int iActionBufSize
    );


DESCRIPTION

This call allows you to determine if a function has been registered against an object. If a function has been registered, you get the description supplied when the function was registered. If no function of that type is registered, the text "*" will be returned in the supplied buffer (which means not registered).

PARAMETERS

ID Type Description
szLocation_in_structure AIC_String Full object tree location specification
szPollingBuf AIC_String Buffer for function description
iPollBufSize int Size of Polling buffer
szThresholdBuf AIC_String Buffer for function description
iThreshBufSize int Size of Threshold buffer
szDoActionBuf AIC_String Buffer for function description
iActionBufSize int Size of doAction buffer

RETURN VALUE

AIC_OK

The operation succeeded

AIC_NOK

An error occurred

AIC_UNEXPECTED_FUNC_RES

Unexpected function return type

AIC_TIMEOUT

Timeout on request to remote application

AIC_NULL_POINTER_ARG

Null pointer argument supplied to function

AIC_IN_STRUC_NAME_SHORT

The location in structure name is too short to be a sensible name

AIC_BADLY_FORMED_LOCATIONSTRING

Something wrong with the supplied location in structure string

AIC_CANT_ALLOCATE_MEMORY

General failure to allocate memory

AIC_HOST_NAME_TOO_LONG

Trying to get short version of a fully qualified name which is too long

AIC_APP_NAME_TOO_LONG

The application name is too long.

EXAMPLE


iStatus = AICCL_GetRegFunctions(
    query_location,
    bufPolling, sizeof(bufPolling),
    bufThreshold, sizeof(bufThreshold),
    bufAction, sizeof(bufAction)
    );


Previous section.

NAME

AICAL_GetSecurityDoAction, AICCL_GetSecurityDoAction

SYNOPSIS


#include <libaic.h>

int AICAL_GetSecurityDoAction ( 
    AIC_String szLocation_in_structure, 
    AIC_SecurityLevel *peDstSecLevel
    ); 

int AICCL_GetSecurityDoAction ( 
    AIC_String szLocation_in_structure, 
    AIC_SecurityLevel *peDstSecLevel
    );


DESCRIPTION

Requests the security level required to invoke a callback (DoAction) which has been registered at the given object location. The default set security of an object is denied and the application programmer needs to change this before external access is allowed - the application programmer always has ultimate control over object creation, deletion and maintenance.

PARAMETERS

ID Type Description
szLocation_in_structure AIC_String Full object tree location specification
PeDstSecLevel AIC_SecurityLevel * Variable to hold the result

RETURN VALUE

AIC_OK

The operation succeeded

AIC_NOK

An error occurred

AIC_UNEXPECTED_FUNC_RES

Unexpected function return type

AIC_TIMEOUT

Timeout on request to remote application

AIC_NULL_POINTER_ARG

Null pointer argument supplied to function

AIC_IN_STRUC_NAME_SHORT

The location in structure name is too short to be a sensible name

AIC_BADLY_FORMED_LOCATIONSTRING

Something wrong with the supplied location in structure string

AIC_CANT_ALLOCATE_MEMORY

General failure to allocate memory

AIC_HOST_NAME_TOO_LONG

Trying to get short version of a fully qualified name which is too long

AIC_APP_NAME_TOO_LONG

The application name is too long.

EXAMPLE


iStatus = AICAL_GetSecurityDoAction(query_location,&eSecLevel);


Previous section.

NAME

AICAL_GetSecurityGet, AICCL_GetSecurityGet

SYNOPSIS


#include <libaic.h>

int AICAL_GetSecurityGet ( 
    AIC_String szLocation_in_structure, 
    AIC_SecurityLevel *peDstSecLevel
    );

int AICCL_GetSecurityGet ( 
    AIC_String szLocation_in_structure, 
    AIC_SecurityLevel *peDstSecLevel
    );


DESCRIPTION

Requests the current permission required to get an attribute of the object. Note that the default value of the security get attribute is set by default to enable get access. If the application programmer chooses to change this default value, it may not be possible to access this or any other attribute of the object from outside of the application. Internal to the application, the programmer can continue to access the objects freely.

PARAMETERS

ID Type Description
szLocation_in_structure AIC_String Full object tree location specification
PeDstVisibility AIC_Visibility * Variable to hold the result

RETURN VALUE

AIC_OK

The operation succeeded

AIC_NOK

An error occurred

AIC_UNEXPECTED_FUNC_RES

Unexpected function return type

AIC_TIMEOUT

Timeout on request to remote application

AIC_NULL_POINTER_ARG

Null pointer argument supplied to function

AIC_IN_STRUC_NAME_SHORT

The location in structure name is too short to be a sensible name

AIC_BADLY_FORMED_LOCATIONSTRING

Something wrong with the supplied location in structure string

AIC_CANT_ALLOCATE_MEMORY

General failure to allocate memory

AIC_HOST_NAME_TOO_LONG

Trying to get short version of a fully qualified name which is too long

AIC_APP_NAME_TOO_LONG

The application name is too long.

EXAMPLE


iStatus = AICAL_GetSecurityGet(query_location,&eSecLevel);


Previous section.

NAME

AICAL_GetSecuritySet, AICCL_GetSecuritySet

SYNOPSIS


#include <libaic.h>

int AICAL_GetSecuritySet ( 
    AIC_String szLocation_in_structure, 
    AIC_SecurityLevel *peDstSecLevel
    );

int AICCL_GetSecuritySet ( 
    AIC_String szLocation_in_structure, 
    AIC_SecurityLevel *peDstSecLevel
    );


DESCRIPTION

Requests the security level required to externally perform a set on the value of this object in the object structure. The default value is denied, which means that no external set operations are allowed on any attributes of the object.

PARAMETERS

ID Type Description
szLocation_in_structure AIC_String Full object tree location specification
PeDstVisibility AIC_Visibility * Variable to hold the result

RETURN VALUE

AIC_OK

The operation succeeded

AIC_NOK

An error occurred

AIC_UNEXPECTED_FUNC_RES

Unexpected function return type

AIC_TIMEOUT

Timeout on request to remote application

AIC_NULL_POINTER_ARG

Null pointer argument supplied to function

AIC_IN_STRUC_NAME_SHORT

The location in structure name is too short to be a sensible name

AIC_BADLY_FORMED_LOCATIONSTRING

Something wrong with the supplied location in structure string

AIC_CANT_ALLOCATE_MEMORY

General failure to allocate memory

AIC_HOST_NAME_TOO_LONG

Trying to get short version of a fully qualified name which is too long

AIC_APP_NAME_TOO_LONG

The application name is too long.

EXAMPLE


iStatus = AICAL_GetSecuritySet(query_location,&eSecLevel);


Previous section.

NAME

AICAL_GetSemantics, AICCL_GetSemantics

SYNOPSIS


#include <libaic.h>

int AICAL_GetSemantics ( 
    AIC_String szLocation_in_structure, 
    AIC_String szDstBuf, 
    int iDstBufSize
    ); 

int AICCL_GetSemantics ( 
    AIC_String szLocation_in_structure, 
    AIC_String szDstBuf, 
    int iDstBufSize
    );


DESCRIPTION

Requests the semantics property of an object. The value is returned in an application programmer specified buffer, of a size given by iDstBufSize. If the returned value is too large for the specified buffer, a truncated value is returned with the appropriate return code.

PARAMETERS

ID Type Description
szLocation_in_structure AIC_String Full object tree location specification
szDstBuf AIC_String Character buffer for result
iDstBufSize int Size of result buffer

RETURN VALUE

AIC_OK

The operation succeeded

AIC_NOK

An error occurred

AIC_UNEXPECTED_FUNC_RES

Unexpected function return type

AIC_TIMEOUT

Timeout on request to remote application

AIC_NULL_POINTER_ARG

Null pointer argument supplied to function

AIC_IN_STRUC_NAME_SHORT

The location in structure name is too short to be a sensible name

AIC_BADLY_FORMED_LOCATIONSTRING

Something wrong with the supplied location in structure string

AIC_CANT_ALLOCATE_MEMORY

General failure to allocate memory

AIC_HOST_NAME_TOO_LONG

Trying to get short version of a fully qualified name which is too long

AIC_APP_NAME_TOO_LONG

The application name is too long.

EXAMPLE


iStatus = AICAL_GetSemantics (query_location, szValue, sizeof(szValue));


Previous section.

NAME

AICAL_GetStatus, AICCL_GetStatus

SYNOPSIS


#include <libaic.h>

int AICAL_GetStatus ( 
    AIC_String szLocation_in_structure, 
    AIC_Status *peDstStatus
    ); 

int AICCL_GetStatus ( 
    AIC_String szLocation_in_structure, 
    AIC_Status *peDstStatus
    );


DESCRIPTION

Requests the status value of the named object.

PARAMETERS

ID Type Description
szLocation_in_structure AIC_String Full object tree location specification
PeDstStatus AIC_Status * Variable to hold the result

RETURN VALUE

AIC_OK

The operation succeeded

AIC_NOK

An error occurred

AIC_NULL_POINTER_ARG

Null pointer argument supplied to function

AIC_UNEXPECTED_FUNC_RES

Unexpected function return type

AIC_TIMEOUT

Timeout on request to remote application

AIC_NULL_POINTER_ARG

Null pointer argument supplied to function

AIC_IN_STRUC_NAME_SHORT

The location in structure name is too short to be a sensible name

AIC_BADLY_FORMED_LOCATIONSTRING

A general problem with the location string

AIC_CANT_ALLOCATE_MEMORY

General failure to allocate memory

AIC_HOST_NAME_TOO_LONG

Trying to get short version of a fully qualified name which is too long

AIC_APP_NAME_TOO_LONG

The application name is too long.

EXAMPLE


iStatus = AICAL_GetStatus(query_location,&eObjectStatus);


Previous section.

NAME

AICCL_GetThreshSemantics, AICAL_GetThreshSemantics

SYNOPSIS


#include <libaic.h>

int AICCL_GetThreshSemantics ( 
    AIC_String szLocation_in_structure, 
    AIC_String szDstBuf, 
    int iDstBufSize
    );

int AICAL_GetThreshSemantics ( 
    AIC_String szLocation_in_structure, 
    AIC_String szDstBuf, 
    int iDstBufSize
    );


DESCRIPTION

Requests the Threshold semantics property of an object. The value is returned in an application programmer specified buffer, of a size given by iDstBufSize. If the returned value is too large for the specified buffer, a truncated value is returned with the appropriate return code.

PARAMETERS

ID Type Description
szLocation_in_structure AIC_String Full object tree location specification
szDstBuf AIC_String Character buffer for result
iDstBufSize int Size of result buffer

RETURN VALUE

AIC_OK

The operation succeeded

AIC_NOK

An error occurred

AIC_UNEXPECTED_FUNC_RES

Unexpected function return type

AIC_TIMEOUT

Timeout on request to remote application

AIC_NULL_POINTER_ARG

Null pointer argument supplied to function

AIC_IN_STRUC_NAME_SHORT

The location in structure name is too short to be a sensible name

AIC_BADLY_FORMED_LOCATIONSTRING

Something wrong with the supplied location in structure string

AIC_CANT_ALLOCATE_MEMORY

General failure to allocate memory

AIC_HOST_NAME_TOO_LONG

Trying to get short version of a fully qualified name which is too long

AIC_APP_NAME_TOO_LONG

The application name is too long.

EXAMPLE


iStatus = AICCL_GetThreshSemantics (
    query_location, szValue, sizeof(szValue)
    );


Previous section.

NAME

AICAL_GetThresholdDateAndTime, AICCL_GetThresholdDateAndTime

SYNOPSIS


#include <libaic.h>

int AICAL_GetThresholdDateAndTime ( 
    AIC_String szLocation_in_structure, 
    AIC_DateAndTime *sValue, 
    AIC_ThresholdType eWhichThreshold 
    );

int AICCL_GetThresholdDateAndTime ( 
    AIC_String szLocation_in_structure, 
    AIC_DateAndTime *sValue, 
    AIC_ThresholdType eWhichThreshold 
    );


DESCRIPTION

GetThresholdDateAndTime() is used to get one of the four date and time thresholds associated with a AICBusDateAndTime object. The threshold is identified with the parameter eWhichThreshold, and its value is returned into the area of memory pointed to by sValue. The application programmer is responsible for allocating the memory for the return value or providing the address of a local variable.

PARAMETERS

ID Type Description
szLocation AIC_String Location in the object tree
sValue AIC_DateAndTime * Pointer to a memory location which will hold the returned date and time information
eWhichThreshold AIC_ThresholdType Which one of the four thresholds to get

RETURN VALUE

AIC_OK

The operation succeeded

AIC_NOK

An error occurred

AIC_UNEXPECTED_FUNC_RES

Unexpected function return type

AIC_TIMEOUT

Timeout on request to remote application

AIC_NULL_POINTER_ARG

Null pointer argument supplied to function

AIC_IN_STRUC_NAME_SHORT

The location in structure name is too short to be a sensible name

AIC_BADLY_FORMED_LOCATIONSTRING

Something wrong with the supplied location in structure string

AIC_CANT_ALLOCATE_MEMORY

General failure to allocate memory

AIC_HOST_NAME_TOO_LONG

Trying to get short version of a fully qualified name which is too long

AIC_APP_NAME_TOO_LONG

The application name is too long.

EXAMPLE


iStatus = AICAL_GetThresholdDateAndTime(
    query_location, &sValue, oneArgThld 
    );


Previous section.

NAME

AICAL_GetThresholdDouble AICCL_GetThresholdDouble

SYNOPSIS


#include <libaic.h>

int AICAL_GetThresholdDouble ( 
    AIC_String szLocation_in_structure, 
    AIC_Double *dValue, 
    AIC_ThresholdType eWhichThreshold 
    );

int AICCL_GetThresholdDouble ( 
    AIC_String szLocation_in_structure, 
    AIC_Double *dValue, 
    AIC_ThresholdType eWhichThreshold 
    );


DESCRIPTION

GetThresholdDouble() returns the value of the specified threshold for the object specified by the location in structure string. The object type must be AICBusDouble - any other type will return an error.

PARAMETERS

ID Type Description
szLocation AIC_String Location in the object tree
dValue AIC_Double * Pointer to a memory location which will hold the returned double value
eWhichThreshold AIC_ThresholdType Which one of the four thresholds to get

RETURN VALUE

AIC_OK

The operation succeeded

AIC_NOK

An error occurred

AIC_UNEXPECTED_FUNC_RES

Unexpected function return type

AIC_TIMEOUT

Timeout on request to remote application

AIC_NULL_POINTER_ARG

Null pointer argument supplied to function

AIC_IN_STRUC_NAME_SHORT

The location in structure name is too short to be a sensible name

AIC_BADLY_FORMED_LOCATIONSTRING

Something wrong with the supplied location in structure string

AIC_CANT_ALLOCATE_MEMORY

General failure to allocate memory

AIC_HOST_NAME_TOO_LONG

Trying to get short version of a fully qualified name which is too long

AIC_APP_NAME_TOO_LONG

The application name is too long.

AIC_VALUE_OVERFLOW

Data overflow

EXAMPLE


iStatus = AICAL_GetThresholdDouble(
    query_location, &dValue, oneArgThld 
    );


Previous section.

NAME

AICAL_GetThresholdLong, AICCL_GetThresholdLong

SYNOPSIS


#include <libaic.h>

int AICAL_GetThresholdLong ( 
    AIC_String szLocation_in_structure, 
    AIC_Long *lValue, 
    AIC_ThresholdType eWhichThreshold 
    );

int AICCL_GetThresholdLong ( 
    AIC_String szLocation_in_structure, 
    AIC_Long *lValue, 
    AIC_ThresholdType eWhichThreshold 
    );


DESCRIPTION

GetThresholdLong() returns the value of the specified threshold for the object specified by the location in structure string. The object type must be AICBusLong - any other type will return an error.

PARAMETERS

ID Type Description
szLocation AIC_String Location in the object tree
lValue AIC_Long * Pointer to a memory location which will hold the returned long value
eWhichThreshold AIC_ThresholdType Which one of the four thresholds to get

RETURN VALUE

AIC_OK

The operation succeeded

AIC_NOK

An error occurred

AIC_UNEXPECTED_FUNC_RES

Unexpected function return type

AIC_TIMEOUT

Timeout on request to remote application

AIC_NULL_POINTER_ARG

Null pointer argument supplied to function

AIC_IN_STRUC_NAME_SHORT

The location in structure name is too short to be a sensible name

AIC_BADLY_FORMED_LOCATIONSTRING

Something wrong with the supplied location in structure string

AIC_CANT_ALLOCATE_MEMORY

General failure to allocate memory

AIC_HOST_NAME_TOO_LONG

Trying to get short version of a fully qualified name which is too long

AIC_APP_NAME_TOO_LONG

The application name is too long.

AIC_VALUE_OVERFLOW

Data overflow

EXAMPLE


iStatus = AICAL_GetThresholdLong(
    query_location, &lValue, oneArgThld 
    );


Previous section.

NAME

AICAL_GetValueDateAndTime, AICCL_GetValueDateAndTime

SYNOPSIS


#include <libaic.h>

int AICAL_GetValueDateAndTime ( 
    AIC_String szLocation_in_structure, 
    AIC_DateAndTime *ptDstDateTime
    ); 

int AICCL_GetValueDateAndTime ( 
    AIC_String szLocation_in_structure, 
    AIC_DateAndTime *ptDstDateTime
    );


DESCRIPTION

Returns the value of the nominated AICBusDateAndTime object. This call is only applicable to this type of object, and will return with an error code and an undefined result in the provided memory location.

PARAMETERS

ID Type Description
szLocation_in_structure AIC_String Full object tree location specification
ptDstDateTime AIC_DateAndTime Character buffer for result

RETURN VALUE

AIC_OK

The operation succeeded

AIC_NOK

An error occurred

AIC_UNEXPECTED_FUNC_RES

Unexpected function return type

AIC_TIMEOUT

Timeout on request to remote application

AIC_NULL_POINTER_ARG

Null pointer argument supplied to function

AIC_IN_STRUC_NAME_SHORT

The location in structure name is too short to be a sensible name

AIC_BADLY_FORMED_LOCATIONSTRING

Something wrong with the supplied location in structure string

AIC_CANT_ALLOCATE_MEMORY

General failure to allocate memory

AIC_HOST_NAME_TOO_LONG

Trying to get short version of a fully qualified name which is too long

AIC_APP_NAME_TOO_LONG

The application name is too long.

EXAMPLE


iStatus = AICAL_GetValueDateAndTime(query_location, &sValue);


Previous section.

NAME

AICAL_GetValueDouble, AICCL_GetValueDouble

SYNOPSIS


#include <libaic.h>

int AICAL_GetValueDouble ( 
    AIC_String szLocation_in_structure, 
    AIC_Double *pdDstValue
    );

int AICCL_GetValueDouble ( 
    AIC_String szLocation_in_structure, 
    AIC_Double *pdDstValue
    );


DESCRIPTION

Returns the value of the object nominated. This call is only applicable to objects of type AICBusDouble and will generate an error if the nominated object is of another type. If the operation is not successful, the contents of the area of memory for the return value will be undefined.

PARAMETERS

ID Type Description
szLocation_in_structure AIC_String Full object tree location specification
pdDstValue AIC_Double Variable to hold the result

RETURN VALUE

AIC_OK

The operation succeeded

AIC_NOK

An error occurred

AIC_UNEXPECTED_FUNC_RES

Unexpected function return type

AIC_TIMEOUT

Timeout on request to remote application

AIC_NULL_POINTER_ARG

Null pointer argument supplied to function

AIC_IN_STRUC_NAME_SHORT

The location in structure name is too short to be a sensible name

AIC_BADLY_FORMED_LOCATIONSTRING

Something wrong with the supplied location in structure string

AIC_CANT_ALLOCATE_MEMORY

General failure to allocate memory

AIC_HOST_NAME_TOO_LONG

Trying to get short version of a fully qualified name which is too long

AIC_APP_NAME_TOO_LONG

The application name is too long.

AIC_VALUE_OVERFLOW

Data overflow

EXAMPLE


iStatus = AICAL_GetValueDouble(query_location, &dValue);


Previous section.

NAME

AICAL_GetValueLong, AICCL_GetValueLong

SYNOPSIS


#include <libaic.h>

int AICAL_GetValueLong ( 
    AIC_String szLocation_in_structure, 
    AIC_Long *plDstValue
    );

int AICCL_GetValueLong ( 
    AIC_String szLocation_in_structure, 
    AIC_Long *plDstValue
    );


DESCRIPTION

Requests the value of an AICBusLong object as named by the location in structure string. This call only works on an AICBusLong object, and will return an error code if called with any other type of object. If the call fails, the contents of the area of memory pointed to by plDstValue are undefined.

PARAMETERS

ID Type Description
szLocation_in_structure AIC_String Full object tree location specification
PlDstValue AIC_Long Long for the result

RETURN VALUE

AIC_OK

The operation succeeded

AIC_NOK

An error occurred

AIC_UNEXPECTED_FUNC_RES

Unexpected function return type

AIC_TIMEOUT

Timeout on request to remote application

AIC_NULL_POINTER_ARG

Null pointer argument supplied to function

AIC_IN_STRUC_NAME_SHORT

The location in structure name is too short to be a sensible name

AIC_BADLY_FORMED_LOCATIONSTRING

Something wrong with the supplied location in structure string

AIC_CANT_ALLOCATE_MEMORY

General failure to allocate memory

AIC_HOST_NAME_TOO_LONG

Trying to get short version of a fully qualified name which is too long

AIC_APP_NAME_TOO_LONG

The application name is too long.

AIC_VALUE_OVERFLOW

Data overflow

EXAMPLE


iStatus = AICAL_GetValueLong(query_location, &lValue);


Previous section.

NAME

AICAL_GetValueVarChar, AICCL_GetValueVarChar

SYNOPSIS


#include <libaic.h>

int AICAL_GetValueVarChar ( 
    AIC_String szLocation_in_structure, 
    AIC_String szDstBuf, 
    int iDstBufSize
    ); 

int AICCL_GetValueVarChar ( 
    AIC_String szLocation_in_structure, 
    AIC_String szDstBuf, 
    int iDstBufSize
    );


DESCRIPTION

Requests the value of an AICBusVarChar object. The value is returned in an application programmer specified buffer, of a size given by iDstBufSize. If the returned value is too large for the specified buffer, a truncated value is returned with the appropriate return code. If this call is applied to an object of some type other than AICBusVarChar, the value returned in the buffer is undefined.

PARAMETERS

ID Type Description
szLocation_in_structure AIC_String Full object tree location specification
szDstBuf AIC_String Character buffer for result
iDstBufSize int Size of result buffer

RETURN VALUE

AIC_OK

The operation succeeded

AIC_NOK

An error occurred

AIC_UNEXPECTED_FUNC_RES

Unexpected function return type

AIC_TIMEOUT

Timeout on request to remote application

AIC_NULL_POINTER_ARG

Null pointer argument supplied to function

AIC_IN_STRUC_NAME_SHORT

The location in structure name is too short to be a sensible name

AIC_BADLY_FORMED_LOCATIONSTRING

Something wrong with the supplied location in structure string

AIC_CANT_ALLOCATE_MEMORY

General failure to allocate memory

AIC_HOST_NAME_TOO_LONG

Trying to get short version of a fully qualified name which is too long

AIC_APP_NAME_TOO_LONG

The application name is too long.

EXAMPLE


iStatus = AICAL_GetValueVarChar(
    query_location, szValue, sizeof(szValue)
    );


Previous section.

NAME

AICAL_GetVisibility, AICCL_GetVisibility

SYNOPSIS


#include <libaic.h>

int AICAL_GetVisibility ( 
    AIC_String szLocation_in_structure, 
    AIC_Visibility *peDstVisibility
    );

int AICCL_GetVisibility ( 
    AIC_String szLocation_in_structure, 
    AIC_Visibility *peDstVisibility
    );


DESCRIPTION

Requests the visibility level of a given object. The visibility values correspond to a level of visibility within a management framework that may optionally be attached to AIC.

PARAMETERS

ID Type Description
szLocation_in_structure AIC_String Full object tree location specification
peDstVisibility AIC_Visibility * Variable to hold the result

RETURN VALUE

AIC_OK

The operation succeeded

AIC_NOK

An error occurred

AIC_NULL_POINTER_ARG

Null pointer argument supplied to function

AIC_TIMEOUT

Timeout on request to remote application

AIC_NULL_POINTER_ARG

Null pointer argument supplied to function

AIC_IN_STRUC_NAME_SHORT

The location in structure name is too short to be a sensible name

AIC_BADLY_FORMED_LOCATIONSTRING

Something wrong with the supplied location in structure string

AIC_CANT_ALLOCATE_MEMORY

General failure to allocate memory

AIC_HOST_NAME_TOO_LONG

Trying to get short version of a fully qualified name which is too long

AIC_APP_NAME_TOO_LONG

The application name is too long.

EXAMPLE


iStatus = AICAL_GetVisibility(query_location,&eDstVisibility);


Previous section.

NAME

AIC_IsTimeStmpNull

SYNOPSIS


#include <libaic.h>

int AIC_IsTimeStmpNull ( 
    AIC_DateAndTime *pDateTimeStmp
    );


DESCRIPTION

Returns 1 (yes) or 0 (no) if the passed time stamp is a NULL value. An invalid value is also considered NULL.

PARAMETERS

ID Type Description
pDateTimeStmp AIC_DateAndTime * Address of DateTime variable

RETURN VALUE

AIC_FALSE

The time stamp is non-null

AIC_TRUE

The time stamp is null

EXAMPLE


if (AIC_IsTimeStmpNull(pdATime))
{
    printf("Time null");
};


Previous section.

NAME

AICAL_LibStart

SYNOPSIS


#include <libaic.h>

int AICAL_LibStart ( 
    AIC_String szRequestedName, 
    AIC_AutomaticName eApplicationNaming, 
    AIC_OpenType eOpenedBy, 
    AIC_String szDerivedName, 
    int iDerivedNameSize
    );


DESCRIPTION

Starts the AIC library in the application. The application requests a specific name in the szRequestedName parameter. Regardless of the value of the eApplicationNaming parameter (in this specification), the application is allocated this name if no other application is currently using it. If it is allocated, a modified name will be allocated to the application - see Rules for Assigning Names, Unique Name Generator.

The requested name can have the format <application name>:<process name> (called federated naming, see Federated Process Naming, Federated Process Naming).

The eOpenedBy parameter is for upward compatibility, and is intended for use when AIC can be invoked from independent libraries within an application. At that time, the defined behaviour will be that any number of libraries can invoke AIC, but only one main program. If the AIC-AL is closed by the main program, it will be closed completely. If it is closed by an instance of a library, it will not be closed finally until all library instances issue a close or the main program does. This allows for the possibility of AIC enabled libraries to be supplied seamlessly into a product that is already AIC enabled.

PARAMETERS

ID Type Description
szRequestedName AIC_String Name requested at registration with AICd
eApplicationNaming AIC_AutomaticName Type of name requested. Currently, the specification makes no distinction between these two options:
fixed
generated
eOpenedBy AIC_OpenType This indicates whether the AIC-AL is being initialised by a library or the main program of an application. Currently only the main program option is required in this standard. Options:
mainProgram
Library
szDerivedName AIC_String Buffer to receive name assigned by AIC
iDerivedNameSize Int Size of buffer for received name

RETURN VALUE

AIC_OK

The operation succeeded

AIC_NOK

An error occurred

AIC_NOT_SUPPORTED

Functionality not currently supported

AIC_ENUMORD_OUTOF_RANGE

The ordinal value of a supplied enum is outside of range

AIC_CANT_ALLOCATE_MEMORY

General failure to allocate memory

AIC_CANT_INITIALISE_CAM

Trying to initialise the CAM connection and failing

AIC_THREAD_CREATE_FAILED

Thread creation failed in library initialisation

AIC_LIB_INITIALISED

The call to LibStart has already been made

EXAMPLE


iStatus = AICAL_LibStart("FXrates", fixed, mainProgram,
          szTemp, sizeof(szTemp) );


Previous section.

NAME

AICAL_List, AICCL_List

SYNOPSIS


#include <libaic.h>

int AICAL_List ( 
    AIC_String szLocation-in-structure, 
    AIC_ListPtr *ppDstListPtr
    );

int AICCL_List ( 
    AIC_String szLocation-in-structure, 
    AIC_ListPtr *ppDstListPtr
    );


DESCRIPTION

Performs a query against the object "tree"3 and returns values horizontally across the tree without going down branches of it. The starting point for the query is given by the location in structure, and must be the full name of an object at the desired level in the implied tree. For example, supplying the name /a/b will find all objects which have the name /a/* where * is a single symbol with no further / delimeters present. The resultant object list is copied into space allocated by AIC. The list can be traversed repeatedly by AIC_GetNextObject(). When the list is no longer required it is freed by AIC_FreeMemory(). No other means of accessing this list are available to the application programmer.

PARAMETERS

ID Type Description
szLocation_in_structure AIC_String Full object tree location specification
ppDstListPtr AIC_ListPtr Pointer to a list of results

RETURN VALUE

AIC_OK

The operation succeeded

AIC_NOK

An error occurred

AIC_NULL_POINTER_ARG

Null pointer argument supplied to function

AIC_TIMEOUT

Timeout on request to remote application

AIC_NULL_POINTER_ARG

Null pointer argument supplied to function

AIC_IN_STRUC_NAME_SHORT

The location in structure name is too short to be a sensible name

AIC_BADLY_FORMED_LOCATIONSTRING

Something wrong with the supplied location in structure string

AIC_CANT_ALLOCATE_MEMORY

General failure to allocate memory

AIC_HOST_NAME_TOO_LONG

Trying to get short version of a fully qualified name which is too long

AIC_APP_NAME_TOO_LONG

The application name is too long.

EXAMPLE


int             iStatus;
AIC_ListPtr     pList;

iStatus = AICAL_List(query_location, &pList);


Previous section.

NAME

AICAL_QueryObjectType, AICCL_QueryObjectType

SYNOPSIS


#include <libaic.h>

int AICAL_QueryObjectType ( 
    AIC_String szLocation_in_structure, 
    AIC_ObjectType *peObjectType
    ); 

int AICCL_QueryObjectType ( 
    AIC_String szLocation_in_structure, 
    AIC_ObjectType *peObjectType
    );


DESCRIPTION

Requests the object type of the nominated object. In the case of an error, the returned object type is undefined. The object type can be one of the following four values: AICBusLong, AICBusDouble, AICBusDateAndTime and AICBusVarChar. This function is important because all AIC functions for accessing values and thresholds are strongly typed. The application programmer must either know the type of an object or request it with this function in order to call the correct type specific function.

PARAMETERS

ID Type Description
szLocation_in_structure AIC_String Full object tree location specification
peObjectType AIC_ObjectType * Variable to hold the result

RETURN VALUE

AIC_OK

The operation succeeded

AIC_NOK

An error occurred

AIC_UNEXPECTED_FUNC_RES

Unexpected function return type

AIC_TIMEOUT

Timeout on request to remote application

AIC_NULL_POINTER_ARG

Null pointer argument supplied to function

AIC_IN_STRUC_NAME_SHORT

The location in structure name is too short to be a sensible name

AIC_BADLY_FORMED_LOCATIONSTRING

Something wrong with the supplied location in structure string

AIC_CANT_ALLOCATE_MEMORY

General failure to allocate memory

AIC_HOST_NAME_TOO_LONG

Trying to get short version of a fully qualified name which is too long

AIC_APP_NAME_TOO_LONG

The application name is too long.

EXAMPLE


iStatus = AICCL_QueryObjectType(query_location,&eObjectType);


Previous section.

NAME

AICAL_RaiseEvent

SYNOPSIS


#include <libaic.h>

int AICAL_RaiseEvent ( 
    AIC_String szMessage, 
    AIC_String szSourceDetail, 
    AIC_String szCategory, 
    AIC_String szEventId, 
    AIC_EventDestination eDst,
    int iSeverity
    ); 


DESCRIPTION

Raise event requests that an event be raised on behalf of the application programmer. At a minimum, this requires that the event be logged locally to file. Additionally, if there is a connection to a management framework that supports the concept of events, this will also receive a copy of the event. See AIC Events for details on the parameters and their purpose.

PARAMETERS

ID Type Description
szMessage AIC_String Error Message
szSourceDetail AIC_String Optional text field
szCategory AIC_String Optional text field
szEventId AIC_String Optional text field
eDst AIC_EventDestination Where to send event. Valid values:
ALERT - send to management framework
LOGONLY - log to persistent storage only
iSeverity int Severity of alert. Range from 1 to 4 where 1 is the highest and 4 the lowest severity.

RETURN VALUE

AIC_OK

The operation succeeded

AIC_NOK

An error occurred

AIC_ENUMORD_OUTOF_RANGE

The ordinal value of a supplied enum is outside of range

AIC_EVENT_MESSAGE_MANDATORY

A raise event request does not have a message associated with it.

EXAMPLE


iStatus = AICAL_RaiseEvent("Cannot connect to DB", "Build2.5.1",
          "CTLIB", "CT100", ALERT, 1);


Previous section.

NAME

AICAL_RegDoAction

SYNOPSIS


#include <libaic.h>

int AICAL_RegDoAction ( 
    AIC_String szLocation_in_structure, 
    AIC_DoActionFunc pfDoAction,
    AIC_String szDescription
    );


DESCRIPTION

Registers a generic callback function against a given object in the object structure. The generic callback takes the location in structure and a string as parameters. When subsequently invoked on request, the callback is passed these two parameters. The callback can provide any functionality required by the application programmer, but will typically be used for remedial action in correcting application problems. The location in structure is provided as a parameter to give context to the DoAction function when it is called. It is the application programmer's responsibility to ensure that the callback is a reference to an existing function. This function can also be used to de-register a previously registered function by passing the function parameter as NULL. The text "*" cannot be used as a description as this string is reserved.

PARAMETERS

ID Type Description
szLocation_in_structure AIC_String Location in the object tree
pfDoAction AIM_DoActionFunc Pointer to the generic callback function
szDescription AIC_String Text description of what function does

RETURN VALUE

AIC_OK

The operation succeeded

AIC_NOK

An error occurred

AIC_NOT_FOUND

The named object was not found

AIC_RESERVED_WORD

A reserved word was used illegally

EXAMPLE


iStatus=AICAL_RegDoAction(
"/received",
    pfnDoAction,
    "Archive received data to disk, pass in path for file");

void pfnDoAction (AIC_String szLocation_in_structure,
                  char *szUserData,
                  int iUserDataLength)
{
    FILE   *fp;
    char   szTime[STRINGLEN];
    char   szFilename[STRINGLEN];
    struct tm tms;
    time_t t_now;

    strncpy(szFilename,szUserData,iUserDataLength);
    szFilename[iUserDataLength]=' ';
    printf("** Inside DoAction ... data passed=%s,  
           size=%d",szFilename,iUserDataLength);
    fp = fopen(szFilename,"a+");
    if (fp==NULL)
    {
        raise_error("Cannot open statistics file");
        printf("** Error writing to file ... aborted");
        return;
    }
    time(&t_now) ;
    memcpy( &tms, localtime(&t_now), sizeof( struct tm ) ) ;
    //- format time as,  YYYY/MM/DD-HH:MM:SS
    strftime( szTime, STRINGLEN, "%Y/%m/%d-%H:%M:%S", &tms ) ;
    fprintf(fp,"%s Received=%d, 
            processed=%d",szTime,iReceived,iProcessed);
    fclose(fp);      
    printf("** Data written out");
}


Previous section.

NAME

AICAL_RegPollSetValue

SYNOPSIS


#include <libaic.h>

int AICAL_RegPollSetValue ( 
    AIC_String szLocation_in_structure, 
    AIC_PollSetCallback pfPollSetCallback,
    AIC_String szDescription
);


DESCRIPTION

Registers a polling function with AIC for the given management object. The intention of a polling function is to update a management object on a regular basis. If a polling function is registered, it must be invoked by the AIC-AL on a regular interval which can be set by the application programmer. The time between the start of each polling cycle must be as close to the defined polling time as possible. For example, if a polling interval of 10 seconds starts at time 0, the next one should start as close as possible to time 10. Polling functions can be de-registered by supplying a NULL to this function instead of a function pointer. As far as possible, the implementation should protect an application from polling functions that have aberrant behaviour (for example accessing bad pointers or doing divide by zero operations). The implementation may also choose to specify upper and lower limits on polling time to ensure that AIC uses an acceptable proportion of machine resources. The text "*" cannot be used as a description as this string is reserved.

PARAMETERS

ID Type Description
szLocation_in_structure AIC_String Location in the object tree
pfPollSetCallback AIC_PollSetCallback Pointer to the polling function
szDescription AIC_String Text description of what function does

RETURN VALUE

AIC_OK

The operation succeeded

AIC_NOK

An error occurred

AIC_NOT_FOUND

The named object was not found

AIC_RESERVED_WORD

A reserved word was used illegally


ne 20

EXAMPLE


iStatus = AICAL_RegPollSetValue(
    szBuffer,
    pfnLongCallBack
    "Increment value");

void pfnLongCallBack (AIC_String szLocation_in_structure )
{
    long   lValue;
    int    iStatus;

    printf("**********************************");
    printf("****Inside pfnLongCallBack: %s****",
        szLocation_in_structure);
    printf("**********************************");
    iStatus = AICAL_GetValueLong( szLocation_in_structure, &lValue );
    lValue = lValue * 2;
    iStatus = AICAL_SetValueLong( szLocation_in_structure, lValue );
    return;
}


Previous section.

NAME

AICAL_RegThresholdFunction

SYNOPSIS


#include <libaic.h>

int AICAL_RegThresholdFunction ( 
    AIC_String szLocation_in_structure, 
    AIC_ThresholdFunction pfThresholdFunction,
    AIC_String szDescription
    );


DESCRIPTION

Registers a threshold function with AIC for the given management object. The intent of a threshold function is to update the status of a given management object on a regular basis. The status can be most useful if the AIC implementation is connected to a management framework, when it is expected that the status would be sent to this framework. The thresholding function should be called on the same polling cycle as the polling function (if either of them are registered). The threshold function can be de-registered by supplying NULL as the function argument. The text "*" cannot be used as a description as this string is reserved.

PARAMETERS

ID Type Description
szLocation_in_structure AIC_String Location in the object tree
pfThresholdFunction AIC_ThresholdFunction Pointer to the threshold function
szDescription AIC_String Text description of what function does

RETURN VALUE

AIC_OK

The operation succeeded

AIC_NOK

An error occurred

AIC_NOT_FOUND

The named object was not found

AIC_RESERVED_WORD

A reserved word was used illegally

EXAMPLE


iStatus = AICAL_RegThresholdFunction(
    szBuffer,
    pfnLongThreshold,
    "Compare Value to Threshold 1 and Set Status"
    );

void AIC_SimpleThresholdLong( AIC_String szLocation_in_structure )
{
    AIC_ObjectType eObjectType;
    AIC_Long lValue;
    AIC_Long lThresh1;
    //, lThresh2, lThresh3, lThresh4;
    int iErrorCode;

/* 
 Check that the type of object we are applying this function to 
 is the correct one. It will not cause AIC problems if the wrong
 type value is requested, but it will save time in this function.
*/
    iErrorCode = AICAL_QueryObjectType(
                 szLocation_in_structure,
                 &eObjectType 
                 );
    if (eObjectType != AICBusLong)
    {
        return;
    }
    /* Get the value of the object first */
    iErrorCode = AICAL_GetValueLong( 
        szLocation_in_structure, &lValue 
        );
    if (iErrorCode != AIC_OK)
    {
        return;
    }

    /* Get all the thresholds. This could be done */
    /* one threshold at a time for efficiency     */

    iErrorCode = AICAL_GetThresholdLong( 
        szLocation_in_structure, &lThresh1, oneArgThld
        );
    if (iErrorCode != AIC_OK)
    {
        return;
    }
    if (lValue < lThresh1)
    {
        iErrorCode = AICAL_SetStatus( 
            szLocation_in_structure, normal 
            );
        return;
    }
    else
    {
        iErrorCode = AICAL_SetStatus( 
            szLocation_in_structure, critical 
            );
        return;
    }

}


Previous section.

NAME

AICCL_RequestServicesStatistics

SYNOPSIS


#include <libaic.h>

int AICCL_RequestServicesStatistics ( 
    AIC_String szHostName, 
    char *szDstBuf, 
    int iDstBufSize
    );


DESCRIPTION

Requests the host service statistics from the specified host. The statistics are returned into a programmer supplied buffer as a formatted string. The current statistics collected are the number of set operations, the number of operations, the total operations, and the number of successful cache hits. These numbers can be slightly misleading unless you understand that they refer to successfully completed operations.

It is possible to have a number of requests generating zero statistics simply because there was some mistake in the parameters of one of the functions called previously (for example, the wrong location in structure being supplied). The statistics are designed to help when tuning the cache timeout for speed against accuracy of information. Speed is improved with long cache timeouts, but accuracy is improved with short time outs and the balance depends very much on requirements.

PARAMETERS

ID Type Description
SzHostName AIC_String Daemon host machine name
SzDstBuf Char * Buffer for statistics information
IDstBufSize Int Size of buffer for statistics information

RETURN VALUE

AIC_OK

The operation succeeded

AIC_NOK

An error occurred

AIC_LOCATION_NULL

The location name given is empty

AIC_STRING_SPACE_TOO_SMALL

Area of memory supplied to small for string.

AIC_UNEXPECTED_FUNC_RES

Unexpected function return type

AIC_TIMEOUT

Timeout on request to remote application

AIC_NULL_POINTER_ARG

Null pointer argument supplied to function

AIC_IN_STRUC_NAME_SHORT

The location in structure name is too short to be a sensible name

AIC_BADLY_FORMED_LOCATIONSTRING

Something wrong with the supplied location in structure string

AIC_CANT_ALLOCATE_MEMORY

General failure to allocate memory

AIC_HOST_NAME_TOO_LONG

Trying to get short version of a fully qualified name which is too long

AIC_APP_NAME_TOO_LONG

The application name is too long.

EXAMPLE


iStatus = AICCL_RequestServicesStatistics ("Krone", szBuffer, 100 );


Previous section.

NAME

AIC_SetLevel

SYNOPSIS


#include <libaic.h>

void AIC_SetLevel ( 
    int iLevel
    );


DESCRIPTION

Sets the debug level for AIC. This can be a value between -1 and 7. Higher numbers produce larger amounts of debug information. Normally, any level above 4 will generate too much debug information for anything more than casual inspection. Also this function is only effective against an AIC library compiled in DEBUG mode. This call should be used in conjunction with AIC_SetLogFileName() and AIC_ToScreen() to direct the additional information to the desired destination. Valid values are:

AIC_LOG_NONE
AIC_LOG_FATAL
AIC_LOG_CRITICAL
AIC_LOG_WARNING
AIC_LOG_INFO
AIC_LOG_DEBUG
AIC_LOG_DEBUG1
AIC_LOG_DEBUG2
AIC_LOG_DEBUG3

PARAMETERS

ID Type Description
Ilevel Int Debug level from list above

RETURN VALUE

None

EXAMPLE


iStatus = AIC_SetLevel(AIC_LOG_DEBUG);


Previous section.

NAME

AIC_SetLogFileName

SYNOPSIS


#include <libaic.h>

void AIC_SetLogFileName ( 
    char *pszLogFileName
    );


DESCRIPTION

Sets the filename for AIC logging, but is only effective when used against an AIC Library compiled in DEBUG mode. There is no default file name for a log file. This has to be set using this call.

PARAMETERS

ID Type Description
PszLogFileName char * Location and name of the file

RETURN VALUE

None

EXAMPLE


IStatus = AIC_SetLogFileName( "Newlog.log" );


Previous section.

NAME

AICAL_SetPollingTime

SYNOPSIS


#include <libaic.h>

int AIC_SetPollingTime ( 
    AIC_Long lPollingTime
    );


DESCRIPTION

This call sets the delay between the polling cycle of the application library. It is suggested that there should be range checking applied to the time interval, because a very short polling period could have the effect of taking processor cycles from the application (although this would depend on implementation and the specific operating system). Suggested starting values are 5 seconds as the minimum and 3600 as the maximum.

PARAMETERS

ID Type Description
LPollingTime AIC_Long Interval of the polling mechanism (seconds)

RETURN VALUE

AIC_OK

The operation succeeded

AIC_TIME_OUT_OF_RANGE

The time and date value is out of the allowed range

EXAMPLE


iStatus = AICAL_SetPollingTime(15);


Previous section.

NAME

AICCL_SetReceiveTimeOut

SYNOPSIS


#include <libaic.h>

int AICCL_SetReceiveTimeOut ( 
    int lTimeOut
    );


DESCRIPTION

This function sets the allowable delay before the API returns a timeout error - the client library may need to make access to an AIC installation across a network. The default value for timeout is 15. The API should also enforce a minimum value and a maximum value, but these are left to the specific implementation. Issues to be wary of are setting a timeout which is too short to allow a network transfer or too long to give efficient error reporting.

PARAMETERS

ID Type Description
LtimeOut Int Timeout value in seconds

RETURN VALUE

AIC_OK

The operation succeeded

AIC_TIME_OUT_OF_RANGE

The time and date value is out of the allowed range

EXAMPLE


iStatus = AICCL_SetReceiveTimeOut(35);


Previous section.

NAME

AICAL_SetSecurityDoAction, AICCL_SetSecurityDoAction

SYNOPSIS


#include <libaic.h>

int AICAL_SetSecurityDoAction ( 
    AIC_String szLocation=in=structure, 
    AIC_SecurityLevel eSecurityLevel
    );

int AICCL_SetSecurityDoAction ( 
    AIC_String szLocation=in=structure, 
    AIC_SecurityLevel eSecurityLevel
    );


DESCRIPTION

Sets the security level on an object for invoking the DoAction function of an object. This attribute can be set for all objects apart from those created by the AIC library internally. The default value of the security attribute for DoAction operations is denied, that is to enable the running of a DoAction function the application programmer must change this value from the default.

PARAMETERS

ID Type Description
szLocation_in_structure AIC_String Full object tree location specification
EsecurityLevel AIC_SecurityLevel New security level

RETURN VALUE

AIC_OK

The operation succeeded

AIC_NOK

An error occurred

AIC_ENUMORD_OUTOF_RANGE

The ordinal value of a supplied enum is outside of range

AIC_UNEXPECTED_FUNC_RES

Unexpected function return type

AIC_TIMEOUT

Timeout on request to remote application

AIC_NULL_POINTER_ARG

Null pointer argument supplied to function

AIC_IN_STRUC_NAME_SHORT

The location in structure name is too short to be a sensible name

AIC_BADLY_FORMED_LOCATIONSTRING

Something wrong with the supplied location in structure string

AIC_CANT_ALLOCATE_MEMORY

General failure to allocate memory

AIC_HOST_NAME_TOO_LONG

Trying to get short version of a fully qualified name which is too long

AIC_APP_NAME_TOO_LONG

The application name is too long.

EXAMPLE


iStatus=AICAL_SetSecurityDoAction(gQuery_location,eSecurityLevel);


Previous section.

NAME

AICAL_SetSecurityGet, AICCL_SetSecurityGet

SYNOPSIS


#include <libaic.h>

int AICAL_SetSecurityGet ( 
    AIC_String szLocation=in=structure, 
    AIC_SecurityLevel eSecurityLevel
    );

int AICCL_SetSecurityGet ( 
    AIC_String szLocation=in=structure, 
    AIC_SecurityLevel eSecurityLevel
    );


DESCRIPTION

Sets the security level required on an object for getting any of the object's attributes. This attribute can be set for all objects apart from those created by the AIC library internally. The default value of the security attribute for get operations allows for access to the object's attributes.

PARAMETERS

ID Type Description
szLocation_in_structure AIC_String Full object tree location specification
EsecurityLevel AIC_SecurityLevel New security level

RETURN VALUE

AIC_OK

The operation succeeded

AIC_NOK

An error occurred

AIC_ENUMORD_OUTOF_RANGE

The ordinal value of a supplied enum is outside of range

AIC_UNEXPECTED_FUNC_RES

Unexpected function return type

AIC_TIMEOUT

Timeout on request to remote application

AIC_NULL_POINTER_ARG

Null pointer argument supplied to function

AIC_IN_STRUC_NAME_SHORT

The location in structure name is too short to be a sensible name

AIC_BADLY_FORMED_LOCATIONSTRING

Something wrong with the supplied location in structure string

AIC_CANT_ALLOCATE_MEMORY

General failure to allocate memory

AIC_HOST_NAME_TOO_LONG

Trying to get short version of a fully qualified name which is too long

AIC_APP_NAME_TOO_LONG

The application name is too long.

EXAMPLE


iStatus=AICAL_SetSecurityGet(gQuery_location,eSecurityLevel);


Previous section.

NAME

AICAL_SetSecuritySet, AICCL_SetSecuritySet

SYNOPSIS


#include <libaic.h>

int AICAL_SetSecuritySet ( 
    AIC_String szLocation_in_structure, 
    AIC_SecurityLevel eSecurityLevel
    ); 

int AICCL_SetSecuritySet ( 
    AIC_String szLocation_in_structure, 
    AIC_SecurityLevel eSecurityLevel
    );


DESCRIPTION

Sets the security level on an object for set operations against all the attributes of the object. Note that the default value for the Security Set attribute is denied. This means that an application programmer must change this to allow any updates to the object's attributes.

PARAMETERS

ID Type Description
szLocation_in_structure AIC_String Full object tree location specification
eSecurityLevel AIC_SecurityLevel New security level

RETURN VALUE

AIC_OK

The operation succeeded

AIC_NOK

An error occurred

AIC_ENUMORD_OUTOF_RANGE

The ordinal value of a supplied enum is outside of range

AIC_UNEXPECTED_FUNC_RES

Unexpected function return type

AIC_TIMEOUT

Timeout on request to remote application

AIC_NULL_POINTER_ARG

Null pointer argument supplied to function

AIC_IN_STRUC_NAME_SHORT

The location in structure name is too short to be a sensible name

AIC_BADLY_FORMED_LOCATIONSTRING

Something wrong with the supplied location in structure string

AIC_CANT_ALLOCATE_MEMORY

General failure to allocate memory

AIC_HOST_NAME_TOO_LONG

Trying to get short version of a fully qualified name which is too long

AIC_APP_NAME_TOO_LONG

The application name is too long.

EXAMPLE


iStatus=AICCL_SetSecuritySet(gQuery_location, eSecurityLevel);


Previous section.

NAME

AICAL_SetSemantics

SYNOPSIS


#include <libaic.h>

int AICAL_SetSemantics ( 
    AIC_String szLocation_in_structure, 
    AIC_String szValue
    );


DESCRIPTION

Sets the semantics value of the given object to the value of the supplied AIC_String.

PARAMETERS

ID Type Description
szLocation_in_structure AIC_String Location in the object tree
szValue AIC_String String

RETURN VALUE

AIC_OK

The operation succeeded

AIC_NOK

An error occurred

AIC_ENUMORD_OUTOF_RANGE

The ordinal value of a supplied enum is outside of range

AIC_UNEXPECTED_FUNC_RES

Unexpected function return type

AIC_TIMEOUT

Timeout on request to remote application

AIC_NULL_POINTER_ARG

Null pointer argument supplied to function

AIC_IN_STRUC_NAME_SHORT

The location in structure name is too short to be a sensible name

AIC_BADLY_FORMED_LOCATIONSTRING

Something wrong with the supplied location in structure string

AIC_CANT_ALLOCATE_MEMORY

General failure to allocate memory

AIC_HOST_NAME_TOO_LONG

Trying to get short version of a fully qualified name which is too long

AIC_APP_NAME_TOO_LONG

The application name is too long.

EXAMPLE


iStatus=AICAL_SetSemantics(gQuery_location,"CIMclass.CIMinstance");


Previous section.

NAME

AICAL_SetStatus, AICCL_SetStatus

SYNOPSIS


#include <libaic.h>

int AICAL_SetStatus ( 
    AIC_String szLocation_in_structure, 
    AIC_Status eStatusValue
    );

int AICCL_SetStatus ( 
    AIC_String szLocation_in_structure, 
    AIC_Status eStatusValue
    );


DESCRIPTION

Sets the status of the application to the new status value. This would typically be used within a thresholding function for an object in order to reflect the relationship between the object's value and the current threshold values of the object.

PARAMETERS

ID Type Description
szLocation_in_structure AIC_String Location in the object tree
EStatusValue AIC_Status New status level

RETURN VALUE

AIC_OK

The operation succeeded

AIC_NOK

An error occurred

AIC_ENUMORD_OUTOF_RANGE

The ordinal value of a supplied enum is outside of range

AIC_UNEXPECTED_FUNC_RES

Unexpected function return type

AIC_TIMEOUT

Timeout on request to remote application

AIC_NULL_POINTER_ARG

Null pointer argument supplied to function

AIC_IN_STRUC_NAME_SHORT

The location in structure name is too short to be a sensible name

AIC_BADLY_FORMED_LOCATIONSTRING

Something wrong with the supplied location in structure string

AIC_CANT_ALLOCATE_MEMORY

General failure to allocate memory

AIC_HOST_NAME_TOO_LONG

Trying to get short version of a fully qualified name which is too long

AIC_APP_NAME_TOO_LONG

The application name is too long.

EXAMPLE


iStatus=AICCL_SetStatus(gQuery_location,eStatusValue);


Previous section.

NAME

AICAL_SetThreshSemantics

SYNOPSIS


#include <libaic.h>

int AICAL_SetThreshSemantics ( 
    AIC_String szLocation_in_structure, 
    AIC_String szValue
    );


DESCRIPTION

Sets the Threshold semantics value of the given object to the value of the supplied AIC_String.

PARAMETERS

ID Type Description
szLocation_in_structure AIC_String Location in the object tree
szValue AIC_String String

RETURN VALUE

AIC_OK

The operation succeeded

AIC_NOK

An error occurred

AIC_ENUMORD_OUTOF_RANGE

The ordinal value of a supplied enum is outside of range

AIC_UNEXPECTED_FUNC_RES

Unexpected function return type

AIC_TIMEOUT

Timeout on request to remote application

AIC_NULL_POINTER_ARG

Null pointer argument supplied to function

AIC_IN_STRUC_NAME_SHORT

The location in structure name is too short to be a sensible name

AIC_BADLY_FORMED_LOCATIONSTRING

Something wrong with the supplied location in structure string

AIC_CANT_ALLOCATE_MEMORY

General failure to allocate memory

AIC_HOST_NAME_TOO_LONG

Trying to get short version of a fully qualified name which is too long

AIC_APP_NAME_TOO_LONG

The application name is too long.

EXAMPLE


iStatus=AICAL_SetThreshSemantics(gQuery_location,
                                 "Envelope: 1=Low, 2=High");


Previous section.

NAME

AICAL_SetThresholdDateAndTime, AICCL_SetThresholdDateAndTime

SYNOPSIS


#include <libaic.h>

int AICAL_SetThresholdDateAndTime ( 
    AIC_String szLocation_in_structure, 
    AIC_DateAndTime tValue, 
    AIC_ThresholdType eThresholdType
    ); 

int AICCL_SetThresholdDateAndTime ( 
    AIC_String szLocation_in_structure, 
    AIC_DateAndTime tValue, 
    AIC_ThresholdType eThresholdType
    );


DESCRIPTION

Sets a threshold value on a given object (object type is a date and time). There are four threshold values per object, and the third parameter indicates which of these threshold values is to be set. The function only applies to AICBusDateAndTime objects.

PARAMETERS

ID Type Description
szLocation_in_structure AIC_String Location in the object tree
TValue AIC_DateAndTime New Value
EWhichThreshold AIC_ThresholdType
Which threshold you want, one of:
oneArgThld
twoArgThld
threeArgThld
fourArgThld

RETURN VALUE

AIC_OK

The operation succeeded

AIC_NOK

An error occurred

AIC_ENUMORD_OUTOF_RANGE

The ordinal value of a supplied enum is outside of range

AIC_UNEXPECTED_FUNC_RES

Unexpected function return type

AIC_TIMEOUT

Timeout on request to remote application

AIC_NULL_POINTER_ARG

Null pointer argument supplied to function

AIC_IN_STRUC_NAME_SHORT

The location in structure name is too short to be a sensible name

AIC_BADLY_FORMED_LOCATIONSTRING

Something wrong with the supplied location in structure string

AIC_CANT_ALLOCATE_MEMORY

General failure to allocate memory

AIC_HOST_NAME_TOO_LONG

Trying to get short version of a fully qualified name which is too long

AIC_APP_NAME_TOO_LONG

The application name is too long.

EXAMPLE


iStatus=AICCL_SetThresholdDateAndTime(gQuery_location,dATime,gThreshold);


Previous section.

NAME

AICAL_SetThresholdDouble, AICCL_SetThresholdDouble

SYNOPSIS


#include <libaic.h>

int AICAL_SetThresholdDouble ( 
    AIC_String szLocation_in_structure, 
    AIC_Double dValue, 
    AIC_ThresholdType eThresholdType
    ); 

int AICCL_SetThresholdDouble ( 
    AIC_String szLocation_in_structure, 
    AIC_Double dValue, 
    AIC_ThresholdType eThresholdType
    );


DESCRIPTION

Sets the specified threshold value on an AICBusDouble object. The function only works on objects of this type.

PARAMETERS

ID Type Description
SzLocation_in_structure AIC_String Full object tree location specification
DValue AIC_Double New value
EWhichThreshold AIC_ThresholdType
Which threshold you want, one of:
oneArgThld
twoArgThld
threeArgThld
fourArgThld

RETURN VALUE

AIC_OK

The operation succeeded

AIC_NOK

An error occurred

AIC_ENUMORD_OUTOF_RANGE

The ordinal value of a supplied enum is outside of range

AIC_UNEXPECTED_FUNC_RES

Unexpected function return type

AIC_TIMEOUT

Timeout on request to remote application

AIC_NULL_POINTER_ARG

Null pointer argument supplied to function

AIC_IN_STRUC_NAME_SHORT

The location in structure name is too short to be a sensible name

AIC_BADLY_FORMED_LOCATIONSTRING

Something wrong with the supplied location in structure string

AIC_CANT_ALLOCATE_MEMORY

General failure to allocate memory

AIC_HOST_NAME_TOO_LONG

Trying to get short version of a fully qualified name which is too long

AIC_APP_NAME_TOO_LONG

The application name is too long.

EXAMPLE


iStatus=AICCL_SetThresholdDouble(gQuery_location,gdValue,gThreshold);


Previous section.

NAME

AICAL_SetThresholdLong, AICCL_SetThresholdLong

SYNOPSIS


#include <libaic.h>

int AICAL_SetThresholdLong ( 
    AIC_String szLocation_in_structure, 
    AIC_Long lValue, 
    AIC_ThresholdType eThresholdType
    ); 

int AICCL_SetThresholdLong ( 
    AIC_String szLocation_in_structure, 
    AIC_Long lValue, 
    AIC_ThresholdType eThresholdType
    );


DESCRIPTION

Sets the value of the specified threshold on an AICBusLong object. This function only works on objects of the type AICBusLong.

PARAMETERS

ID Type Description
szLocation_in_structure AIC_String Location in the object tree
lValue AIC_Long New threshold value
eWhichThreshold AIC_ThresholdType
Which threshold you want, one of:
OneArgThld
TwoArgThld
ThreeArgThld
FourArgThld

RETURN VALUE

AIC_OK

The operation succeeded

AIC_NOK

An error occurred

AIC_ENUMORD_OUTOF_RANGE

The ordinal value of a supplied enum is outside of range

AIC_UNEXPECTED_FUNC_RES

Unexpected function return type

EXAMPLE


iStatus=AICAL_SetThresholdLong(gQuery_location,glValue,gThreshold);


Previous section.

NAME

AIC_SetTimeStmp

SYNOPSIS


#include <libaic.h>

int AIC_SetTimeStmp ( 
    AIC_Date_AndTime *pDateTimeStmp, 
    short sYear, 
    AIC_Byte bMonth, 
    AIC_Byte bDay, 
    AIC_Byte bMinute, 
    AIC_Byte bSeconds
    );


DESCRIPTION

Sets the time in a DateAndTime variable using component parts of a time stamp (note that these component parts do not imply anything about the internal structure of the AIC_DateAndTime type). Range checking is applied to these parameters, in line with the specification of the range of allowable values in

PARAMETERS

ID Type Description
PDateTimeStmp AIC_DateAndTime * Address of DateTime variable
SYear short Year
BMonth AIC_BYTE Month
BDay AIC_BYTE Day
BHour AIC_BYTE Hour
BMinute AIC_BYTE Minute
BSeconds AIC_BYTE Second

RETURN VALUE

AIC_OK

The operation succeeded

AIC_NOK

An error occurred

EXAMPLE


i=AIC_SetTimeStmp(pdATime,(short)year,(AIC_BYTE)month,
    (AIC_BYTE)day,(AIC_BYTE)hour,(AIC_BYTE)min,(AIC_BYTE)sec);


Previous section.

NAME

AIC_SetTimeStmpNull

SYNOPSIS


#include <libaic.h>

int AIC_SetTimeStmpNull ( 
    AIC_DateAndTime *pDateTimeStmp
    );


DESCRIPTION

Sets the current timestamp to a NULL value4.

PARAMETERS

ID Type Description
PDateTimeStmp AIC_DateAndTime * Address of DateTime variable

RETURN VALUE

AIC_OK

The operation succeeded

AIC_NOK

An error occurred

EXAMPLE


lStatus=AIC_SetTimeStmpNull(pdATime);


Previous section.

NAME

AICCL_SetUserCredentials

SYNOPSIS


#include <libaic.h>

int AICCL_SetUserCredentials ( 
    AIC_String szName, 
    AIC_String szGroup, 
    AIC_String szPassword
    );


DESCRIPTION

When a security model requires a userid and password to be supplied (such as the operating system model), it is the client application's responsibility to provide this combination. This function call is used to supply the required credential details to the client library.

The group is used as an optional paramter (for example, NT domain name)

The use of this call is specific to the security plug-in in use.

PARAMETERS

ID Type Description
SzName AIC_String User Name
SzGroup AIC_String User Group
SzPassword AIC_String User Password

RETURN VALUE

AIC_OK

The operation succeeded

AIC_NOK

An error occurred

AIC_NULL_POINTER_ARG

Null pointer argument supplied to function

AIC_CANT_ALLOCATE_MEMORY

General failure to allocate memory

EXAMPLE


iStatus = AICCL_SetUserCredentials("jelvers",NULL,"fred");


Previous section.

NAME

AICAL_SetValueDateAndTime, AICCL_SetValueDateAndTime

SYNOPSIS


#include <libaic.h>

int AICAL_SetValueDateAndTime ( 
    AIC_String szLocation_in_structure, 
    AIC_DateAndTime tValue
    );

int AICCL_SetValueDateAndTime ( 
    AIC_String szLocation_in_structure, 
    AIC_DateAndTime tValue
    );


DESCRIPTION

Sets the value of a AICBusDateAndTime object to the provided date and time value. This function call is only applicable to objects of this type.

PARAMETERS

ID Type Description
szLocation_in_structure AIC_String Location in the object tree
tValue AIC_DateAndTime Value

RETURN VALUE

AIC_OK

The operation succeeded

AIC_NOK

An error occurred

AIC_ENUMORD_OUTOF_RANGE

The ordinal value of a supplied enum is outside of range

AIC_UNEXPECTED_FUNC_RES

Unexpected function return type

AIC_TIMEOUT

Timeout on request to remote application

AIC_NULL_POINTER_ARG

Null pointer argument supplied to function

AIC_IN_STRUC_NAME_SHORT

The location in structure name is too short to be a sensible name

AIC_BADLY_FORMED_LOCATIONSTRING

Something wrong with the supplied location in structure string

AIC_CANT_ALLOCATE_MEMORY

General failure to allocate memory

AIC_HOST_NAME_TOO_LONG

Trying to get short version of a fully qualified name which is too long

AIC_APP_NAME_TOO_LONG

The application name is too long.

EXAMPLE


iStatus=AICAL_SetValueDateAndTime(gQuery_location,dATime);


Previous section.

NAME

AICAL_SetValueDouble, AICCL_SetValueDouble

SYNOPSIS


#include <libaic.h>

int AICAL_SetValueDouble ( 
    AIC_String szLocation_in_structure, 
    AIC_Double dValue
    ); 

int AICCL_SetValueDouble ( 
    AIC_String szLocation_in_structure, 
    AIC_Double dValue
    );


DESCRIPTION

Sets the value of the AICBusDouble object to the double value supplied. This function only applies to objects of this type.

PARAMETERS

ID Type Description
szLocation_in_structure AIC_String Location in the object tree
DValue AIC_Double Value

RETURN VALUE

AIC_OK

The operation succeeded

AIC_NOK

An error occurred

AIC_ENUMORD_OUTOF_RANGE

The ordinal value of a supplied enum is outside of range

AIC_UNEXPECTED_FUNC_RES

Unexpected function return type

AIC_TIMEOUT

Timeout on request to remote application

AIC_NULL_POINTER_ARG

Null pointer argument supplied to function

AIC_IN_STRUC_NAME_SHORT

The location in structure name is too short to be a sensible name

AIC_BADLY_FORMED_LOCATIONSTRING

Something wrong with the supplied location in structure string

AIC_CANT_ALLOCATE_MEMORY

General failure to allocate memory

AIC_HOST_NAME_TOO_LONG

Trying to get short version of a fully qualified name which is too long

AIC_APP_NAME_TOO_LONG

The application name is too long.

EXAMPLE


iStatus=AICCL_SetValueDouble(gQuery_location,gdValue);


Previous section.

NAME

AICAL_SetValueLong. AICCL_SetValueLong

SYNOPSIS


#include <libaic.h>

int AICAL_SetValueLong ( 
    AIC_String szLocation_in_structure, 
    AIC_Long lValue
    ); 

int AICCL_SetValueLong ( 
    AIC_String szLocation_in_structure, 
    AIC_Long lValue
    );


DESCRIPTION

Sets the value of the AICBusLong object to the value of the provided long.

PARAMETERS

ID Type Description
szLocation_in_structure AIC_String Location in the object tree
lValue AIC_Long Value

RETURN VALUE

AIC_OK

The operation succeeded

AIC_NOK

An error occurred

AIC_ENUMORD_OUTOF_RANGE

The ordinal value of a supplied enum is outside of range

AIC_UNEXPECTED_FUNC_RES

Unexpected function return type

AIC_TIMEOUT

Timeout on request to remote application

AIC_NULL_POINTER_ARG

Null pointer argument supplied to function

AIC_IN_STRUC_NAME_SHORT

The location in structure name is too short to be a sensible name

AIC_BADLY_FORMED_LOCATIONSTRING

Something wrong with the supplied location in structure string

AIC_CANT_ALLOCATE_MEMORY

General failure to allocate memory

AIC_HOST_NAME_TOO_LONG

Trying to get short version of a fully qualified name which is too long

AIC_APP_NAME_TOO_LONG

The application name is too long.

EXAMPLE


glValue=123;
iStatus=AICCL_SetValueLong(gQuery_location,glValue);


Previous section.

NAME

AICAL_SetValueVarChar, AICCL_SetValueVarChar

SYNOPSIS


#include <libaic.h>

int AICAL_SetValueVarChar ( 
    AIC_String szLocation_in_structure, 
    AIC_String szValue
    );

int AICCL_SetValueVarChar ( 
    AIC_String szLocation_in_structure, 
    AIC_String szValue
    );


DESCRIPTION

Sets the value of the given object to the value of the supplied AIC_String. The defined behaviour of this operation is that the supplied string argument is copied into the value attribute of the object. Therefore on return from this function, the application programmer can re-use the string value or free the memory as desired.

PARAMETERS

ID Type Description
szLocation_in_structure AIC_String Location in the object tree
szValue AIC_String String

RETURN VALUE

AIC_OK

The operation succeeded

AIC_NOK

An error occurred

AIC_ENUMORD_OUTOF_RANGE

The ordinal value of a supplied enum is outside of range

AIC_UNEXPECTED_FUNC_RES

Unexpected function return type

AIC_TIMEOUT

Timeout on request to remote application

AIC_NULL_POINTER_ARG

Null pointer argument supplied to function

AIC_IN_STRUC_NAME_SHORT

The location in structure name is too short to be a sensible name

AIC_BADLY_FORMED_LOCATIONSTRING

Something wrong with the supplied location in structure string

AIC_CANT_ALLOCATE_MEMORY

General failure to allocate memory

AIC_HOST_NAME_TOO_LONG

Trying to get short version of a fully qualified name which is too long

AIC_APP_NAME_TOO_LONG

The application name is too long.

EXAMPLE


iStatus=AICCL_SetValueVarChar(gQuery_location,data);


Previous section.

NAME

AICAL_SetVisibility, AICCL_SetVisibility

SYNOPSIS


#include <libaic.h>

int AICAL_SetVisibility ( 
    AIC_String szLocation_in_structure, 
    AIC_Visibility eVisibility
    );

int AICCL_SetVisibility ( 
    AIC_String szLocation_in_structure, 
    AIC_Visibility eVisibility
    );


DESCRIPTION

Sets the visibility level of the given object to the supplied visibility level. This functionality is provided for compatibility with external management frameworks. The three levels provided will need to be mapped into visibilities that are relevant in the chosen management framework.

PARAMETERS

ID Type Description
szLocation_in_structure AIC_String Location in the object tree
eVisibility AIC_Visibility
New visibility level. Either:
local
domain
enterprise

RETURN VALUE

AIC_OK

The operation succeeded

AIC_NOK

An error occurred

AIC_ENUMORD_OUTOF_RANGE

The ordinal value of a supplied enum is outside of range

AIC_UNEXPECTED_FUNC_RES

Unexpected function return type

EXAMPLE


iStatus=AICCL_SetVisibility(gQuery_location,"domain");


Previous section.

NAME

AIC_TimeStmpCmp

SYNOPSIS


#include <libaic.h>

int AIC_TimeStmpCmp ( 
    AIC_DateAndTime *pDateTimeStmp1, 
    AIC_DateAndTime *pDateTimeStmp2, 
    double *pdDeltaSeconds
    );


DESCRIPTION

Compares two DateAndTime variables and also calculates the number of seconds difference between the two. The return value of the function indicates whether the two times are the same, the first is less than the second, or the first is greater than the second.

PARAMETERS

ID Type Description
pDateTimeStmp1 AIC_DateAndTime * Address of DateTime variable1
pDateTimeStmp2 AIC_DateAndTime * Address of DateTime variable2
pdDeltaSeconds double * Seconds difference between times

RETURN VALUE

AIC_OK

The operation succeeded

AIC_NOK

An error occurred

ONE_GREATER_THAN_TWO

Arg1 is > arg 2

ONE_LESS_THAN_TWO

Arg1 is < arg 2

ONE_EQUALS_TWO

Arg1 == Arg2

EXAMPLE


AIC_DateAndTime sTime1, sTime2;
Double dDifference;

IStatus = AIC_TimeStmpCmp( &sTime1, &sTime2, &dDifference );


Previous section.

NAME

AIC_TimeStmpToStr

SYNOPSIS


#include <libaic.h>

int AIC_TimeStmpToStr ( 
    AIC_DateAndTime *pDateTimeStmp, 
    char *pszDst, 
    long lDstLength
    );


DESCRIPTION

Takes a DateAndTime variable and converts it to the following standard character representation: YYYY/MM/DD-HH:MM:SS. If the supplied buffer is too small for the string version of the date and time, the value is truncated and an error returned.

PARAMETERS

ID Type Description
pDateTimeStmp AIC_DateAndTime * Address of DateTime variable
pszDst char * Buffer for string
lDstLength long Length of buffer

RETURN VALUE

AIC_OK

The operation succeeded

AIC_NOK

An error occurred

AIC_NULL_POINTER_ARG

Null pointer argument supplied to function

AIC_NEGATIVE_DATA_SIZE_SUPPLIED

Bad length parameter for space

EXAMPLE


iStatus=AIC_TimeStmpToStr(&sValue,szValue,MAXLEN);


Previous section.

NAME

AIC_ToScreen

SYNOPSIS


#include <libaic.h>

void AIC_ToScreen ( 
    short sFlag
    );


DESCRIPTION

Turns screen debug on or off, but only works with an AIC Library compiled in DEBUG mode.

PARAMETERS

ID Type Description
sFlag short 1 = ON, 0 = OFF

RETURN VALUE

None

EXAMPLE


iStatus = AIC_ToScreen(1);


Previous section.

NAME

AICAL_Traverse, AICCL_Traverse

SYNOPSIS


#include <libaic.h>

int AICAL_Traverse ( 
    AIC_String szLocation_in_structure, 
    int iLevels,
    AIC_ListPtr *ppDstListPtr
    );

int AICCL_Traverse ( 
    AIC_String szLocation_in_structure, 
    int iLevels,
    AIC_ListPtr *ppDstListPtr
    );


DESCRIPTION

Performs a query against the object structure5, and returns objects across the tree horizontally and down from the nominated start position. The number of levels traversed down the tree is limited by the value iLevels, passed into the function. A list of matching objects is passed back from the function and can be accessed via the AIC_GetNextObject() call. When the programmer no longer needs this list, it can be freed using the AIC_FreeMemory() call.

PARAMETERS

ID Type Description
szLocation_in_structure AIC_String Full object tree location specification
iLevels int Number of levels down the tree to include search results
ppDstListPtr AIC_ListPtr Pointer to a list of results

RETURN VALUE

AIC_OK

The operation succeeded

AIC_NOK

An error occurred

AIC_NULL_POINTER_ARG

Null pointer argument supplied to function

AIC_IN_STRUC_NAME_SHORT

The location in structure name is too short to be a sensible name

AIC_BADLY_FORMED_LOCATIONSTRING

Something wrong with the supplied location in structure string

AIC_CANT_ALLOCATE_MEMORY

General failure to allocate memory

AIC_HOST_NAME_TOO_LONG

Trying to get short version of a fully qualified name which is too long

AIC_APP_NAME_TOO_LONG

The application name is too long.

EXAMPLE


int             iStatus;
AIC_ListPtr     pList;

iStatus = AICCL_Traverse(query_location,depth, &pList);



Footnotes

1.
Internal storage of the object structure may not in fact be a tree.

2.
If this list is created as the result of a cross platform query, the function callbacks will be undefined in the program space of the recipient machine.

3.
The object structure is not physically a tree, but this case it is helpful to think of it in this way. Each / delimeter can seen as another level lower in the tree. For example the objects /a/b and /a/c are at the same level in this implied tree structure.

4.
The internal value is not necessarily the C NULL value. It is a fully encapsulated value which represents a null time stamp to the AIC library.

5.
The object structure can be thought of as being a tree, due to the naming convention of objects, although it is not necessarily stored or accessed in that way.

Contents Next section Index