IBM Director Resource Monitor Agent extensions

    The IBM Director Resource Monitor Agent is an extendable service for collecting and displaying real-time data on system resources. The monitor agent (TWGMonit.exe) executes on the system being monitored and loads the installed monitor libraries on the system by invoking predefined entry points in each library for monitor initialization, data collection, and termination. The monitor library needs only to provide data to the monitor agent, which handles the communications with the monitor server, routine data collection, recording of data points, threshold conditions and alert generation.

    The monitor agent supports two types of dynamic attributes: Numeric and String. Numeric monitor attributes are quantitative monitors in that they track system attributes or components that are measured in terms of some numerical value. Numeric attributes can be used to monitor resource utilization, such as CPU, DASD or memory. In this case, the quantity being tracked is a percentage, and values can range between zero and one hundred. String monitor attributes are qualitative monitors in that they deal with non-numeric qualities of the systems and components being monitored. String attributes can be used to monitor the state of devices, such as "off-line", "online", or "busy".
 

Monitor library discovery

    When the monitor agent is started, it searches for monitor libraries in its current directory. To be discovered by the monitor agent, a monitor library must:

 

Developing a monitor library

    A monitor library is a dynamic link library (DLL) or NetWare load module (NLM) that is loaded by the monitor agent at run-time. To add a new monitor library extension, the following requirements must be met:

 
 
Initializing a monitor library

    A monitor library can provide any number of monitor attributes to monitor all kinds of system resources. The number of attributes supported by a monitor library on a given system might vary, depending on the system's hardware configuration, software configuration, or other factors. The first job of the monitor library is to determine if it can provide any monitor attributes on the system where it is installed. When the monitor agent discovers a monitor library, it issues the InitNodes call to find out if the monitor library is supported on this system.
 
BOOL MONENTPNT InitNodes()

Parameters:  Returns:  
Define Name Meaning
FALSE The monitor library is not supported on this system or its initialization failed.
TRUE The monitor library has attributes for this system and was initialized successfully.
 

Discovering the available attributes in a monitor library

    The available monitor attributes are displayed in a tree view by the IBM Director Resource Monitor Console.  This is the conceptual view of how your monitor library nodes and attributes should be laid out.  The monitor attributes should be grouped and laid out in a tree fashion with as many nodes and branches as you need to make it easy to navigate and understand for the user.  As a user navigates into the IBM Director Agent node on the console, they will see a branch for each monitor library installed on that individual client or for the collection of libraries availble on the systems that they have choosen to monitor.  The list of monitor libraries is provided to the server by the monitor agent by matching up the initialized monitor libraries to their presentation names located in the monitors.ini file.  If a filename mapping is not found, then the library name without its extension will be displayed in the console.  When the user expands a monitor library node, the monitor agent will query the library for its nodes or leaves (attributes) at that level by calling the GetNodeList entry point.  So, the first time the library will be queried by the monitor agent is for its Level 1 nodes/attributes, since the monitor agent handles the Level 0 or root queries for the monitor libraries.  After the monitor agent has processed the data returned by a GetNodeList call, it will call FreeNodeList with the data reference so the monitor library can free the memory it allocated for the data structure.  The get/free calls are made back-to-back to each other and can be received at any time between the initialization and termination of a monitor library.

AttributeNodeList * MONENTPNT GetNodeList( AttributePath MONFAR *queriedPath)

Parameters: Returns:  
void MONENTPNT FreeNodeList( AttributeNodeList MONFAR *pNList) Parameters: Returns:  
Connecting to an attribute in a monitor library

    A handle to a monitor attribute is acquired by the monitor agent when the console user wants to monitor, record or set a threshold range for its value.  The handle returned by NodeConnect call should be a persistent handle or index value maintained by the monitor library with as much of the AttributePath or meta-data values required until the monitor agent releases the attribute by calling NodeDisconnect.  After a valid handle has been acquired, it can be used at any time for the GetNodeAttributes, NodePulse and  NodeGetValue calls until a NodeDisconnect call is made on the handle.

BOOL MONENTPNT NodeConnect( AttributePath MONFAR *pAPath, ULONG MONFAR *key, BYTE MONFAR *dataType)

Parameters:  
Value Range Meaning
0x00000000 to 0xFFFFFFFE A valid handle into the monitor library.
INVALID_HANDLE (0xFFFFFFFF) An incorrect handle.
   
Value Range Meaning
DYNAMICNODE_ATTRIBUTE (0x08) The monitor attribute is a dynamic attribute.
INVALID_ATTRIBUTE (0x00) The monitor attribute is incorrect.
 
 Returns:  
Define Name Meaning
FALSE A handle could not be returned to the specifed monitor attribute path.  The path is not valid for this monitor library or for this particular system.
TRUE A valid handle was returned for the specified monitor attribute.
 

NodeParms * MONENTPNT GetNodeAttributes( ULONG key)

Parameters:  
Value Range Meaning
0x00000000 to 0xFFFFFFFE A valid handle into the monitor library.
INVALID_HANDLE (0xFFFFFFFF) An incorrect handle.
 

 Returns:

 
 
Gathering data from an attribute in a monitor library

    Periodically, the monitor agent polls each monitor attribute handle for its current value.  The monitoring process occurs continuously from the time when a handle is acquired until it is released.  Monitor attributes are polled for data according to the attribute's base_pulse and pulses_per_data parameters. Each attribute receives one or more pulses, or NodePulse calls, before it's current value is requested with NodeGetValue.  Pulses allow the monitor to perform periodic activities like polling a device for data.  The monitor agent issues a NodeGetValue call immediately after the last of pulses_per_data pulses to obtain the next data point from an atttribute.  A monitor attribute reports its data value to the monitor agent by returning a completed NodeData structure on a NodeGetValue call.
 

ULONG MONENTPNT NodePulse( ULONG key, ULONG time_since_last)

Parameters: Returns: NodeData * MONENTPNT NodeGetValue( ULONG key) Parameters:  Returns:  

void MONENTPNT NodeFreeValue( NodeData MONFAR *nd)

Parameters:  Returns:  

Releasing an attribute in a monitor library

When all of the users have stopped monitoring and recording an attribute and when the last threshold has been disabled or deleted, then the monitor agent will call FreeNodeAttributes and then NodeDisconnect once with the pointer returned by NodeGetAttributes and the handle returned by the NodeConnect calls so the monitor library can perform any cleanup of its associated data being maintained for the attribute.  The monitor library will receive no further calls for this monitor attribute after the NodeDisconnect call unless a user wants to monitor the attribute again, at which time a NodeConnect call will be made to acquire a new handle to the attribute.

void MONENTPNT FreeNodeAttributes( NodeParms MONFAR *nParms)

Parameters:  Returns:  

BOOL MONENTPNT NodeDisconnect( ULONG key)

Parameters:  Returns:  
Define Name Meaning
FALSE The referenced handle was incorrect or already released.
TRUE The handle and its data were released.
 

Terminating a monitor library

    When the monitor agent terminates execution (usually when the system is being shut down), it issues a termination call to every monitor library it initialized by calling the TermNodes entry point. The monitor library should then cleanup any dynamic storage it has allocated and terminate all processing.

BOOL MONENTPNT TermNodes()

Parameters:  Returns:  
Define Name Meaning
FALSE The monitor library termination failed.  This return code is ignored.
TRUE The monitor library has finished its termination routines.
 
 
Monitor library constants
 
Return Values for the rc fields in the _TWG_xxx structs: These are the defined Attribute/Node types supported by Monitor DLLs: This define is used to indicate that a handle could not be acquired or to invalidate a handle being returned: The following are the defined data types that can be returned by the NodeData structure: The following are the defined types that should be used for exporting the required Monitor DLL entry points.  The type has been defined for each supported operating system so common code and programming requirements can be maintained. The following define what versions of the structures being used.  Currently there is only one supported version of each structure.  

Monitor library structures

AttributePath

AttributeNode AttributeNodeList NodeParms DataLevelRec Node Data