Developing Performance Monitoring Applications - Introduction

Tools
Tools covers the tools and utilities you use to work with Teradata and its supporting ecosystem. You'll find information on everything from the Teradata Eclipse plug-in to load/extract tools.
Teradata Employee

Developing Performance Monitoring Applications - Introduction

The Teradata Performance Monitor Object is a COM object that provides methods which encapsulate the code required to fetch performance information from a Teradata Database. In most cases the data is returned as a collection of performance objects.

These articles refer to the version of the object that ships with Teradata Manager 12.0, and 13.0.

For example, the GetSessionData method returns a collection of Session objects. Each Session object contains information about a specific session that is currently logged onto the Database. If this session is blocked, it also contains information about the sessions that are blocking it, and the resource that is causing the block.

The Monitor object also allows you to issue control commands to Abort, or change the Account or Workload, of any session.

Operating modes

The Monitor object can be used in 2 modes. The mode is controlled by the setting of the UseClient property. Initially UseClient will be set to False.


Direct mode

In direct mode all data is fetched directly from the Teradata Database. You must establish a session using the Connect method before calling any of the data retrieval or action methods.


Client mode

In Client mode all data will be retrieved from a Teradata Manager server. You do not need to establish a session on the Teradata Database. You may not be able to use the action (‘Set’ or ‘Send’) methods through Client mode. The server can be set up to allow or reject action commands.

You start client mode by setting UseClient = True. This will fail if communication could not be established with the Teradata Manager server. You should therefore check the value of the UseClient property, after setting it, to ensure that it has been successfully set to True.

When you set UseClient to True, a dialog may ask you for the name of the Teradata Manager server you wish to communicate with, and for your login information. (This dialog will not appear if you launched your application from within Teradata Manager, or have already set the 4 required data properties.) If not launched from within Teradata Manager, a session will be temporarily logged on in order to read some control information from the database.

Terminology

Although you can use any programming environment that supports COM you will find that Visual Basic provides more assistance when using such objects. As a result, this document is written using Visual Basic terminology.

When this document refers to an object property it means that you set the value in Visual Basic using an assignment statement, and query the value by referencing it as a variable.

In Visual C++ the assignment is performed using a put_xxx function and the query would use a get_xxx function, where xxx is the property name.

For example, to set the Application name to be used in the Error object you would assign the AppName property.

In VB:    gMon.AppName = "My Monitor App"

In C++: BSTR MyAppName = "My Monitor App";

              put_AppName(MyAppName);

 Also note that references to a value of True apply to Visual Basic. In Visual C++ use the value VARIANT_TRUE. In C++ all boolean values must be of type VARIANT_BOOL and all strings must be of type BSTR.

Installing the Monitor Object

The monitor object is installed as part of the Teradata Manager installation.

Preparing to use the Monitor object

The monitor object (TDMon6.dll) requires a number of support files. These must be installed either in your application directory, or in a directory referenced in your environment path.

(Please refer to the Monitor Object Reference guide for more information)

Before you can use the Monitor object in your project you must let the compiler know that you plan to use this COM object. This step varies depending on the programming environment that you are using.


Visual Basic

Use the Project, References menu to add a reference to it. You will find it in the ‘Available References’ list box as TeradataPerformance6.


Visual C++

Include the files TDMon.h and TDMon_i.c in the source file that will be using the Monitor object. These files can be found in the Samples\VC\SimpMon sub-directory of the directory in which you installed the Monitor Object.

Note - If you are using C (not C++) you will need to include TDMon6.h instead of TDMon.h.

You will also need to call the Windows API function CoInitialize() before creating your first COM object, and call CoUninitialize() before ending your application.


Visual Basic .Net

Use the Project, Add Reference… menu. Then click the COM tab and scroll down to select TeradataPerformance6 from the list.


Microsoft Excel

Use the Tools, References menu to add a reference to it. You will find it in the ‘Available References’ list box under TeradataPerformance6.

Internal Documentation

The Object is self documenting. Each Class, Method and Property has an associated description which can be viewed using the object browser in your development environment.

If your development environment supports intellisense you will also see the expected drop down lists and function descriptions.

Error Handling

If the object encounters a problem it will raise an error that can be trapped by the calling application. The information returned will consist of a 5 digit error code and a textual description of the error. How you handle errors will depend on the programming language you are using.


Visual Basic

Use the standard On Error statement to trap the errors. In your error function use the Err.Number to obtain the error code, and Err.Description to obtain the error text.


Visual C++

Every Method returns an HRESULT. Use the macros SUCCESS() or FAILED() to determine whether the function succeeded. In your error function you can refer to the error number using HRESULT_CODE() and obtain the text message using FormatMessage().

For example:

void COMError(HRESULT hr, const CString sAction)
{
CString sMsg;
char sz[256];
if (!FormatMessage(FORMAT_MESSAGE_FROM_SYSTEM,0, hr,0, sz, 256,0))
strcpy(sz, "Unknown error");
sMsg.Format("%s failed!\n\n%d: %s", sAction, HRESULT_CODE(hr), sz);
}

Error codes are grouped into 2 types.

If the first digit is a 1 then the remaining 4 digits will be the Teradata error code.

Refer to the Teradata Database Messages manual for further information about these codes.

If the first digit is a 2 then the message is generated by the Monitor object itself.

Creating an Instance of the Monitor object

In general you will want to create an instance of the Monitor object at application startup and destroy it at program termination.

The GetSessionData method uses an internal cache that allows the object to calculate values for CurrentCPU, TimeBlocked, and TimeIdle. Each time you destroy and re-create the object these values will be reset to zero.

Creating an instance of the Monitor object varies depending on the programming environment that you are using.


Visual Basic

To create a globally available Monitor object called gMon use the following code:

Public gMon As TeradataPerformance6.Monitor

Set gMon = New TeradataPerformance6.Monitor


Visual C#

To create a globally available Monitor object called gMon use the following code:

public static TeradataPerformance6.Monitor gMon;

gMon = New TeradataPerformance6.Monitor();


Visual C++

To create an instance of the Monitor object called pMon use the following code:

_Monitor *pMonitor = 0; // The monitor object

HRESULT hr = CoCreateInstance(CLSID_Monitor, 0, CLSCTX_ALL,

                         IID__Monitor,(void**)&pMonitor);

if (FAILED(hr))

    /* call your error function */

else {

    /* You can now use the object’s methods */

}

Connecting to the Database

After you have created an instance of the Monitor object you must connect it to a Teradata Database.

Use the Connect method as follows:

In VB:   gMon.Connect System, UserName, Password

In C#:   gMon.Connect(System, UserName, Password);

In C++: BSTR Sys = "ProdA", Usr = "SysDBA", Pwd = "MyPwd";

             HRESULT hr = pMonitor->Connect(Sys, Usr, Pwd);

In addition to the parameters shown above you may also pass the Account, AuthenticationMechanism and AuthenticationParameter. All parameters are optional. You will be prompted to enter the data if it is insufficient to connect.

Allocating and Freeing memory

Some of the GetXxx() methods return collections of AMPs, PEs, Nodes etc. The Monitor object will allocate the necessary storage for these collections, but it will not free any storage that is currently pointed to by the function parameter(s). It is up to the user application to free this storage when it has finished with the data.

For Example:

In VB:    Set pAMPs = Nothing

In C++: pAMPs->Release();

             pAMPs = NULL;

Using Collections

Each collection object contains a Count property that describes the number of objects in the collection. In C++ you would use this property to iterate through the collection. In Visual Basic or .Net you can either use this property or use the For Each loop construct.

A specific member of a collection can be referenced either by its index (1 through Count) or by its Key property.

The Key is a character string, as follows:

Object    Key

Node       ccc-nn      where ccc is cabinet number and nn is node within cabinet

AMP         n              Ascending sequence from 0

PE            n              Descending sequence from 16383

VSS          n              Ascending sequence from 10237

Session    hh/ssss   where hh is the HostId and ssss is the SessionNumber

Collections may also contain additional information such as AvgCpuUse or MonitorRate.

Please refer to the Reference Guide for detailed information on the Object Model.

Tags (2)
6 REPLIES
Fan

Re: Developing Performance Monitoring Applications - Introduction

Very good examples.

Any java code?
Teradata Employee

Re: Developing Performance Monitoring Applications - Introduction

I know someone wrote a java app to use the object a few years ago but I'm afraid i dont have any java examples.
Maybe someone else has done this?

Re: Developing Performance Monitoring Applications - Introduction

Hi Mike

I have developed an tool for alerting based on PerfMon (TDMon6) object using Excel/VBA. Its working fine on my desktop, but when I try to run it from different desktop, it gives me error 'can't find MONPM.DLL'

Appreciate your help.

Thanks in advance.

Regards,
Ashok
Teradata Employee

Re: Developing Performance Monitoring Applications - Introduction

The monitor object requires a number of support dlls which are installed as part of Teradata Manager. If Teradata Manager is not installed on the other system you will need to install these dlls in either the directory that contains your app, or in a directory that is on the current PATH. (You could also use \Windows\System32)

Please refer to Appendix B at the end of the 'Property and Method Reference' article, for more details.

Re: Developing Performance Monitoring Applications - Introduction

Mike, have you posted any new articles lately? Although your articles are over a year old, the content is sound. I would really appreciate your feedback on my application monitoring site, Techout. Thanks.
Teradata Employee

Re: Developing Performance Monitoring Applications - Introduction

There have not been any changes to the Monitor object so all the old articles are still valid.