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.
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.
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.
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.
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";
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.
The monitor object is installed as part of the Teradata Manager installation.
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.
Use the Project, References menu to add a reference to it. You will find it in the ‘Available References’ list box as TeradataPerformance6.
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.
Use the Project, Add Reference… menu. Then click the COM tab and scroll down to select TeradataPerformance6 from the list.
Use the Tools, References menu to add a reference to it. You will find it in the ‘Available References’ list box under TeradataPerformance6.
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.
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.
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.
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().
void COMError(HRESULT hr, const CString sAction)
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.
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.
To create a globally available Monitor object called gMon use the following code:
Public gMon As TeradataPerformance6.Monitor
Set gMon = New TeradataPerformance6.Monitor
To create a globally available Monitor object called gMon use the following code:
public static TeradataPerformance6.Monitor gMon;
gMon = New TeradataPerformance6.Monitor();
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,
/* call your error function */
/* You can now use the object’s methods */
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.
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.
In VB: Set pAMPs = Nothing
In C++: pAMPs->Release();
pAMPs = NULL;
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:
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.