Application Programming Reference

Application Programming Reference
Teradata Database
Application Programming Reference
Workload Management
Release 14.0
B035-1090-111A
June 2013
The product or products described in this book are licensed products of Teradata Corporation or its affiliates.
Teradata, Active Data Warehousing, Active Enterprise Intelligence, Applications-Within, Aprimo, Aprimo Marketing Studio, Aster, BYNET,
Claraview, DecisionCast, Gridscale, MyCommerce, Raising Intelligence, Smarter. Faster. Wins., SQL-MapReduce, Teradata Decision Experts,
"Teradata Labs" logo, "Teradata Raising Intelligence" logo, Teradata ServiceConnect, Teradata Source Experts, "Teradata The Best Decision Possible"
logo, The Best Decision Possible, WebAnalyst, and Xkoto are trademarks or registered trademarks of Teradata Corporation or its affiliates in the
United States and other countries.
Adaptec and SCSISelect are trademarks or registered trademarks of Adaptec, Inc.
AMD Opteron and Opteron are trademarks of Advanced Micro Devices, Inc.
Apache, Apache Hadoop, Hadoop, and the yellow elephant logo are either registered trademarks or trademarks of the Apache Software Foundation
in the United States and/or other countries.
Axeda is a registered trademark of Axeda Corporation. Axeda Agents, Axeda Applications, Axeda Policy Manager, Axeda Enterprise, Axeda Access,
Axeda Software Management, Axeda Service, Axeda ServiceLink, and Firewall-Friendly are trademarks and Maximum Results and Maximum
Support are servicemarks of Axeda Corporation.
Data Domain, EMC, PowerPath, SRDF, and Symmetrix are registered trademarks of EMC Corporation.
GoldenGate is a trademark of Oracle.
Hewlett-Packard and HP are registered trademarks of Hewlett-Packard Company.
Hortonworks, the Hortonworks logo and other Hortonworks trademarks are trademarks of Hortonworks Inc. in the United States and other
countries.
Intel, Pentium, and XEON are registered trademarks of Intel Corporation.
IBM, CICS, RACF, Tivoli, and z/OS are registered trademarks of International Business Machines Corporation.
Linux is a registered trademark of Linus Torvalds.
LSI is a registered trademark of LSI Corporation.
Microsoft, Active Directory, Windows, Windows NT, and Windows Server are registered trademarks of Microsoft Corporation in the United States
and other countries.
NetVault is a trademark or registered trademark of Quest Software, Inc. in the United States and/or other countries.
Novell and SUSE are registered trademarks of Novell, Inc., in the United States and other countries.
Oracle, Java, and Solaris are registered trademarks of Oracle and/or its affiliates.
QLogic and SANbox are trademarks or registered trademarks of QLogic Corporation.
Red Hat is a trademark of Red Hat, Inc., registered in the U.S. and other countries. Used under license.
SAS and SAS/C are trademarks or registered trademarks of SAS Institute Inc.
SPARC is a registered trademark of SPARC International, Inc.
Symantec, NetBackup, and VERITAS are trademarks or registered trademarks of Symantec Corporation or its affiliates in the United States and
other countries.
Unicode is a registered trademark of Unicode, Inc. in the United States and other countries.
UNIX is a registered trademark of The Open Group in the United States and other countries.
Other product and company names mentioned herein may be the trademarks of their respective owners.
THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROVIDED ON AN "AS-IS" BASIS, WITHOUT WARRANTY OF ANY KIND, EITHER
EXPRESS OR IMPLIED, INCLUDING THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR
NON-INFRINGEMENT. SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OF IMPLIED WARRANTIES, SO THE ABOVE EXCLUSION
MAY NOT APPLY TO YOU. IN NO EVENT WILL TERADATA CORPORATION BE LIABLE FOR ANY INDIRECT, DIRECT, SPECIAL, INCIDENTAL,
OR CONSEQUENTIAL DAMAGES, INCLUDING LOST PROFITS OR LOST SAVINGS, EVEN IF EXPRESSLY ADVISED OF THE POSSIBILITY OF
SUCH DAMAGES.
The information contained in this document may contain references or cross-references to features, functions, products, or services that are not
announced or available in your country. Such references do not imply that Teradata Corporation intends to announce such features, functions,
products, or services in your country. Please consult your local Teradata Corporation representative for those features, functions, products, or
services available in your country.
Information contained in this document may contain technical inaccuracies or typographical errors. Information may be changed or updated
without notice. Teradata Corporation may also make improvements or changes in the products or services described in this information at any time
without notice.
To maintain the quality of our products and services, we would like your comments on the accuracy, clarity, organization, and value of this document.
Please email: teradata-books@lists.teradata.com.
Any comments or materials (collectively referred to as "Feedback") sent to Teradata Corporation will be deemed non-confidential. Teradata
Corporation will have no obligation of any kind with respect to Feedback and will be free to use, reproduce, disclose, exhibit, display, transform,
create derivative works of, and distribute the Feedback and derivative works thereof without limitation on a royalty-free basis. Further, Teradata
Corporation will be free to use any ideas, concepts, know-how, or techniques contained in such Feedback for any purpose whatsoever, including
developing, manufacturing, or marketing products or services incorporating Feedback.
Copyright © 2000 – 2013 by Teradata Corporation. All Rights Reserved.
Preface
Purpose
This is a reference book for the Teradata Database workload management application
programming interface (API), which consists of interfaces to PM/APIs and open APIs, that
can be used for creating third-party applications and custom applications requiring the
acquisition and use of Teradata Database workload management and performance data.
It describes the different categories of workload management PM/APIs and open APIs and
how they can be used to interface with your own custom applications when performance
monitoring tools, such as Teradata Viewpoint or resource usage reports, do not provide the
information you need.
Note that the workload management PM/APIs described in this manual use monitor version 9
only (see “MONITOR VERSION” on page 136 for details). Monitor version 9 provides fields
that allow you to create new applications and enhance existing custom applications.
Related Documentation
•
If your custom application uses an earlier monitor version, depending on the version used,
see previous releases of Workload Management API: PM/API or Open API or PM/API
Reference.
•
For information on Teradata Viewpoint, see Teradata Viewpoint User Guide.
Audience
This book is intended to be used by:
•
Developers creating third-party applications.
•
End-users writing their own custom applications or enhancing existing ones.
Supported Software Releases and Operating
Systems
This book supports Teradata® Database 14.0.
Teradata Database 14.0 is supported on:
•
SUSE Linux Enterprise Server (SLES)10
•
SLES 11
Application Programming Reference
3
Preface
Changes to This Book
Note that SLES 11 will be supported after the initial release of Teradata Database 14.0.
Teradata Database client applications support other operating systems.
Changes to This Book
Release
Description
Teradata Database 14.0
• Changed the MONITOR SESSION Blk_1_OType column data type
to VARCHAR(1).
• Added the following note about:
• System PMPC and query band UDFs not being fully qualified by
the database name, SYSLIB, when issued.
• Query band external stored procedures being fully qualified by the
database name, SYSLIB, when issued.
• Teradata Dynamic Workload Management UDFs and external
stored procedures being fully qualified by the database name,
TDWM, when issued.
June 2013
Teradata Database 14.0
February 2012
Teradata Database 14.0
• Updated the following:
• Status field description in MONITOR PHYSICAL RESOURCE.
• The “Monitor Privileges” and “Required Privileges” topics.
• The field Data Type columns.
• Combined the descriptions for monitor version ID 7 and 8 in the
“Response Parcel Groups” topic of MONITOR SESSION.
• Added a note to the IndByte fields in the PM/API requests.
• Removed the TDWMObjectAssn external stored procedure.
Updated the Confidence field description in MonitorSQLSteps.
January 2012
4
Application Programming Reference
Preface
Changes to This Book
Release
Description
Teradata Database 14.0
• Added the following fields:
• CPUDecayLevel, IODecayLevel, TacticalCPUException, and
TacticalIOException, RedriveProtection,
CurrentRedriveParticipation, ReqPersistentSpoolSpace, ReqIOKB,
ReqPhysIO, and ReqPhysIOKB to MONITOR SESSION,
MonitorSession, and MonitorMySessions.
• CollectionInterval, CollectionSeqNum, SessionRate,
ExceptionInterval, SessionRateThreshold, and DBQLFlushRate to
MONITOR SESSION.
• CollectionDate and CollectionTime to MONITOR SESSION,
MONITOR WD, MONITOR PHYSICAL RESOURCE,
MONITOR PHYSICAL SUMMARY, MONITOR VIRTUAL
RESOURCE, MONITOR VIRTUAL SUMMARY, MONITOR
AWT RESOURCE.
• SystemType, CliqueNo, NetAUp and NetBUp to MONITOR
PHYSICAL CONFIG.
• CurrentVersion to MONITOR VERSION.
• Added the following:
• MonitorAMPLoad, GetPSFVersion, MonitorPhysicalConfig, and
QueryBandReservedNames_TBF functions and the
QueryBandReservedNames view.
• Several new fields to MONITOR WD, MonitorWD, TDWM
SUMMARY and TDWMSummary.
• Updated the following:
• The “Input Data” and “Statement Type” topics of several of the
System PMPC and Teradata Dynamic Workload Management
PM/APIs.
• The “Definition” and “Input Parameter” topics of several of the
System PMPC, Teradata Dynamic Workload Management, and
Query Band open APIs.
• Renamed VProcMonitor and VProcLogging to ResMonitor and
ResLogging in MONITOR VIRTUAL SUMMARY and
MonitorVirtualSummary.
• Changed the following in the PM/APIs (CLIv2 interfaces):
• The DataInfo and Record Parcel length to 64100.
• All CHAR data type fields to VARCHAR.
November 2011
Application Programming Reference
5
Preface
Additional Information
Additional Information
URL
Description
www.info.teradata.com/
Use the Teradata Information Products Publishing Library site
to:
• View or download a manual:
1 Under Online Publications, select General Search.
2 Enter your search criteria and click Search.
• Download a documentation CD-ROM:
1 Under Online Publications, select General Search.
2 In the Title or Keyword field, enter CD-ROM, and click
Search.
• Order printed manuals:
Under Print & CD Publications, select How to Order.
www.teradata.com
The Teradata home page provides links to numerous sources of
information about Teradata. Links include:
• Executive reports, white papers, case studies of customer
experiences with Teradata, and thought leadership
• Technical information, solutions, and expert advice
• Press releases, mentions and media resources
www.teradata.com/t/TEN/
Teradata Customer Education designs, develops and delivers
education that builds skills and capabilities for our customers,
enabling them to maximize their Teradata investment.
tays.teradata.com/
Use Teradata @ Your Service to access Orange Books, technical
alerts, and knowledge repositories, view and join forums, and
download software patches.
developer.teradata.com/
Teradata Developer Exchange provides articles on using
Teradata products, technical discussion forums, and code
downloads.
To maintain the quality of our products and services, we would like your comments on the
accuracy, clarity, organization, and value of this document. Please email teradatabooks@lists.teradata.com.
Teradata Database Optional Features
This book may include descriptions of the following optional Teradata Database features and
products:
6
•
Teradata Row Level Security
•
Teradata Columnar
Application Programming Reference
Preface
Teradata Database Optional Features
•
Teradata Temporal
•
Teradata Virtual Storage (VS)
You may not use these features without the appropriate licenses. The fact that these features
may be included in product media or downloads, or described in documentation that you
receive, does not authorize you to use them without the appropriate licenses.
Contact your Teradata sales representative to purchase and enable optional features.
Application Programming Reference
7
Preface
Teradata Database Optional Features
8
Application Programming Reference
Table of Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3
Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3
Supported Software Releases and Operating Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3
Changes to This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4
Additional Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6
Teradata Database Optional Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6
Chapter 1: Workload Management Concepts . . . . . . . . . . . . . . . . . . 15
Workload Management API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
API Categories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
PM/APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Open APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Differences Between Open APIs and PM/APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Requirements for Using the API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PM/APIs (CLIv2 Requests) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Open APIs (SQL Interfaces) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Required Privileges. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Related Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
18
18
18
18
19
Chapter 2: Workload Management API Features and
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
System PMPC API Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Types of Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Examples of Job Control Support Applications Using PM/APIs . . . . . . . . . . . . . . . . . . .
Examples of Open APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Functionality. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
21
21
24
26
26
Teradata Dynamic Workload Management API Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Examples Using Open APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Functionality. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Application Programming Reference
9
Table of Contents
Query Band API Features. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32
Examples Using PM/API and Open APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .33
Functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34
Chapter 3: PM/API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35
PM/API Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35
Creating a Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35
Setting Indicator or Record Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .36
Response Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37
Parcel Ordering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37
Buffer Allocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .38
Abort Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .38
Logging On . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .39
Logging Off . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40
Warning and Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40
Comparisons Between PM/API and Teradata SQL Requests . . . . . . . . . . . . . . . . . . . . . . . . . . .40
Similarities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41
Differences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41
Keywords/Reserved Words . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42
Using Teradata SQL GRANT and REVOKE Statements . . . . . . . . . . . . . . . . . . . . . . . . . . .42
Using the CLIv2 ABORT SESSION Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42
PM/API Dynamic Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43
Monitoring Rates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43
Session-Level Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .44
Resource Usage Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .44
Logging Resource Usage Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45
Collection and Logging Rates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45
Chapter 4: System PMPC APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .47
PM/APIs (CLIv2 Requests) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .48
Common Warning and Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .48
ABORT SESSION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50
IDENTIFY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .61
MONITOR AWT RESOURCE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .69
MONITOR PHYSICAL CONFIG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .77
MONITOR PHYSICAL RESOURCE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .83
MONITOR PHYSICAL SUMMARY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .93
10
Application Programming Reference
Table of Contents
MONITOR SESSION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Collecting Session Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Unreported Session Partitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
A Down Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Internal Sessions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Response Parcel Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
101
104
105
105
105
108
MONITOR SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
MONITOR VERSION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
MONITOR VIRTUAL CONFIG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
MONITOR VIRTUAL RESOURCE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
MONITOR VIRTUAL SUMMARY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
MONITOR WD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
SET RESOURCE RATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
SET SESSION ACCOUNT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
SET SESSION RATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
Open APIs (SQL Interfaces). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
AbortListSessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
AbortSessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
IdentifyDatabase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
IdentifySession . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
IdentifyTable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
IdentifyUser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
MonitorAMPLoad . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
MonitorAWTResource. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
MonitorMySessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
MonitorPhysicalConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
MonitorPhysicalResource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
MonitorPhysicalSummary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
MonitorSession . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
MonitorSessionRate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
MonitorSQLCurrentStep . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
MonitorSQLSteps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
MonitorSQLText. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
MonitorSystemPhysicalConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
MonitorVirtualConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
MonitorVirtualResource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
MonitorVirtualSummary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
MonitorWD. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
MonitorWDRate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
Application Programming Reference
11
Table of Contents
SetResourceRate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .290
SetSessionAccount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .292
SetSessionRate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .294
Chapter 5: Teradata Dynamic Workload Management
APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .297
PM/APIs (CLIv2 Requests) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .298
EVENT STATUS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .299
PERFGROUPS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .308
TDWM DELAY REQUEST CHANGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .313
TDWM EXCEPTIONS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .316
TDWM LIST WD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .321
TDWM STATISTICS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .324
TDWM SUMMARY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .335
TDWM WD ASSIGNMENT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .341
USER EVENT CONTROL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .345
Open APIs (SQL Interfaces). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .348
GetPSFVersion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .349
TDWMAbortDelayedRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .350
TDWMApply. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .352
TDWMAssignWD. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .354
TDWMEventControl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .356
TDWMEventMapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .358
TDWMEventStatus. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .360
TDWMExceptionRate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .364
TDWMExceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .365
TDWMGetDelayedQueries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .369
TDWMGetDelayedUtilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .373
TDWMInquire . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .375
TDWMListWDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .376
TDWMLoadUtilStatistics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .378
TDWMReleaseDelayedRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .380
TDWMRuleControl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .382
TDWMSetLimits. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .383
TDWMSummary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .384
TDWMSummaryRate. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .388
12
Application Programming Reference
Table of Contents
TDWMThrottleStatistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389
Chapter 6: Query Band APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393
PM/API (CLIv2 Request) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394
MONITOR QUERYBAND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
Open APIs (SQL Interfaces). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398
GetQueryBand. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
GetQueryBandPairs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400
GetQueryBandSP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402
GetQueryBandValue. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403
GetQueryBandValueSP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404
MonitorQueryBand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406
QueryBandReservedNames_TBF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408
Appendix A: Sample PM/API Application . . . . . . . . . . . . . . . . . . . . . . . 411
Sample Application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411
Header File for Sample PMPC Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425
Appendix B: Combination PEState and AMPState
Response Values for MONITOR SESSION . . . . . . . . . . . . . . . . . . . . . . . 437
Sample MONITOR SESSION Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437
Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443
Application Programming Reference
13
Table of Contents
14
Application Programming Reference
CHAPTER 1
Workload Management
Concepts
Workload Management API
Workload management API consists of interfaces to PM/APIs and open APIs. You can use
these interfaces to:
•
Monitor system and session-level activities.
•
Manage Teradata Active System Management (ASM) rules.
•
Update components stored in a custom database called TDWM.
•
Track system usage and manage task priorities.
API Categories
PM/APIs, also called CLIv2 requests, and open APIs, also called SQL interfaces (such as UDFs
and external stored procedures) are divided into the following three categories:
•
System PMPC
•
Teradata Dynamic Workload Management
•
Query Band
The following diagram shows how:
•
The System PMPC, Teradata Dynamic Workload Management, and Query Band CLIv2
requests write to the PMPC subsystem through the MONITOR partition.
•
The System PMPC, Teradata Dynamic Workload Management, and Query Band SQL
interfaces write to the PMPC subsystem through the SQL partition.
•
Some of the Teradata Dynamic Workload Management SQL interfaces (such as the
TDWMRuleControl and TDWMSetLimits external stored procedures) write directly to
the TDWM database.
Application Programming Reference
15
Chapter 1: Workload Management Concepts
PM/APIs
Open APIs
(also called SQL Interfaces)
Consists of User-Defined Functions and
External Stored Procedures
PM/APIs
(also called CLIv2 Requests)
System PMPC
Teradata Dynamic
Workload Management
Query Band
System PMPC
Teradata Dynamic
Workload Management
Query Band
SQL Partition
Monitor Partition
PMPC Subsystem
TDWM Database
1090A001
For more information on these APIs, see:
•
Chapter 2: “Workload Management API Features and Examples”
•
Chapter 4: “System PMPC APIs”
•
Chapter 5: “Teradata Dynamic Workload Management APIs”
•
Chapter 6: “Query Band APIs”
PM/APIs
PM/APIs provide access to PMPC routines resident in Teradata Database. The PMPC
subsystem is available through a logon partition called MONITOR, using a specialized
PM/API subset of CLIv2.
PM/APIs have the following features:
•
CLIv2 data is acquired in near real time, with less overhead and minimal possibility of
being blocked. These capabilities allow frequent in-process performance analysis.
•
A CLIv2 request saves the raw data in an in-memory buffer where a client application
program can easily retrieve the data for real-time analysis or importing into custom
reports.
•
A CLIv2 request provides access to data that the resource usage does not. For example,
session-level resource usage data, and data on application locks and which application is
being blocked.
Using PM/APIs may not be the right choice for all performance monitoring requirements.
Standard performance monitoring tools and reports, such as Teradata Viewpoint and resource
usage reports, may be sufficient.
For more information on how the PMPC subsytem manages CLIv2 requests, see the diagram
in “API Categories” on page 15
16
Application Programming Reference
Chapter 1: Workload Management Concepts
Open APIs
Open APIs
The workload management open API provides an SQL interface to the PMPC subsystem
through user-defined functions (UDFs) and external stored procedures.
The following are examples of some of the UDFs and external stored procedures used:
Use the ...
To ...
AbortSessions function
abort queries submitted by a set of users that have been
running longer than 10 minutes and have been skewed by
more than 10% for 5 minutes.
TDWMRuleControl function
temporarily enable a rule to block an application from
accessing a database while it is synchronized between two
active systems.
GetQueryBandValue procedure
query the DBQLogTbl based on specified names and
values in the QueryBand field.
Most of the SQL interfaces available to the PMPC subsystem provide similar functionality to
the CLIv2 interfaces.
Note: Most open APIs do not follow transaction rules. If, within a transaction, a UDF or
external stored procedure is called that performs an action (for example, setting a session
account string) and the transaction rolls back, the action of the UDF or external stored
procedure is not rolled back.
However, those interfaces that update the TDWM database, such as the TDWMRuleControl,
TDWMObjectAssn, and TDWMSetLimits procedures, must follow transaction rules. If one of
these interfaces is called within a transaction, the update will be rolled back if the transaction
is aborted.
Differences Between Open APIs and PM/APIs
The following table describes the differences between open APIs (that is, SQL interfaces
consisting of UDFs or external stored procedures) and PM/APIs.
Open APIs...
WHERE PM/APIs...
are issued in the current SQL partition
require logging on to the MONITOR partition. To
view a diagram of the process, see “API Categories”
on page 15.
require EXECUTE privilege on the function
or external stored procedure
require MONITOR privileges.
Application Programming Reference
17
Chapter 1: Workload Management Concepts
Requirements for Using the API
Open APIs...
WHERE PM/APIs...
use SQL parsing, dispatching steps, and UDF
processing
require use of a custom CLI application in C or
some other programming language.
run in priority of account string or by the
Teradata dynamic workload management
software classification
run in the system priority.
can be placed on a Teradata dynamic
workload management software delay queue
and can block system resources
do not block.
use AMP Worker Tasks (AWTs)
are not subject to running out of resources (AWTs).
Requirements for Using the API
PM/APIs (CLIv2 Requests)
You must install CLIv2 on a client machine where the PM/API application is running.
Open APIs (SQL Interfaces)
The SQL interfaces to workload management already exist if the DIPDEM and DIPTDWM
scripts have been run as part of the Teradata Database installation.
For information on the DIPDEM or DIPTDWM scripts, see Utilities.
Required Privileges
Each API described in this document, except for the MONITOR VERSION request, has its
own required privileges.
Below are some examples of the required privileges:
•
To issue the ABORT SESSION and MONITOR SESSION requests, you must have the
ABORTSESSION and MONSESSION privileges respectively as part of your default role or
these privileges must be granted directly to you.
•
To issue the MONITOR AWT RESOURCE, MONITOR VIRTUAL RESOURCE, and
MONITOR PHYSICAL RESOURCE requests, you must have the MONRESOURCE
privilege as part of your default role or this privilege must be granted directly to you.
•
To access the UDFs and external stored procedures, the DBA must grant EXECUTE
FUNCTION and EXECUTE PROCEDURE privileges to you. These privileges are not
granted by default.
For more information on roles and privileges, see Database Administration and Security
Administration.
18
Application Programming Reference
Chapter 1: Workload Management Concepts
Requirements for Using the API
Related Topics
For more information ...
See ...
on the response buffer
“Buffer Allocation” on page 38.
on defining the buffer size as part of the API
input
“Sample Input” on page 142.
on how to code an application that uses the
CLIv2 requests in this book
Teradata Call-Level Interface Version 2 Reference
for Mainframe-Attached Systems or Teradata
Call-Level Interface Version 2 Reference for
Network-Attached Systems
Application Programming Reference
19
Chapter 1: Workload Management Concepts
Requirements for Using the API
20
Application Programming Reference
Workload Management
API Features and Examples
CHAPTER 2
This chapter describes the functionality and features of the Workload Management API,
which consists of interfaces to System PMPC, Teradata Dynamic Workload Management, and
Query Band, and provides examples of each.
System PMPC API Features
Types of Tasks
Data Collection
System PMPC requests, except MONITOR VERSION and MONITOR SQL, are based on
periodic data collection. The Resource Sampling Subsystem (RSS) rates at which the resource
data is gathered (collection rate) and written to the resource usage tables (logging rate) are set
separately.
You can control the session-level collection rate, the resource collection rate, and the resource
logging rate. You can set all collection rates for any interval between 0 and 3600 seconds. For
other rules governing logging rates, see Resource Usage Macros and Tables.
A single master resource collection system within the Teradata Database collects all
performance monitoring data. It can be accessed in a number of ways, such as using the CLIv2
requests or SQL interfaces. Collection rates that are set this way can be reset by using the
Database Window utility or Teradata Viewpoint.
Care should be taken to integrate the various performance monitoring tasks on your system to
avoid potential conflicts.
Note: Because resource usage data is collected in different memory repositories than sessionlevel data, changes in the resource collection rate have no impact on session-level usage data,
and vice versa.
The following table describes the various types of monitoring rates that are set using the
following APIs:
•
The SET RESOURCE RATE and SET SESSION RATE requests.
•
The SetResourceRate and SetSessionRate functions.
Application Programming Reference
21
Chapter 2: Workload Management API Features and Examples
System PMPC API Features
Rate
Description
Global session
(SesMonitorSys)
monitoring
Sets the maximum acceptable age of collected session-level data in
memory to the PM/API application or end user.
This rate is returned as SesMonitorSys value in a MONITOR VIRTUAL
SUMMARY request.
The global session rate impacts all MONITOR SESSION requests unless
local session rate is set.
Local session
(SesMonitorLoc)
monitoring
Sets the maximum acceptable age of collected session-level data in
memory for an individual Monitor partition session that submits a
MONITOR SESSION request.
This rate is returned as SesMonitorLoc value in a MONITOR VIRTUAL
SUMMARY request.
By default the local session rate is the same as the global session rate.
Note: A change to the local collection rate could affect the cumulative
data that other users see because all session usage data is stored in the
same memory repository.
Because changes to either the global or local rate can reset the starting
point at which data is collected and may alter cumulative session usage
data, it is important to restrict the granting of session monitoring
privilege to users trained in the use of system monitoring tools, for
example, the system or database administrator or certain application
programmers.
This rate is not saved on disk and is lost during a system outage.
Resource monitoring
(ResMonitor)
Sets the interval in seconds at which all resource usage data is collected
within memory for reporting via the PM/API.
The resource monitoring rate is returned as a ResMonitor data value in a
MONITOR PHYSICAL SUMMARY or MONITOR VIRTUAL
SUMMARY request.
You can use the SampleSec field of MONITOR PHYSICAL RESOURCE to
view the current rate. This field is equivalent to the ResMonitor field.
Resource logging
(ResLogging)
Sets the interval in seconds at which resource usage data is written to the
resource usage tables.
The resource logging rate is returned as a ResLogging data value in a
MONITOR PHYSICAL SUMMARY or MONITOR VIRTUAL
SUMMARY request.
22
•
Data collection rates must be set to a nonzero value for all data fields called by a CLIv2
request or SQL interface or the fields will not contain any data.
•
Because all rates, except for the local session monitoring rate, are saved on disk every time
they are altered, they are “remembered” during restarts.
Application Programming Reference
Chapter 2: Workload Management API Features and Examples
System PMPC API Features
Related Topics
FOR ...
SEE ...
information on global and local rates
• “SET SESSION RATE” on page 187.
• “MONITOR VIRTUAL SUMMARY” on
page 159.
information on resource monitoring and
logging rates
• “SET RESOURCE RATE” on page 179.
• “MONITOR PHYSICAL SUMMARY” on
page 93.
• “MONITOR VIRTUAL SUMMARY” on
page 159.
comparative information on setting logging
rates
• “Control GDO Editor (ctl)” in Utilities.
• Resource Usage Macros and Tables.
• Teradata Viewpoint User Guide
comparative information on setting collection
rates
• “Database Window (xdbw)” in Utilities.
• Teradata Viewpoint User Guide.
System-Level Monitoring
System PMPC allows you to perform two types of system monitoring:
•
•
Physical resources
•
Nodes availability
•
BYNET availability
Virtual resources (vprocs)
•
Access Module Processor (AMP) status, performance and utilization
•
Parsing Engine (PE) status, performance and utilization
Resource utilization data is collected and reported differently from session utilization data.
Whereas some of the session usage data is collected cumulatively, resource data is collected for
a particular collection period. The resource data reported is based on the activity that
occurred during that collection period and does not include any cumulative data over
collection periods. For example, if you set the resource usage collection interval to 60 seconds
and issue a MONITOR VIRTUAL RESOURCE request (or a MonitorVirtualResource
function) or MONITOR PHYSICAL RESOURCE request (or MonitorPhysicalResource
function), a report is issued for that specific 60-second interval.
Any data you do not examine within the 60 seconds is lost when it is overwritten by data
collected during the next 60-second collection interval.
Resource usage data and session-level usage data are deposited in separate global data
collection areas. The data in the repository is updated once each collection period. All users
share the data, which is used to generate responses.
Session-Level Monitoring
Session-level monitoring tasks return the following information:
Application Programming Reference
23
Chapter 2: Workload Management API Features and Examples
System PMPC API Features
•
Identification of blocking users, sessions and locked databases or tables
•
Session-level usage data on:
•
•
AMPs
•
CPUs
Identification of problem SQL requests, including:
•
Current session
•
Current step
•
SQL text EXPLAIN data
Some of the session-level utilization data is collected cumulatively. The session rate is used to
limit the frequency at which cumulative data is updated. For example, if you set the session
rate to 60 seconds and issue a MONITOR SESSION request every 60 seconds, session-level
usage data and request-level usage data is cumulatively totaled and updated every 60 seconds.
Cumulative type session-level or request-level data reported includes data from the beginning
of the session or request.
Monitor Locks
Locks may occur when sessions, utilities, and applications being run by specific users block
access to databases or tables normally available from the Teradata Database. Interfaces to
System PMPC can help you monitor locks.
To help determine the user causing a block and the locked database or table, you can use the
MONITOR SESSION request or the MonitorSession function. Then, to get more specific
information about the blocking session and the object being blocked, you can use the
IDENTIFY request or IdentifySession, IdentifyUser or IdentifyTable functions.
To learn more about the interfaces used to perform these functions, see Chapter 4: “System
PMPC APIs.”
Examples of Job Control Support Applications Using PM/APIs
This section explains two advanced examples of potential job control support applications
that use CLIv2 requests:
•
Resource Supervisor
•
Idle Session Logoff
They are explained at a high level so that, by understanding the concepts, you can develop
similar applications at a customer site for monitoring and controlling the use of Teradata
Database resources.
Resource Supervisor
A Resource Supervisor prevents runaway queries. Runaway queries are sometimes a problem
at a site where end users can access the Teradata Database to make ad hoc Teradata SQL
requests. A badly formulated query (for example, one missing constraint on a WHERE clause)
could inadvertently cause a product join, which consumes more resources than the user
intended. Further, a user making an ill-formed SQL statement might request a join on two big
24
Application Programming Reference
Chapter 2: Workload Management API Features and Examples
System PMPC API Features
tables, which unintentionally results in a Cartesian product join. The Resource Supervisor
aborts transactions that exceed a certain resource usage threshold.
You can write a Resource Supervisor for Teradata Database to use features available in the
request as shown in the example below.
1
Program the SET SESSION RATE request to set a reasonable session-level collection rate,
for example, 10 minutes.
2
Based on the session-level rate, program the client application to issue a MONITOR
SESSION request for all sessions or for a subset of sessions (for example, if users from a
specific client are the only ones to be governed).
3
For each session returned to the client, program the client application to check some
site-specific criteria to see if the session is a candidate for the Resource Supervisor.
For example, interactive users are required to have INTERACTIVE as the first word of
their account string. If only interactive users are to be monitored by the Resource
Supervisor, all sessions that do not include INTERACTIVE as the first word of the
UserAccount value returned by a MONITOR SESSION request are ignored.
4
For those sessions that are candidates for the Resource Supervisor, program the client
application to look at the AMPCPUSec, PECPUSec, and AMPIO values to determine if
some site-specific maximum acceptable value has been exceeded.
These session values are cumulative and may not be appropriate for use as a Governor
limit because you are limiting the total resource usage of a session and not of a request.
5
Program the client application to keep a history of all previous cumulative values of
AMPCPUSec, PECPUSec, and AMPIO, plus current XactCount (transaction count) and
ReqCount (request count) values for each session.
The difference between the historical value and the current value tells you the resources
used. The request count and transaction count values tell you if they are consumed as part
of the current transaction or as part of the new request.
6
If the Resource Supervisor determines that a particular session has exceeded site-specific
limits, program the client application to issue an ABORT SESSION request for those
session that have exceeded the limits.
The client application can specify the logoff option for the ABORT SESSION request,
depending on how severely the offending session is controlled.
Idle Session Logoff
An Idle Session Logoff application automatically logs off users whose sessions have been idle
for a certain length of time. This job control support feature prevents users from walking away
from a terminal and allowing unauthorized users access to sensitive information.
You can write an Idle Session Logoff application program using the requests described below.
1
Program the SET SESSION RATE request to set a reasonable session-level collection rate,
for example, 10 minutes.
Application Programming Reference
25
Chapter 2: Workload Management API Features and Examples
System PMPC API Features
2
Based on the session-level rate, program the client application to issue a MONITOR
SESSION request for all sessions or for a subset of sessions (for example, if users from a
specific client are the only ones to be monitored for idle sessions).
3
For each session returned to the client, check some site-specific criteria to see if the session
is a candidate for Idle Session Logoff.
For example, interactive users are required to have INTERACTIVE as the first word of
their account string. If only interactive users are to be monitored by the Resource
Supervisor, all sessions that did not have INTERACTIVE as the first word of the
UserAccount value returned by a MONITOR SESSION request are ignored. Those
sessions with the INTERACTIVE label proceed through the next step.
4
For sessions that are candidates for Idle Session Logoff, program the client application to
verify the following conditions to determine whether the session has been inactive for the
duration of the collection period:
•
AMPState and PEState are idle.
•
The session was idle during the last MONITOR SESSION request.
•
XactCount and ReqCount values did not change during the last MONITOR SESSION
request.
If all these conditions are met, the session has been inactive for the duration of the
collection interval and is a candidate for automatic logoff.
5
Program the client application to issue an ABORT SESSION request with the logoff option
for the sessions that are candidates for automatic logoff.
Examples of Open APIs
The following table describes the different uses of the System PMPC open APIs.
You can ...
To ...
execute the MonitorSession and AbortSessions
functions
create a query that aborts queries submitted by a
set of users that have been running longer than
10 minutes and have been skewed by more than
30% for 20 minutes.
execute the MonitorSession and
SetSessionAccount functions
change the account string.
execute the MonitorSession or MonitorSQLText
functions
display the SQL of all active sessions that have
run over 20 minutes.
select the blocked fields of the MonitorSession
function
display the block information of all blocked
sessions.
Functionality
The following table describes the System PMPC interfaces that are used to show how
efficiently Teradata Database is using its resources, to identify problem sessions and users, and
to abort sessions and users having a negative impact on system performance.
26
Application Programming Reference
Chapter 2: Workload Management API Features and Examples
System PMPC API Features
IF you want to ...
abort any outstanding
requests or transactions of
one or more sessions
THEN use the following SQL
interface...
OR use the following CLIv2
request ...
“AbortSessions” on page 198
“ABORT SESSION” on page 50
or
“AbortListSessions” on page 195
return the name of a user,
by session, who is causing a
block
“IdentifySession” on page 202
“IDENTIFY” on page 61
return the name of the
specified table ID
“IdentifyTable” on page 203
“IDENTIFY” on page 61
return the name of the
specified user ID who is
causing a block.
“IdentifyUser” on page 204
“IDENTIFY” on page 61
collect statistics on AMPs
based on the inuse AMP
Worker Tasks (AWTs)
“MonitorAMPLoad” on page 205
or “MonitorAWTResource” on
page 207
“MONITOR AWT
RESOURCE” on page 69
collect session information
for the current user on the
current host
“MonitorMySessions” on
page 211
—
collect overall information
on node availability
“MonitorPhysicalConfig” on
page 227
“MONITOR PHYSICAL
CONFIG” on page 77
collect RSS data and returns
node-specific data
“MonitorPhysicalResource” on
page 230
“MONITOR PHYSICAL
RESOURCE” on page 83
collect global summary
information
“MonitorPhysicalSummary” on
page 235
“MONITOR PHYSICAL
SUMMARY” on page 93
return session or request
resource usage statistics
“MonitorSession” on page 240
“MONITOR SESSION” on
page 101
return session rate
“MonitorSessionRate” on
page 256
“MONITOR SESSION” on
page 101
return data about the step
being executed of the
currently running request
“MonitorSQLCurrentStep” on
page 258
“MONITOR SQL” on page 128
return the step information
of the current or running
request
“MonitorSQLSteps” on page 260
“MONITOR SQL” on page 128
return the SQL text of the
request currently being
executed for the specified
host, session, and vproc
“MonitorSQLText” on page 263
“MONITOR SQL” on page 128
Application Programming Reference
27
Chapter 2: Workload Management API Features and Examples
Teradata Dynamic Workload Management API Features
THEN use the following SQL
interface...
OR use the following CLIv2
request ...
return BYNET status and
system type values that are
generated once for the
entire system or collect
overall information on
node availability
“MonitorSystemPhysicalConfig”
on page 265
“MONITOR PHYSICAL
CONFIG”
collect information on
virtual processor (vproc)
availability
“MonitorVirtualConfig” on
page 267
“MONITOR VIRTUAL
CONFIG” on page 139
collect performance
information for each AMP,
PE, or TVS vproc
“MonitorVirtualResource” on
page 269
“MONITOR VIRTUAL
RESOURCE” on page 146
collect global summary
information on system
utilization
“MonitorVirtualSummary” on
page 275
“MONITOR VIRTUAL
SUMMARY” on page 159
return ResUsageSps data
from the RSS SPS memory
buffer
“MonitorWD”
“MONITOR WD”
return a subset of the RSS
ResUsageSps data or return
the collection rate, number
of nodes with at least one
online AMP, and number of
nodes with at least one
online PE
“MonitorWDRate”
“MONITOR WD”
set either the:
“SetResourceRate” on page 290
“SET RESOURCE RATE” on
page 179
change the account string
for the session or for the
request.
“SetSessionAccount” on page 292
“SET SESSION ACCOUNT” on
page 183
set the global and local rates
for updating session-level
statistics in memory
“SetSessionRate” on page 294
“SET SESSION RATE” on
page 187
IF you want to ...
• ResMonitor rate
• ResLogging rate
Teradata Dynamic Workload Management API
Features
Teradata dynamic workload management software is a rule-oriented management system
capable of detecting and acting on events. It is a key component of Teradata Active System
Management (Teradata ASM).
28
Application Programming Reference
Chapter 2: Workload Management API Features and Examples
Teradata Dynamic Workload Management API Features
Note: Teradata ASM is not fully supported on Teradata appliances. For more information, see
appropriate appliance documents for further details.
Teradata Dynamic Workload Management APIs allow database administrators to:
•
Apply updates to the Teradata ASM rule categories (For descriptions of these rules, see
Teradata Viewpoint User Guide.)
•
Monitor delayed requests
•
Release or abort requests from the delay queue
•
Change or display the workload definition of a query
•
Determine the current status of Teradata ASM rules and rule sets
•
Review statistics on how Teradata ASM rule categories are affecting request processing
•
Update the System Throttle limits of a rule for Dual Active Support
•
Retrieve information about the current status of all event-related constructs
•
Add or remove an object association in Teradata Database for batch management
•
Enable or disable user-defined events for event management
For information on Teradata ASM rules and how to enable the rule categories in the Teradata
Viewpoint Workload Designer portlet, see Teradata Viewpoint User Guide.
For examples on performing these Teradata Dynamic Workload Management functions, see
“Examples Using Open APIs” on page 29.
Examples Using Open APIs
The following table describes the different uses of the Teradata Dynamic Workload
Management open APIs.
You can execute the ...
To ...
TDWMSummary function
display the current workload summary
statistics.
TDWMThrottleStatistics function
display the current delay queue statistics.
TDWMEventStatus function
display all active events.
TDWMGetDelayedQueries and
TDWMReleaseDelayedRequest functions
release all delayed queries for a specified
workload.
TDWMRuleControl function
temporarily enable a rule to block an
application for accessing a database while it is
synchronized between two active systems.
TDWMEventControl function
change the active health condition or planned
environment on the system to adjust the
throttles and, on SLES 10 or earlier systems,
adjust the Priority Scheduler weights to handle
the other dual active system being down.
Application Programming Reference
29
Chapter 2: Workload Management API Features and Examples
Teradata Dynamic Workload Management API Features
You can execute the ...
To ...
MonitorSession and TDWMAssignWD
functions
change the workload to WD-Report-High of all
active requests with a workload of WD-ReportLow.
Functionality
The following table describes the interfaces of the Teradata Dynamic Workload Management
that are used to return WDs, delayed query lists, summary data, and statistics; and update the
components stored in the TDWM database.
THEN use the following SQL
interface ...
OR use the following CLIv2
request ...
return the current type of
Priority Scheduler being used
“GetPSFVersion” on page 349
—
apply changes to the rules in
one or more the Teradata
dynamic workload
management software
categories
“TDWMApply” on page 352
—
abort a request or utility
session on the Teradata
dynamic workload
management software delay
queue
“TDWMAbortDelayedRequest”
on page 350
“TDWM DELAY REQUEST
CHANGE” on page 313
change the workload a session
or request is assigned to
“TDWMAssignWD” on
page 354
“TDWM WD ASSIGNMENT”
on page 341
activate or deactivate a userdefined event
“TDWMEventControl” on
page 356
“USER EVENT CONTROL”
on page 345
list all objects that make up
the system state
“TDWMEventMapping” on
page 358
“EVENT STATUS” on
page 299
return the currently defined
events
“TDWMEventStatus” on
page 360
“EVENT STATUS” on
page 299
collect the Teradata dynamic
workload management
software exception data from
the Teradata Database
“TDWMExceptions” on
page 365
“TDWM EXCEPTIONS” on
page 316
IF you want to ...
30
Application Programming Reference
Chapter 2: Workload Management API Features and Examples
Teradata Dynamic Workload Management API Features
THEN use the following SQL
interface ...
OR use the following CLIv2
request ...
return the collection rate
(that is, the first record of the
Teradata dynamic workload
management software
Exception CLIv2 request) or
return Teradata dynamic
workload management
software exception data from
Teradata Database
“TDWMExceptionRate” on
page 364
“TDWM EXCEPTIONS”
report if each category is
active or not
“TDWMInquire” on page 375
—
release a request or utility
session on the Teradata
dynamic workload
management software delay
queue
“TDWMReleaseDelayedRequest
” on page 380
“TDWM DELAY REQUEST
CHANGE” on page 313
return a list of the WDs
“TDWMListWDs” on page 376
“TDWM LIST WD” on
page 321
return the delayed query data
fields and delay information
from releases prior to
Teradata Database 13.10
Teradata Tools and Utilities
13.10
“TDWMGetDelayedQueries” on
page 369
“TDWM STATISTICS” on
page 324
return the utility delay queue
“TDWMGetDelayedUtilities” on
page 373
“TDWM STATISTICS” on
page 324
return the statistics on the
load utilities that are available
in the system
“TDWMLoadUtilStatistics” on
page 378
“TDWM STATISTICS” on
page 324
return statistics for throttled
database objects or throttled
workloads
“TDWMThrottleStatistics” on
page 389
“TDWM STATISTICS” on
page 324
return the Teradata dynamic
workload management
software WD summary data
fields
“TDWMSummary” on page 384
“TDWM SUMMARY” on
page 335
return the collection rate
“TDWMSummaryRate” on
page 388
“TDWM SUMMARY” on
page 335
update the EnabledFlag of the
rule and the EnabledFlag in
the base state for the rule in
the TDWM database
“TDWMRuleControl” on
page 382
—
IF you want to ...
Application Programming Reference
31
Chapter 2: Workload Management API Features and Examples
Query Band API Features
IF you want to ...
update the System Throttle
limits of a rule in the TDWM
database
THEN use the following SQL
interface ...
OR use the following CLIv2
request ...
“TDWMSetLimits” on page 383
—
Note: The updates in the TDWMRuleControl and TDWMSetLimits procedures must be
committed before calling the TDWMApply procedure. A self-deadlock occurs if the external
stored procedures that update the TDWM database and the TDWMApply are called within a
transaction, for example:
Bt;
Call TDWMRuleControl()
The updates are not committed because the TDWMRuleControl procedure is in a transaction
(that is, the rows are locked for write).
Call TDWMApply(200, 'Y','N','N','N');
The TDWM database waits on the locked tables.
Query Band API Features
Query banding is a method for tracking system usage and managing task priorities. A query
band is a list of “name=value” pairs in a string contained within apostrophes that is defined by
the user or middle-tier application as shown below.
'org=Finance;report=EndOfYear;universe=west;'
Note: The name-value pairs are separated by a semicolon.
There are two types of query bands:
•
A session query band, which is stored in the session table and recovered after a system
reset.
•
A transaction query band, which is discarded when the transaction ends (for example, a
commit, rollback, or abort).
You can set a query band for the transaction and session using the SQL statement, SET
QUERY_BAND. For information on SET QUERY_BAND, see SQL Data Definition Language.
By setting a query band you can:
32
•
Identify the user, application, or report that originated the request from a middle-tiered
application.
•
Identify what user, application, report, and even what part of an application issued a
request (for example, a query band can be used for accounting, troubleshooting, and in
other types of system management operations).
•
Give requests a higher priority. For example, a query band can make a request issued for
an interactive report a higher priority than one issued for a report that generates output
files.
Application Programming Reference
Chapter 2: Workload Management API Features and Examples
Query Band API Features
•
Increase the priority of an urgent job. For example, if the CEO needs a report for a board
review that starts in 20 minutes, a query band can be used to expedite the job.
•
Create requests that make up a “job” to be grouped for accounting and control purposes.
There are several uses for query bands. A query band can be:
•
Logged by Database Query Log (DBQL). DBQL reports are created using the query band
name-values pairs to provide additional refinement for accounting and resource allocation
purposes and to assist in troubleshooting performance problems.
•
Used for rule checking and Workload Classification. Query band name-value pairs can be
associated with Teradata ASM Filter rules and defined as workload attributes (see Teradata
Viewpoint User Guide for details on these rules).
•
Used to determine the origin of a request that may be consuming system resources or
blocking other requests.
•
Used as a system variable. A query band can be set for a session and retrieved using APIs.
Through these interfaces, the following information can be retrieved:
•
The concatenated transaction and session query band for the specified session.
•
The concatenated query band for the current transaction and session.
•
The name and value pairs in the query band.
•
The value of the specified name in the current query band.
For examples on performing Query band requests and functions, see “Examples Using
PM/API and Open APIs” on page 33.
To learn more about these interfaces and how to retrieve query bands, see
Chapter 6: “Query Band APIs.”
Examples Using PM/API and Open APIs
The following table describes the different uses of the query band APIs.
You can use ...
To ...
MONITOR QUERYBAND or
MonitorQueryBand
return the concatenated query band for session
number 1102 on host ID 20 running on vproc
16383.
GetQueryBand or GetQueryBandSP
return the concatenated query band string for
the current transaction and session.
GetQueryBandValue
query the DBQLogTbl based on names and
values specified in the query band name input
argument.
GetQueryBandValueSP
search the session name-value pairs in the query
band and return the value that corresponds to
the query band name “aa.”
GetQueryBandPairs
return the query band in name and value
columns.
Application Programming Reference
33
Chapter 2: Workload Management API Features and Examples
Query Band API Features
Functionality
The following table describes the query band interfaces that are used to track system usage and
manage task priorities.
IF you want to ...
THEN use the following SQL
interface ...
THEN use the following CLIv2
request ...
return the name and value pairs
in the query band
“GetQueryBandPairs” on
page 400
—
return the concatenated query
band for the current transaction
and session
“GetQueryBand” on page 399
—
or
“GetQueryBandSP” on
page 402
return the value of the specified
name in the current query band
“GetQueryBandValue” on
page 403
—
or
“PurposeGetQueryBandValueS
P” on page 404
34
return the concatenated query
band for the specified session
“111MonitorQueryBand” on
page 406
“MONITOR QUERYBAND”
on page 395
return all query band names
and descriptions, including
those dropped from a release
“QueryBandReservedNames_T
BF” on page 408
—
Application Programming Reference
CHAPTER 3
PM/API
This chapter describes how each MONITOR request processes the following PM/APIs (also
called CLIv2 requests) issued to Teradata Database by an end-user application interface on a
client:
•
System PMPC
•
Teradata Dynamic Workload Management
•
Query Band
The client can be either a channel-attached mainframe or a network-attached workstation.
PM/API Processing
The CLIv2 is used to write end-user application interfaces to PM/API routines. CLIv2, a
Teradata proprietary API and library, is the interface between your application and the
Teradata Director Program. Teradata Director Program is the interface between CLIv2 and the
Teradata Database. For an example of CLIv2, see Appendix A: “Sample PM/API Application.”
Whether the client application interface you develop is a simple utility or a complex system,
the process is the same. Because the PM/API uses CLIv2 directly, it processes requests and
responses in much the same way that CLIv2 does for a Teradata SQL application. No changes
are required in CLIv2 to support PM/API. As a result, PM/API capabilities on Teradata
Database are available on any client platform that supports CLIv2. If you can write a CLIv2
program, you can access PM/API routines.
For more detailed information on the uses of CLIv2 for the interfaces described in this
chapter, see:
•
Teradata Call-Level Interface Version 2 Reference for Mainframe-Attached Systems
•
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
Creating a Request
Your client application program tells CLIv2 what to do by creating a request string consisting
of:
•
A request parcel (when the response is desired in record mode) or an IndicReq parcel
(when the response is desired in indicator mode).
When the response mode option is set in CLI, CLIv2 automatically uses the correct request
parcel format.
•
A USING Data String, which contains the input data.
Application Programming Reference
35
Chapter 3: PM/API
PM/API Processing
Unlike Teradata SQL, PM/API does not use a USING Phrase to name the variables and
reserve space in the request parcel. Instead, each MONITOR request has a USING Data
String of a particular fixed format that determines the order of items, their data types, and
lengths.
Because a USING Data String is required, either a data parcel must follow a request parcel or
an IndicData parcel must follow an IndicReq parcel.
An IndicData parcel is recommended, because several of the fields in the USING Data String
can be NULL.
Generating an IndicReq parcel results in a response that contains a PclDataInfo parcel, which
describes the number of response columns. Each Record parcel returned begins with a
number of presence bits, that supply the NULL indicators for the result columns.
To pass PM/API requests to Teradata Database as the text portion (body field) of the request
parcel, the application program calls the CLIv2 DBCHCL routine with the DBCAREA
function code (4) set to the Initiate Request operation. Code your application program to do
the following before calling CLIv2 for the Initiate Request operation:
•
Set the request pointer to the address of a character string containing the request name.
Note: For the IDENTIFY request, set the request pointer to the address of a character
string containing one of the following:
•
IDENTIFY SESSION
•
IDENTIFY DATABASE
•
IDENTIFY USER
•
IDENTIFY TABLE
•
Set the request length to the length in bytes of the character string.
•
Set the USING Data pointer to the address of the USING Data String.
•
Set the USING Data Length to the length in bytes of the USING Data String.
Setting Indicator or Record Mode
You can send the USING Data String in either indicator mode or record mode. CLI must
inform CLIv2 which mode is used by setting the appropriate use presence bits option in the
DBCAREA.
36
IF you want...
THEN...
to send the USING Data
String in indicator mode
the indicator (presence) bits must be provided by CLI.
Note: The use presence bits option is usually set to a default value
for the site.
Application Programming Reference
Chapter 3: PM/API
PM/API Processing
IF you want...
THEN...
to change the default value
do the following:
1 Set change options to Y in the application program.
2 Set the use presence bits option in the DBCAREA to Y.
Note: This also allows the application program to send NULL
data to the Teradata Database system.
the USING Data String sent
in record mode
do the following:
1 Set change options to Y in the application program.
2 Set the use presence bits option to N in the DBCAREA in the
application program.
Response Processing
PM/API requests are processed similarly to Teradata SQL requests because CLIv2 is used for
both. Response processing is similar in both parcel ordering and buffer allocation. For an
example CLI program, see Appendix A: “Sample PM/API Application.”
Just as input data can be sent to the Teradata Database in indicator or record mode, the
response can be returned from the Teradata Database in either indicator or record mode,
depending on how the response mode option is set in CLIv2. You can set response mode to be
independent of input data mode. For example, it may be more convenient to send the input
data in record mode, but the response may require indicator mode if NULL is expected.
Response mode is usually set to a default value for the site. If you want to change the default
value set, change options to Y in the application program.
IF you want to return data in…
THEN set the response mode option in DBCAREA to…
indicator mode
I for Indicator. CLIv2 automatically uses the correct request parcel
format.
record mode
R for Record. CLIv2 automatically uses the correct request parcel
format.
Note: Field mode, represented by F, is not supported in a PM/API request.
Parcel Ordering
The response returned from a MONITOR request is a series of parcels constructed by Teradata
Database and sent to the client.
The basic parcel layout for a successful response is the same for most MONITOR requests,
except the following:
•
MONITOR SQL
•
MONITOR VERSION
Some MONITOR requests such as:
Application Programming Reference
37
Chapter 3: PM/API
PM/API Processing
•
MONITOR SESSION
•
MONITOR VIRTUAL CONFIG
•
MONITOR PHYSICAL CONFIG
•
MONITOR VIRTUAL RESOURCE
•
MONITOR PHYSICAL RESOURCE
behave like multi-statement requests, for which multiple record parcels are returned. For
request-specific parcel layout, see Chapter 4: “System PMPC APIs.”
The following table shows the parcel layout for an unsuccessful response is the same for all
MONITOR requests -- either a Failure or an Error parcel is returned.
Parcel
Name
Parcel
Flavor
Field
Length
Failure
9
15 to 267
Message code and message text: description of cause of
failure; request could not be processed. For example,
the request is aborted.
Error
49
15 to 267
Message code and message text: description of cause of
error. Application can fix the problem and resubmit the
request. For example, response buffer is too small to
hold entire response row.
Comments/Key Parcel Body Fields
Buffer Allocation
A PM/API application, like a Teradata SQL application, requires space for a:
•
Response buffer, containing the parcels transmitted back from the Teradata Database.
•
Request buffer, containing the parcels sent to the Teradata Database.
Space for these two buffers is allocated for the application by CLIv2 based on the setting of
DBCAREA arguments at the time a session is established. Default buffer sizes are controlled
by the HSHSPB (control block containing site specific information), which is created during
installation when CLI defaults are specified. The minimum size of a response buffer is 32,000
bytes.
If your response buffer is not large enough, your application program may receive an error
message. For details on error messages, see Messages.
Abort Processing
To abort your session or transaction, you can execute an asynchronous abort by using the
CLIv2 routine DBCHCL, with the DBCAREA function code (7) set to the Abort Request
operation. You can attempt an asynchronous abort on any of your MONITOR query
operations, on any rate changing operations, or on an ABORT SESSION operation itself.
If you are responsible for monitoring performance, you can abort a session or group of
sessions. For instructions, see “ABORT SESSION” on page 50.
38
Application Programming Reference
Chapter 3: PM/API
PM/API Processing
The impact of the abort depends on the type of operation running. For the following query
operations:
•
IDENTIFY
•
MONITOR PHYSICAL CONFIG
•
MONITOR PHYSICAL RESOURCE
•
MONITOR PHYSICAL SUMMARY
•
MONITOR SESSION
•
MONITOR SQL
•
MONITOR VERSION
•
MONITOR VIRTUAL CONFIG
•
MONITOR VIRTUAL RESOURCE
•
MONITOR VIRTUAL SUMMARY
The impact of the abort is described below.
IF...
THEN...
no portion of the response to the
query has been sent to the session
an Asynchronous Abort causes the Monitor to terminate its
processing of the query and transmit a failure parcel to the
client. The failure indication is user-initiated abort.
a portion of the response to the
query has been sent, but more
remains to be sent
the abort and the request response have crossed in the mail.
The Monitor ignores the abort.
all of the response has been sent to
the session
the abort and the request response have crossed in the mail.
The Monitor ignores the abort.
For rate alterations (SET SESSION RATE or SET RESOURCE RATE), processing is identical
to Teradata SQL treatment of a single-statement transaction as shown on the following table.
IF the response to the request has...
THEN the...
not yet been sent to the session
Monitor terminates its processing of the request, backs out
any alteration already made by the request, and transmits a
failure parcel to the client. The failure indication is userinitiated abort.
already been sent to the session
abort and the request response have crossed in the mail. The
Monitor ignores the abort.
Logging On
A PM/API application logs on similar to a Teradata SQL application. However, there are some
differences:
•
The partition name is MONITOR. Set the following within your PM/API application:
Application Programming Reference
39
Chapter 3: PM/API
Comparisons Between PM/API and Teradata SQL Requests
•
•
The run pointer to the address of the character string containing the word MONITOR.
•
The run length to the length in bytes of the character string containing the word
MONITOR.
Your logon fails if:
•
You do not have the appropriate MONITOR privilege.
•
The PE or client that the MONITOR session is logged on to is already supporting its
maximum number of four MONITOR sessions.
Note: Currently on the PE, the load balancing mechanism does not support
MONITOR partition sessions. Session Control allocates MONITOR session requests
to the PE on which a MONITOR session is logged until the four sessions per PE limit is
reached.
•
The system-wide limitation of 128 concurrent MONITOR sessions is reached.
Logging Off
A PM/API application logs off the same way a Teradata SQL application does with one
exception. If you log off a session that has a local session monitoring rate (SesMonitorLoc) of
nonzero, the rate is changed to zero. This change is added to the DBC.SW_Event_Log table
(accessible from the DBC.Software_Event_LogV view), which is similar to what occurs if you
had issued a SET SESSION RATE request prior to logging off.
Warning and Error Messages
For a general discussion on common warning and error messages that may be returned in
response to various requests, see “Common Warning and Error Messages” on page 48.
For detailed information on the meaning of individual error and warning messages and the
response required, see Messages.
Comparisons Between PM/API and Teradata
SQL Requests
There are both similarities and differences between PM/API applications and Teradata SQL
applications, such as Basic Teradata Query (BTEQ), special utilities (for example, FastLoad),
and third party software.
40
Application Programming Reference
Chapter 3: PM/API
Comparisons Between PM/API and Teradata SQL Requests
Similarities
The similarities between a PM/API based application and a Teradata SQL based application
include:
•
Data types supported for input and output data in PM/API applications are a subset of
those data types supported by Teradata SQL.
•
Fixed length character data is blank padded on the right.
•
NULL returned for the PclRecordType response parcel is equal to NULL returned by
Teradata SQL (see “Response Parcel Groups” on page 108).
Differences
The differences between a PM/API based application and a Teradata SQL based application
are:
•
A PM/API application issues requests through a session partition named MONITOR.
•
The MONITOR partition does not support the capabilities found in a Teradata SQL
partition. The following table shows how the MONITOR partition reacts to the Teradata
SQL partition capabilities.
IF you use the Teradata SQL partition
capability...
THEN the MONITOR partition returns ...
Keep Response processing mode
an error message.
Execute a rewind operation
Run the start-up operation
Field mode request
CleanUp request
P (Prepare) or S (Setup) request processing
option of the DBCAREA
•
Keywords used by the MONITOR PM/API requests are different from keywords in
Teradata SQL. However, both have the same rules for identifiers.
•
MONITOR query processing, unlike Teradata SQL, produces dynamic data.
•
A Using Data String, which defines the input data, is always required in a PM/API
application. In Teradata SQL, it is optional.
Application Programming Reference
41
Chapter 3: PM/API
Comparisons Between PM/API and Teradata SQL Requests
Keywords/Reserved Words
The following keywords are Teradata Database reserved words:
•
ABORTSESSION
•
MONITOR
•
MONRESOURCE
•
MONSESSION
•
SETRESRATE
•
SETSESSRATE
The following keywords are Teradata Database non-reserved words that are permitted as
object names, but discouraged because of the possible confusion that may result:
•
MONSQL
•
MONVERSION
For a complete list of words that are unavailable for use as object names, see SQL
Fundamentals.
Using Teradata SQL GRANT and REVOKE Statements
If you are using a Teradata SQL based application, you can issue the GRANT and REVOKE
statements. For more information on these SQL statements, see SQL Data Control Language.
In rare cases, a change in privileges could temporarily block the request of an active
MONITOR session because the system must look up the new privileges before accepting any
more requests from the affected user. If the system query is blocked by a lock on a Teradata
Database dictionary table or if there is some other type of system processing bottleneck, you
cannot issue any MONITOR requests until you acquire the new set of privileges. However,
MONITOR requests submitted from the system console are not blocked by a change in
privileges, because no privileges are necessary to issue MONITOR requests on the system
console.
Using the CLIv2 ABORT SESSION Request
If you are using a PM/API based application, you can issue the CLIv2 ABORT SESSION
request.
With the proper privileges granted, you can abort and log off a Teradata Database user.
IF the ABORT SESSION
command...
42
THEN the Teradata Database user receives...
targets a current Teradata
Database request or session
an error message that the transaction is aborted.
targets a request or session after
the user has logged off from
Teradata Database
an error message that the session is not currently logged on.
Application Programming Reference
Chapter 3: PM/API
PM/API Dynamic Data
The error message is not returned to the user of the affected session until ABORT SESSION
completes rolling back the current transaction or, if applicable, the session is logged off.
The status of an active session determines when the error message is received.
IF, at the time you issue an ABORT
REQUEST statement and...
THEN the...
a request is outstanding for the user
session
error message is sent as a response to the current request.
no request is outstanding, but a
session is in progress
user receives the error message when the next request is
received.
For more information on this request, see “ABORT SESSION” on page 50.
PM/API Dynamic Data
When you issue a request through the Monitor partition, current and dynamic data is
reported. PM/API requests place data in a global repository (in memory), not in an
intermediary spool file (on disk). AMP, PE, node, and session-level usage data are each
collected in independent data collection global areas.
As a result, changes in the resource collection rate have no impact on session-level data, and
vice versa. Any MONITOR request, except MONITOR VIRTUAL CONFIG, MONITOR
PHYSICAL CONFIG, and IDENTIFY, may cause the memory repository to be updated on
demand (specifically, once each collection period). All users share the data in the repository,
which is used to generate responses to both queries and CONTINUE requests.
Note: If, after issuing a PM/API request, the Monitor partition session returns an error parcel
with empty error text, run the Database Initialization Program (DIP) option 1 (DIPERR),
then wait up to 60 minutes to reload the error text cache in the Monitor partition. After the
error text cache is reloaded, the error parcels will have the proper error texts. For instructions
on how to run DIP, see Utilities.
Monitoring Rates
You should be aware of the rate at which your PM/API client application requests
performance data. If a PM/API client application requests data more frequently than the
corresponding data collection rate, an individual request could potentially include data from
one collection period mixed in with data from a subsequent collection period initiated by a
different MONITOR user because common global data is shared.
However, the impact need not be detrimental. The data collected from one request when
compared with the next request may not show a change in resource usage. Follow the simple
rule that the PM/API client application must request data at the same rate, or a less frequent
rate, than the rate at which the Teradata Database collects that data.
Application Programming Reference
43
Chapter 3: PM/API
PM/API Dynamic Data
The monitoring rate is a PM/API collection rate that sets the interval in seconds at which
resource usage data is collected within memory.
Note: A physical monitoring rate is the same as a virtual monitoring rate.
There are significant differences in the way resource usage and session utilization data are
collected and reported by the MONITOR partition. For details, see “Data Collection” on
page 21 and “Collection and Logging Rates” on page 45.
Session-Level Data
Session-level data is collected cumulatively. The collection period is used to limit the
frequency of this update.
For example, if you set the SET SESSION RATE to 120 seconds and then issue a MONITOR
SESSION request every 120 seconds, session usage data is collected and cumulatively totaled
every 120 seconds.
Note: Session-level data is lost in the event of a system outage.
Data reported includes data for the beginning 120 seconds as well as for subsequent intervals.
For more information on how session usage data is collected, see “System-Level Monitoring”
on page 23.
Resource Usage Data
Resource usage data is collected based on activity during a collection period and does not
reflect cumulative data for a sequence of collection periods. For example, if you set the SET
RESOURCE RATE to 120 seconds and issue a MONITOR VIRTUAL RESOURCE or
MONITOR PHYSICAL RESOURCE request, resource usage data is collected at 120-second
intervals.
If you do not examine the data within 120 seconds or enable resource usage tables for logging,
it is lost when overwritten by data collected during the next 120-second collection interval.
Features of Using Resource Usage Data
Resource usage data features are:
44
•
Access is via SQL, not C or some other programming language
•
More detailed
•
Written to tables so past data values are available
•
Can be accumulated over a long period of time and can be used for the following:
•
Examining trends and patterns
•
Planning system upgrades
•
Deciding when to add new applications to heavily utilized systems
•
Building baseline resource usage profiles for operations
Application Programming Reference
Chapter 3: PM/API
PM/API Dynamic Data
Logging Resource Usage Data
You can retain collected data for subsequent historical analysis by enabling one or more
resource usage tables for logging. The table and type of PM/API request are listed below. For
details on the resource usage tables and pre-defined report macros, see Resource Usage Macros
and Tables.
To control the resource usage logging option (for example, setting the logging rate and
enabling one or more log tables or subtables), use the ctl utility. For instructions on using ctl,
see Utilities.
PM/API Request
Table
MONITOR PHYSICAL RESOURCE
ResUsageSpma
MONITOR PHYSICAL SUMMARY
MONITOR PHYSICAL RESOURCE
ResUsageShst
MONITOR VIRTUAL RESOURCE
MONITOR VIRTUAL RESOURCE
ResUsageSldv (Storage Devices)
MONITOR VIRTUAL SUMMARY
EVENT STATUS
ResUsageSps
MONITOR WD
MONITOR VIRTUAL RESOURCE
ResUsageSvpr
MONITOR VIRTUAL SUMMARY
MONITOR VIRTUAL RESOURCE
ResUsageSvdsk
Collection and Logging Rates
You can control the rate at which resources are monitored (collected) and, if you enable
resource logging, the interval at which a data row is to be inserted into the log table.
Setting Collection Rates
The following collection rates can be set:
•
Global session monitoring
•
Local session monitoring
•
Resource monitoring
For more information on these types of rates, see “Data Collection” on page 21.
Setting Logging Rates
You can enable logging of collected data into the resource usage tables. In this case, you also
set a logging rate that specifies how often a data row is to be inserted.
Logging is not required to collect and retrieve current data, but it does preserve data that
would otherwise be lost at the next collection interval.
Application Programming Reference
45
Chapter 3: PM/API
PM/API Dynamic Data
If you decide to enable logging, set the logging rate. The resource logging rate, also referred to
as the physical or virtual resource logging rate, sets the interval in seconds at which resource
usage data is written to the resource usage tables (see “Data Collection” on page 21). The rate
is saved on disk every time it is altered. Use the SET RESOURCE RATE request to set this rate
(see “SET RESOURCE RATE” on page 179).
The resource logging rate:
•
Can be set within the range of 0 and 3600 seconds.
•
With a value of zero indicates that logging is not being performed.
•
Returns the value ResLogging in the MONITOR PHYSICAL SUMMARY and MONITOR
VIRTUAL SUMMARY requests.
Note: A physical resource logging rate is the same as a virtual resource logging rate.
46
Application Programming Reference
CHAPTER 4
System PMPC APIs
This chapter discusses how to use the System Performance Monitor and Production Control
(PMPC) APIs to monitor system and session-level performance and to identify and abort
problem sessions and users having a negative impact on system performance.
PMPC data is available through two types of interfaces:
•
“PM/APIs (CLIv2 Requests)”
•
“Open APIs (SQL Interfaces)”
Before using the System PMPC APIs, you may want to familiarize yourself with the following
topics:
•
“PM/APIs” on page 16
•
“Open APIs” on page 17
•
“Examples of Job Control Support Applications Using PM/APIs” on page 24
Application Programming Reference
47
Chapter 4: System PMPC APIs
PM/APIs (CLIv2 Requests)
PM/APIs (CLIv2 Requests)
This section describes the System PMPC interfaces that use CLIv2 to access the PMPC data.
These interfaces are referred to as PM/API requests.
Note: The PM/API requests described in this section are shown in uppercase, although mixed
case interfaces are also supported.
Common Warning and Error Messages
Most of the monitor requests covered in this chapter depend on periodic collection of data.
When this collection process is disturbed, the returned data can temporarily become
confusing or inaccurate.
If this happens, the user receives a warning message indicating that the data returned may not
give a true picture of system or user activity.
The following are some common situations in which a warning message is provided:
•
The data returned may have been affected by a system restart or a single processor
recovery. Resource/session usage values may not be realistic until requests on the Teradata
Database re-attain their normal level of activity.
•
Data may also be incomplete in cases where:
•
A full data collection period has not transpired since the Teradata Database has gone
through a recovery.
•
A full data collection period has not transpired since the related monitoring rate was
changed.
For more detailed information on warning and error messages, see Messages.
Errors Resulting from PMPC Subsystem Failures
All MONITOR requests get their information from the PMPC subsystem. In the event of a
PMPC internal software failure, the system will generate one of several possible errors. Each of
these errors causes the PMPC subsystem to discontinue the current session to prevent the
error from crashing the entire system.
If the system encounters such an error, it takes a snapshot dump and does one of the
following:
48
•
If the internal software error occurs during the initial parsing of the System PMPC request,
the session and the interface that caused the error will be discontinued. The user can log
on again and submit other System PMPC requests, however, sometimes the internal
software error will persist. On the third instance that a PE sees the internal software error,
the PE will be shutdown for further logons. Even if this happens the PMPC subsystem may
still be available through other PEs.
•
If an internal software error occurs during a subsequent request processing task, the
system will take a snapshot dump both of the problem task and parsing task. Then it will
shut down the entire PMPC subsystem from further logons.
Application Programming Reference
Chapter 4: System PMPC APIs
PM/APIs (CLIv2 Requests)
Even though the PMPC subsystem may be partially or fully shut down due to an internal
software error, the shut down avoids a crash and allows the system to process other types
(non-PMPC) of requests. Although the system resources are cleaned up as much as possible
after such an internal software error, there may be leftover resources or tasks that stay hung
waiting on a response from the task that originally caused the error.
After encountering a PMPC subsystem internal failure, especially if a subsequent MONITOR
request results in an error, the administrator should do a manual DBS restart as soon as
possible (taking care not to unnecessarily disrupt users) to rid the system of task and resource
fragments. The administrator should also report the snapshot dump and any related errors in
the event log to the Teradata Support Center.
Application Programming Reference
49
Chapter 4: System PMPC APIs
ABORT SESSION
ABORT SESSION
Purpose
Aborts any outstanding request or transaction of one or more sessions, and optionally logs
those sessions off the Teradata Database system.
Input Data
Warning:
If an ABORT SESSION request is submitted when host_id, user_name, or session_no is either
left blank or set to NULL, an attempt is made to abort all hosts, all users, or all sessions. For
example, if you specify 127 for host_id, FRR for user_name, and NULL for session_no, ABORT
SESSION attempts to abort every and all sessions currently logged on from host 127 as user
FRR.
Element
Data Type/ Range
Description
IndByte
BYTE
Indicator bits that specify which fields to treat as NULL if
you are using indicator mode.
Each bit in the byte corresponds to one field in the input
data.
If data is supplied for that field, then set the bit to zero.
If the data for that field is NULL (that is, there is no data
supplied for that field), then set the bit to 1.
Note: The IndByte field is only required if the PM/API
request is submitted in indicator mode.
mon_ver_id
SMALLINT,
NOT NULL
MONITOR software version ID. This can be version 2 or
later.
For a general explanation of monitor version choices, see
“MONITOR VERSION” on page 136.
host_id
SMALLINT
Logical ID of a host (or client) with sessions logged on. For
example, a hostid of zero identifies internal sessions or
system console sessions.
host_id cannot exceed 1023.
50
session_no
INTEGER
Session number. session_no combined with the host_id
represents a unique session ID.
user_name
VARCHAR (30)
Name of user who is running the sessions.
Application Programming Reference
Chapter 4: System PMPC APIs
ABORT SESSION
Element
Data Type/ Range
Description
list
VARCHAR (1)
Indicator of whether to display a list of sessions.
To display a list of all session_no sessions, specify y or Y. If
you do not want to display a list of sessions, specify n, N,
NULL, or blank.
Caution:
Do not use list when large numbers of sessions
are being aborted. Otherwise, system degradation
can result, especially when the abort list contains
more than 1500 sessions. The slowdown occurs
because all of the impacted sessions must be
buffered and then sorted on a single processor.
During the sort, the processor is unavailable for
requests from any other MONITOR session
logged on to that PE. Furthermore, in extremely
rare cases, perhaps involving an abort of 10,000
sessions, the number of sessions needed to be
sorted can exhaust scratch space on the processor
and cause a system restart.
Note: If your site is running Two-Phase Commit (2PC), the
following information applies. For more information on
2PC, see Database Design.
• Do not use ABORT SESSION to abort or log off Teradata
Director Program internal sessions used for 2PC
processing. To log off the sessions, use the Teradata
Director Program command DISABLE IRF instead.
• Be sure to issue DISABLE IRF before executing ABORT
SESSION using the host_id.* or *.* parameters to avoid
any possible problem with the Teradata Director
Program.
• To identify Teradata Director Program internal sessions,
run the Teradata Director Program command DISPLAY
SESSIONS. Teradata Director Program internal sessions
have the job name *TDPINT*. (The MONITOR
SESSION request cannot identify Teradata Director
Program internal sessions.)
logoff
VARCHAR (1)
Indicator of whether to log session_no sessions off the
Teradata Database in addition to aborting them.
To log session_no sessions off the Teradata Database, specify
y or Y. To simply abort session_no sessions, specify n, N,
NULL, or blank.
Application Programming Reference
51
Chapter 4: System PMPC APIs
ABORT SESSION
Element
Data Type/ Range
Description
override
VARCHAR (1)
Indicator of whether to override an ABORT SESSION
failure.
Specify y or Y if you do not want the ABORT SESSION
request to fail in any of the following cases:
• An identified session is being session-switched.
• An identified session is executing its own ABORT
SESSION request.
• An identified session has a PEState of IDLE: IN-DOUBT
as a result of a 2PC.
Note: Sessions are marked IN-DOUBT by the 2PC
protocol, which governs how transactions are committed
by multiple systems that do not share memory. The
protocol guarantees that either all systems commit or all
roll back.
Therefore, when you specify y or Y, session_no sessions that
fit one of the above criteria are ignored, and all sessions that
do not fit any of the above criteria are aborted.
If you specify n, N, NULL, or blank, and at least one
identified session fits one of the above criteria, the ABORT
SESSION request will fail.
If you specify n or N, or do not specify this option, the entire
ABORT SESSION operation fails if any non-abortable
session is encountered. Sessions are not aborted (including
those in abortable states) and an error message is returned.
Performance and the list Option
The ABORT SESSION request is different from other PM/API requests, because as soon as
processing begins, the ABORT SESSION operation is not abortable.
Except for a small timing window (which closes when the PM/API acknowledges the ABORT
SESSION request) any Asynchronous Abort operation is ignored.
The ABORT SESSION cannot be stopped even if list displays some sessions that were included
by mistake.
Monitor Privileges
To use this request, you must have the ABORTSESSION privilege as part of your default role
or this privilege must be granted directly to you.
For more information on roles and privileges, see Database Administration and Security
Administration.
52
Application Programming Reference
Chapter 4: System PMPC APIs
ABORT SESSION
Usage Notes
Aborting a session is useful when a session causes a production job to block other sessions
waiting for locks, or when a session takes up many resources that a critical application is
running too slowly.
By default, the ABORT SESSION request aborts the current transaction for the specified
sessions and logs those sessions off the Teradata Database.
The ABORT SESSION request is logged to the DBC.SW_Event_Log table (accessible from the
DBC.Software_Event_LogV view). If you specify y or Y for logoff, records are added to
DBC.SW_Event_Log table.
ABORT SESSION will not abort nor log off a session under any of the following conditions:
•
The session status is IN-DOUBT.
•
The session is currently being session-switched.
•
The session is a Database Query Log (DBQL) artificial internal session
•
The actual session is currently executing an ABORT SESSION request.
If you attempt to abort such a session, either a diagnostic message displays indicating that
the ABORT SESSION request was not accepted, or, the ABORT SESSION request aborts
any identified sessions that do not meet the above conditions.
Although this request may abort and log off other PM/API sessions, it ignores the session
from which it was submitted. To abort your own session, use the asynchronous abort
available through Call-Level Interface (CLI). For an example CLI program, see “Appendix
A Sample PM/API Application” on page 411.
At least one of the transactions you want to abort either cannot be aborted or already is
being aborted if:
•
A session is in the final stage of an ALTER TABLE operation and cannot be aborted.
•
A user-initiated abort must complete before whatever caused the ABORT SESSION
request to be executed can be done. Therefore, if you specify list, that list will indicate
sessions that are:
•
Currently IN-DOUBT
•
Being session-switched
•
Already aborting or committing their own transactions
•
Executing an ABORT SESSION request
The ABORT SESSION request has the following impact as described in the table below.
Application Programming Reference
53
Chapter 4: System PMPC APIs
ABORT SESSION
Type of Session
Impact of
ABORT
SESSION
A session with a
transaction that is
currently being
committed or
rolled back
None
An internal
session
None
Option
Comments
with or
without
logoff
The ABORT SESSION request does not fail. Instead,
the stage 1 response from the Teradata Database
includes a warning that identified sessions are in the
process of committing or rolling back their
transactions.
The activity of such sessions is vital to the continued
execution of Teradata Database and is always
considered to be more important than any userinitiated work that may be blocked. The Teradata
Database system acts as if the internal sessions do not
appear in the optional list of sessions identified by this
request.
Note: Specify a host_id of zero to abort console Basic
Teradata Query (BTEQ) sessions.
54
A DBQL/Teradata
dynamic
workload
management
software artificial
internal session
Does not
work
This is not a real session and cannot be aborted. If you
attempt to abort this session, an error message is
returned.
A client utility
user
Little
Client utility locks are designed to survive system
outages or interruptions in the archive process, and
are not necessarily associated with an active session.
Instead, they are associated with the user who
originally submitted the archive or recovery
operation. Therefore, an ABORT SESSION request
does not necessarily remove locks placed by the client
utility and does not necessarily cause whatever
activity any such locks were blocking to become
unblocked. However, such sessions still appear in the
optional list of sessions identified by this request.
Application Programming Reference
Chapter 4: System PMPC APIs
ABORT SESSION
Type of Session
MLOAD,
FASTLOAD,
HUTCTL,
HUTPARSE, and/
or DBCUTIL
partition sessions
Impact of
ABORT
SESSION
Option
Comments
Does not
work
without
logoff
Sessions within these partitions do not have
transactions or locks associated with them. Also,
many of these partitions do not include the Teradata
SQL or PM/API ability to recover from an interrupted
request without terminating the application. That is,
these partitions are designed to be restarted, but not
rolled back. As a result, when a FastLoad, MultiLoad,
or Archive/Recovery operation needs to be
terminated, the ABORT SESSION request typically
specifies that all sessions associated with the utility job
be aborted and logged off. These utility-related
sessions appear in the optional list of sessions
identified by this request.
It is easier to kill a FastLoad, MultiLoad,
Archive /Recovery, or FastExport job by user_name
instead of by session_no. These utilities have multiple
sessions under one user_name and it makes little sense
to abort one utility session running under that
user_name and not another. However, be aware that
the same user_name may be running other sessions at
the same time and these sessions would also be
aborted and logged off.
Processing Messages
Unlike other PM/API requests, ABORT SESSION has an unpredictable execution time and
could take hours to roll back a transaction.
Therefore, upon receipt of an ABORT SESSION request, the Teradata Database sends one or
more of the following processing messages:
•
Indicates that the ABORT SESSION request has been received and is in one of the
following states:
•
Has been accepted and is in execution.
•
Cannot be accepted because resources are exhausted, because of either a heavy
workload or several ABORT SESSION requests are queued and waiting to finish
processing. Information is recorded in the error log.
Teradata Database should not restart as a result of this error. Depending on the
available resources, this request will be processed to completion after all the queued
abort requests have completed processing.
•
Lists how many sessions have been affected by the executing request (if Y was entered into
the list field).
•
Indicates the request is complete when all identified sessions have been aborted.
•
Indicates that all session have been logged off (if Y was entered into the logoff field).
Application Programming Reference
55
Chapter 4: System PMPC APIs
ABORT SESSION
Parcels
Because of the unpredictable execution time of ABORT SESSION, the Teradata Database
system handles ABORT SESSION as if it were a two-statement request, with each statement
generating a response.
The two-statement response contains the following sequence of parcel types.
Parcel
Sequence
Parcel
Flavor
Length (Bytes)
Comments/Key Parcel Body Fields
Success
8
18 to 273
StatementNo =1
ActivityCount = Number of sessions identified by
the ABORT SESSION request
ActivityType = 86 (PCLABTSESS)
DataInfo
71
6 to 64100
Optional; this parcel is present if request was
IndicData parcel.
Record
10
• 5 to 64100
(record
mode)
• 6 to 64100
(indicator
mode)
Data or IndicData list of sessions. This parcel is
present only if you specified list.
EndStatement
11
6
StatementNo = 2-byte integer.
Success
8
18 to 273
StatementNo = 2
ActivityCount = 0 (Number of sessions identified
by the ABORT SESSION request)
ActivityType = 86 (PCLABTSESS)
DataInfo
71
6 to 64100
Optional; this parcel is present if request was
IndicData parcel.
EndStatement
11
6
StatementNo = 2-byte integer.
EndRequest
12
4
None.
The only difference between the parcels returned with the list option set to y or Y, and those
returned with the list option set to n, N, blank, or NULL, is that one or more Record parcels
are added when you specify the former.
In the first response, the Teradata Database indicates that the request was accepted and is
being executed. It also lists the affected sessions and their status if you specify y or Y for list.
Statement Type: 1
The Record parcel in the first statement of the response returns the list of sessions in
increasing order of HostId. The following table shows the values returned from the first
statement.
56
Application Programming Reference
Chapter 4: System PMPC APIs
ABORT SESSION
Field Name
Data Type
Description
HostId
SMALLINT
Logical host ID associated with a PE or session. For a PE,
the Host ID identifies one of the hosts or LANs associated
with the described PE. For a session, the combination of a
host ID and a session number uniquely identifies a user
session on the system.
Note: This value is NULL for AMPs. A value of zero
represents the Supervisor window.
UserName
VARCHAR (30),
NOT NULL
User name of the session. This is the name specified when
the user is created; it is used to log on to a session. Within
Teradata Database, user name is almost equivalent to
database name.
SessionNo
INTEGER,
NOT NULL
Number of the current session. Together with a given host
ID, a session number uniquely identifies a session on the
Teradata Database system. This value is assigned by the
host (or client) at logon time.
AbortStatus
VARCHAR (1)
Information on the status of the associated session:
• I = In-Doubt
• A = Aborting a transaction
• C = Committing a transaction
• E = Executing an ABORT SESSION request
• S = Switching
• NULL = In some state other than the above
For an ABORT without LOGOFF, any status except NULL
indicates the reason the request could not impact the
associated session.
For an ABORT with LOGOFF, an I, E, or S status value
indicates that the associated session cannot be aborted or
logged off.
If you do not specify logging off sessions, the Success parcel produced for the first statement,
when applicable, includes a warning that identified sessions are in the process of committing
or rolling back their transactions. An ABORT with logoff completes normally and does not
produce any warnings.
Statement Type: 2
In the second response, the Teradata Database indicates that the request is complete. The
completion response is sent only after all impacted sessions have been aborted and, if
requested, logged off.
Sample Input
The following example illustrates how the parcels for an ABORT SESSION request built by
CLIv2 look when sent to the Teradata Database server using a host_id of 52, session_no of 2521,
Application Programming Reference
57
Chapter 4: System PMPC APIs
ABORT SESSION
user_name of user_01, list of Y, logoff of Y, and override of N. In this example, the size of the
response buffer is set at the maximum (64,000 bytes), although you can set it to any size.
However, a minimum response size is 32,000 bytes.
Flavor
Length
Body
Num
Name
Bytes
Field
Value
0001
Req
17
Request
ABORT SESSION
0003
Data
47
MonVerID
2
HostId
348
SessionNo
1000
UserName
user_01
ListOption
Y
Logoff
Y
Override
N
BufferSize
64000
0004
Resp
6
Sample Output
With a host_id of 52, session_no of 2521, user_name of DBC, list of Y, and logoff of Y, this
request might return the following values in character text format. Your application program
may return the values in a different format or display.
Success parcel:
StatementNo: 1
ActivityCount: 1
ActivityType: 86
FieldCount: 4
DataInfo iparcel:
FieldCount: 4
Record parcel.
Parcel flavor:
10
Parcel body length:
38
HostId = 52, UserName = "DBC", SessionNo = 2521,
AbortStatus = ' '.
EndStatement.
Success parcel:
StatementNo: 2
ActivityCount: 0
ActivityType: 86
FieldCount: 0
DataInfo parcel:
FieldCount: 0
EndStatement.
EndRequest.
Relationship Between ABORT SESSION and MONITOR SESSION
When sessions are being aborted or sessions are being blocked by the sessions being aborted,
data returned from subsequent MONITOR SESSION queries may be affected. After the abort
operation starts, you can immediately notice the changes from aborting sessions. However,
58
Application Programming Reference
Chapter 4: System PMPC APIs
ABORT SESSION
you will not notice the changes resulting from sessions that were blocked by aborting sessions
in MONITOR SESSION responses until the abort operation is complete.
Aborted Sessions
For aborted sessions, expect the following types of changes in the response returned from a
subsequent MONITOR SESSION query:
•
PEState changes to PARSING. AMPState changes to ABORTING.
•
AMPCPUSec is updated due to its continued tracking of the CPU time used during the
transaction rollback process. Resources consumed during a transaction rollback are
charged to the user the same way as any other form of resource usage.
•
AMPIO is updated due to its tracking of logical I/O necessary during the transaction
rollback process.
•
Request_AMPSpool decreases if there are spool files in use by the aborted request, because
those spool files are discarded.
•
After the abort operation has completed and if the aborted sessions are not logged off, the
sessions become IDLE (PEState) while they wait for subsequent requests.
If the aborted sessions are logged off, they are no longer tracked by subsequent MONITOR
SESSION requests.
Blocked Sessions
For sessions blocked or slowed down by aborted sessions, expect the following types of
changes in the response returned from a subsequent MONITOR SESSION query:
•
The following response fields related to the aborted sessions are removed (that is, they are
reported as NULLS because the blocking session is gone):
•
Blk_x_HostId
•
Blk_x_SessNo
•
Blk_x_UserID
•
Blk_x_LMode
•
Blk_x_OType
•
Blk_x_ObjDBId
•
Blk_x_ObjTId
•
Blk_x_Status
For example, the following describes the information that can be inferred from the
returned data:
•
•
Within a MONITOR SESSION, response fields show Session 1 blocked by Sessions 2
and 3.
•
After an ABORT SESSION, Session 2 is removed.
•
Within a subsequent MONITOR SESSION, response fields show Session 1 blocked by
Session 3.
The MoreBlockers field may return data indicating there are no additional lock conflicts.
Application Programming Reference
59
Chapter 4: System PMPC APIs
ABORT SESSION
Because removing an aborted session allows another blocking session to be reported, there
may be no remaining locks to report.
•
If the aborted sessions are no longer blocking other sessions, the AMPState of those other
sessions changes from BLOCKED to ACTIVE.
•
For sessions that have changed to ACTIVE, or that are only slowed down by the aborted
sessions, all resource usage fields may show a more rapid increase in resource usage. For
example, the AMPCPUSec, AMPIO, and Request_AMPSpool fields may change more
rapidly due to reduction in competition for those resources.
Before You Execute the ABORT SESSION Request
Execute the MONITOR SESSION before you execute the ABORT SESSION request to get a
list of current sessions. Therefore, you can evaluate which sessions to abort. You can use the
host ID, session number, and user name returned by the MONITOR SESSION request as
input data to an ABORT SESSION request.
Some of the values returned by MONITOR SESSION can help you determine which session is
not actively processing or has a long-running transaction. For example, look at PEState for the
session in question. If PEState is not PARSING-WAIT, PARSING, DISPATCHING,
BLOCKED, or ACTIVE, that session may be a good candidate for an abort. As another
example, look at the ratio of AMPCPUSec to XactCount to determine which transaction has
been running for a long time. If this ratio is high, this session has a long-running transaction.
It is also useful to run the QUERY SESSION request to determine how long a particular
transaction has been running. Execute the MONITOR SESSION and QUERY SESSION
request to pinpoint the source of the problem. By running these two requests, you may not
need to abort as many transactions as originally planned. For more information on QUERY
SESSION, see Utilities.
Relationship Between ABORT SESSION and MONITOR PHYSICAL
RESOURCE or MONITOR VIRTUAL RESOURCE
If you executed an ABORT SESSION request, data returned in a MONITOR PHYSICAL
RESOURCE or MONITOR VIRTUAL RESOURCE request may be altered. Whether you
notice the change in data depends on the scope of the ABORT SESSION request. For example,
if you execute an ABORT SESSION and log off all of the sessions associated with a specific
host (or client), the PEs associated with that client will report a large decrease in resource
consumption. However, if the ABORT SESSION request only aborts one transaction from one
session, you may not notice a change in AMP or PE resource use.
60
Application Programming Reference
Chapter 4: System PMPC APIs
IDENTIFY
IDENTIFY
Purpose
Returns information on the locks blocking a session:
•
Name of the user associated with a session
•
User name of an object
•
Database name of an object
•
Name of a table
Input Data
Element
Data Type
Description
IndByte
BYTE
Indicator bits that specify which fields to treat as NULL if you are
using indicator mode.
Each bit in the byte corresponds to one field in the input data.
If data is supplied for that field, then set the bit to zero.
If the data for that field is NULL (that is, there is no data supplied
for that field), then set the bit to 1.
Note: The IndByte field is only required if the PM/API request is
submitted in indicator mode.
mon_ver_id
SMALLINT,
NOT NULL
MONITOR software version ID. This can be version 2 or later.
host_id
SMALLINT
Logical ID of a host (or client). host_id cannot exceed 1023. A
host_id of zero identifies the system console ID of the host. A
combination of host_id and session_no identifies a user causing a
block.
session_no
INTEGER
Session number. A combination of host_id and session_no
identifies a user causing a block.
For a general explanation of monitor version choices, see
“MONITOR VERSION” on page 136.
To identify the user involved in a lock conflict, include the
Blk_x_HostId and Blk_x_SessNo returned in a MONITOR
SESSION response as input in the USING Data String for the
IDENTIFY SESSION request.
database_id
INTEGER
ID of the database for this session.
To identify the database name of the object involved in a block,
include the Blk_x_ObjDBId returned in a MONITOR SESSION
response as input in the USING Data String for the IDENTIFY
DATABASE request.
Application Programming Reference
61
Chapter 4: System PMPC APIs
IDENTIFY
Element
Data Type
Description
user_id
INTEGER
ID of the user for this session.
To identify the user involved in a lock conflict, include the
Blk_x_UserID field returned in a MONITOR SESSION response
as input in the USING Data String for the IDENTIFY USER
request.
table_id
INTEGER
Unique ID of a table.
To identify the table name of the object involved in a block,
include the Blk_x_ObjTId returned in a MONITOR SESSION
response as input in the USING Data String for the IDENTIFY
TABLE request.
Note: The database name and user name are assigned an
associated identifier when they are created. The IDENTIFY
DATABASE or IDENTIFY USER request processes database and
user names in the same manner because the database name and
user name are almost equivalent.
Note: Because the Blk_x_HostId, Blk_x_SessNo, and Blk_x_UserID fields returned by a
MONITOR SESSION request may either be NULL or identify an internal session, the data
returned by a MONITOR SESSION request that you use as input for the IDENTIFY request
can result in error responses from IDENTIFY. If you use an internal session identifier as input
to the IDENTIFY SESSION request, it will return an error message. The same error message is
returned if you submit the IDENTIFY SESSION request for the DBQL/Teradata dynamic
workload management software artificial internal session.
If you use an NULL UserID as input to the IDENTIFY DATABASE or IDENTIFY USER
request, they system will return an error message.
Monitor Privileges
To use this request, you must have the MONSESSION privilege as part of your default role or
this privilege must be granted directly to you.
For more information on roles and privileges, see Database Administration and Security
Administration.
Usage Notes
The following table describes the different IDENTIFY options.
62
Option
Description
IDENTIFY DATABASE
Identify a locked database.
IDENTIFY SESSION
Identify a user (by session) who is causing a block. You can use
IDENTIFY SESSION with a combination of host_id and session_no,
or you can use IDENTIFY USER.
Application Programming Reference
Chapter 4: System PMPC APIs
IDENTIFY
Option
Description
IDENTIFY TABLE
Identify a locked table.
IDENTIFY USER
Identify a user who is causing a block. You can use IDENTIFY
SESSION, or you can use IDENTIFY USER user_id.
The following table lists the system table for each option. You can use Data Dictionary views
to examine the information in each system table (see Data Dictionary).
System Table Name
IDENTIFY Option
DBC.SessionTbl
IDENTIFY SESSION
DBC.DBase
IDENTIFY DATABASE
IDENTIFY USER
DBC.TVM
IDENTIFY TABLE
Parcels
Regardless of the form of the IDENTIFY request you execute, the response contains the
following sequence of parcel types.
Parcel
Sequence
Parcel
Flavor
Length (Bytes)
Comments/Key Parcel Body Fields
Success
8
18 to 273
StatementNo = 2
ActivityCount = 1
ActivityType = 85 (PCLIDENTIFY)
DataInfo
71
6 to 64100
Optional; this parcel is present if request was
IndicData parcel.
Record
10
• 5 to 64100
(record
mode)
• 6 to 64100
(indicator
mode)
Depending on request (Data or IndicData), data
is in record or indicator mode. This record
contains the user name with the specified user
ID or database ID, user name logged on as the
specified session, or table name with the
specified table ID.
EndStatement
11
6
StatementNo = 2-byte integer
EndRequest
12
4
None
The Record parcel returns the following field:
Application Programming Reference
63
Chapter 4: System PMPC APIs
IDENTIFY
Field
Data Type
Description
Name
VARCHAR (30),
NOT NULL
Name of the object (for example, database, user, or table)
whose identifier was supplied by the IDENTIFY request.
Sample Input
The following example shows how the Request parcels for an IDENTIFY SESSION request,
built by CLIv2, appear when sent to the Teradata Database server using a host_id of 348 and a
session_no of 1000.
Note: In this example, the size of the response buffer is set at the maximum (64,000 bytes),
although you can set it to any size. However, a minimum response size is 32,000 bytes.
Flavor
Length
Body
Num
Name
Bytes
Field
Value
0001
Req
20
Request
IDENTIFY SESSION
0003
Data
12
MonVerID
2
HostId
348
SessionNo
1000
BufferSize
64000
0004
Resp
6
The following example shows how the Request parcels for an IDENTIFY USER request, built
by CLIv2, look when they are sent to the Teradata Database server using a user_id of 725.
Note: In this example, the size of the response buffer is set at the maximum (64,000 bytes),
although you can set it to any size. However, a minimum response size is 32,000 bytes.
Flavor
Length
Body
Num
Name
Bytes
Field
Value
0001
Req
21
Request
IDENTIFY DATABASE or
IDENTIFY USER
0003
Data
10
MonVerID
2
UserID
725
BufferSize
64000
0004
Resp
6
The next example shows how the Request parcels for an IDENTIFY TABLE request, built by
CLIv2, look when they are sent to the Teradata Database server using a table_id of 183351.
64
Application Programming Reference
Chapter 4: System PMPC APIs
IDENTIFY
Note: In this example, the size of the response buffer is set at the maximum (64,000 bytes),
although you can set it to any size. However, a minimum response size is 32,000 bytes.
Flavor
Length
Body
Num
Name
Bytes
Field
Value
0001
Req
18
Request
IDENTIFY TABLE
0003
Data
10
MonVerID
2
TableId
183351
BufferSize
64000
0004
Resp
6
Sample Output
With a host_id of 52 and a session_no of 31467, the IDENTIFY SESSION request might return
the following values. These example values are returned in text character format. Your
application program may return the values in a different format or display.
Success parcel:
StatementNo: 1
ActivityType: 85
DataInfo parcel:
FieldCount: 1
Record parcel.
Parcel flavor:
Name = "DBC
EndStatement.
EndRequest.
ActivityCount: 1
FieldCount: 1
10
Parcel body length:
".
31
With a database_id of 1012, the IDENTIFY DATABASE request might return the following
values. These example values are returned in text character format. Your application program
may return the values in a different format or display.
Success parcel:
StatementNo: 1
ActivityType: 85
DataInfo parcel:
FieldCount: 1
Record parcel.
Parcel flavor:
Name = "weekly
EndStatement.
EndRequest.
ActivityCount: 1
FieldCount: 1
10
Parcel body length:
".
31
With a user_id of 1012, the IDENTIFY USER request might return the following values. These
example values are returned in text character format. Your application program may return
the values in a different format or display.
Success parcel:
StatementNo: 1
ActivityType: 85
DataInfo parcel:
FieldCount: 1
Application Programming Reference
ActivityCount: 1
FieldCount: 1
65
Chapter 4: System PMPC APIs
IDENTIFY
Record parcel.
Parcel flavor:
Name = "weekly
EndStatement.
EndRequest.
10
Parcel body length:
".
31
With a table_id of 63, the IDENTIFY TABLE request might return the following values. These
example values are returned in text character format. Your application program may return
the values in a different format or display.
Success parcel:
StatementNo: 1
ActivityType: 85
DataInfo parcel:
FieldCount: 1
Record parcel.
Parcel flavor:
Name = "EventLog
EndStatement.
EndRequest.
ActivityCount: 1
FieldCount: 1
10
Parcel body length:
".
31
Relationship Between IDENTIFY and MONITOR SESSION
PM/API can report on locks placed by any user or object with the MONITOR SESSION and
IDENTIFY requests. The MONITOR SESSION request helps you identify the types of locks
blocking a session.
The MONITOR SESSION request:
•
Monitors the currently executing processes and reports blocks preventing sessions from
doing useful work, for both application or utility locks causing the block.
•
Tells you not only which session is blocked and on what type of object but also who is
holding the lock. You can trace a blocked session back to the object locked and display the
owner of the lock if your job is hung or is running very slowly and you suspect there is a
lock conflict involved.
•
On a query, reports up to three lock conflicts per session, with a flag (MoreBlockers) to
indicate if there are more lock conflicts involved but not reported. The types of lock
information returned for each session include:
•
User ID or user of host utility job causing a block
•
Type of object (for example, database, table, or row hash) causing a lock
•
Mode or severity of lock
•
Database identifier of object being locked
•
Table identifier of object being locked
By looking at the logical host ID of a session causing the block in combination with the session
number of the session causing a block, you can uniquely identify the session that is causing a
block.
Although you have the above lock information, you must use the IDENTIFY request to
further identify the locks as either a user name, database name, or table name. Use the
Blk_ data values (or fields) returned in the MONITOR SESSION operation as input for an
IDENTIFY request.
66
Application Programming Reference
Chapter 4: System PMPC APIs
IDENTIFY
MONITOR SESSION, with IDENTIFY, is a more powerful diagnostic tool than the Show
Locks utility accessed through Database Window (DBW), which displays information about
only client utility locks on an object and does not report who the lock is blocking.
Example
The following example output shows that SessionNo 1001 is blocked by SessionNo 1000 by a
WRITE lock that has been granted on a table object type. Records are sorted in HostId and
then SessionNo order.
First Record:
HostId = 719
.
.
SessionNo = 1000
.
.
.
Second Record:
HostId = 719
.
.
SessionNo = 1001
.
.
Blk-1-HostId = 719
Blk-1-SessNo = 1000
Blk-1-UserID = 10
Blk-1-LMode = 'W'
Blk-1-OType = 'T'
Blk-1-ObjDBId = 12
Blk-1-ObjTId = 1097
Blk-1-Status = 'G'
Blk-2-HostId = NULL
.
.
.
Note: When the Blk_2_ HostId, Blk_2_SessNo, and Blk_2_UserID values are returned as
NULLs, this usually means that the blocking job is a HUT job that has logged off without
releasing its lock.
Because the data returned here does not tell you which user is causing the block or which table
is locked, you must next use the IDENTIFY request with the output from your MONITOR
SESSION to return that information.
To identify the user causing the lock, execute the IDENTIFY request with:
HostId = 719
SessionNo = 1000
Or:
UserID = 10
To identify a locked database, execute the IDENTIFY request with:
Application Programming Reference
67
Chapter 4: System PMPC APIs
IDENTIFY
ObjDBId = 12
To identify a locked table, execute the IDENTIFY request with:
ObjTId = 1097
68
Application Programming Reference
Chapter 4: System PMPC APIs
MONITOR AWT RESOURCE
MONITOR AWT RESOURCE
Purpose
Collects statistics on AMPs based on the in-use AMP Worker Tasks (AWTs).
Input Data
Element
Data Type
Description
IndByte
BYTE
Indicator bits that specify which fields to treat as NULL if
you are using indicator mode.
Each bit in the byte corresponds to one field in the input
data.
If data is supplied for that field, then set the bit to zero.
If the data for that field is NULL (that is, there is no data
supplied for that field), then set the bit to 1.
Note: The IndByte field is only required if the PM/API
request is submitted in indicator mode.
mon_ver_id
SMALLIN,
NOT NULL
MONITOR software version ID. This can be version 2 or
later.
For a general explanation of monitor version choices, see
“MONITOR VERSION” on page 136.
Threshold 1
SMALLINT,
NOT NULL
Minimum value for in-use AWTs to qualify an AMP for
inclusion into this interval.
Threshold 2
SMALLINT
Start value for in-use AWTs to qualify an AMP for inclusion
into this interval.
Threshold 3
SMALLINT
Start value for in-use AWTs to qualify an AMP for inclusion
into this interval.
Threshold 4
SMALLINT
Start value for in-use AWTs to qualify an AMP for inclusion
into this interval.
Summary
SMALLINT,
NOT NULL
0 = Returns no record parcels in Statement Type 2.
Application Programming Reference
1 = Returns the record parcels in Statement Type 2, which
are the data fields returned in Groups I through V only.
69
Chapter 4: System PMPC APIs
MONITOR AWT RESOURCE
Element
Data Type
Description
Detail
SMALLINT,
NOT NULL
0 = Returns no Detail information.
1 = Returns AMP worker task usage information by each
AMP.
If Detail is enabled, a third statement is returned containing
AMP worker task usage information by each AMP. If Detail
is not enabled, a statement is returned with no record
parcels. For information on the record parcels returned, see
“Statement Type: 3” on page 74.
Note: You can define up to four thresholds for categorizing AMPs.
Monitor Privileges
To use this request, you must have the MONRESOURCE privilege as part of your default role
or this privilege must be granted directly to you.
For more information on roles and privileges, see Database Administration and Security
Administration.
Usage Notes
This interface provides a snapshot of AMP utilization based on the number of AWTs in use
within the MSGWORKNEW and MSGWORKONE message work types. These two message
work types are a barometer for AMP activity/health. The MONITOR AWT RESOURCE
request allows the specification of four thresholds which are used to categorize AMPs. AMPs
are counted into categories defined by these thresholds and based on the AWT usage of the
AMP.
This request also indicates the number of AMPs currently in some form of Flow Control. Flow
Control can be defined at a node level and, therefore, may not have a system-wide consistent
definition. This indication is applicable only to those messages to which Flow Control is
applicable.
MONITOR AWT RESOURCE provides information on the AMPs having the highest and
lowest in-use counts within the system. When duplicate in-use counts exist, the AMP
information returned is for the AMPs with the largest VProc ID.
Thresholds must be defined in ascending order and cannot contain gaps. If a gap is detected,
an error message is returned.
Thresholds that are not used must be set to -1 (or NOT NULL). The minimum valid threshold
value is zero.
Parcels
The MONITOR AWT RESOURCE request is treated internally as a one statement request that
generates two responses. The statement response returned from Teradata Database contains
the following sequence of parcel types.
70
Application Programming Reference
Chapter 4: System PMPC APIs
MONITOR AWT RESOURCE
Parcel
Sequence
Parcel
Flavor
Length
(Bytes)
Comments and Key Parcel Body Fields
Success
8
18 to 273
StatementNo = 1
ActivityCount = 1
ActivityType = 175 (PCLMONAWTRESSTMT)
DataInfo
71
6 to 64100
Optional: This parcel is present if request was
IndicData parcel.
Record
10
• 5 to 64100
(record
mode)
• 6 to 64100
(indicator
mode)
Depending on the request (Data or IndicData) data is
returned in record or indicator mode. This record
contains information in StatementNo-1. For an
example of this record, see “Statement Type: 1” on
page 72.
EndStatement
11
6
StatementNo = 2-byte integer=1
Success
8
18 to 273
StatementNo = 2
ActivityCount = 1
ActivityType = 175 (PCLMONAWTRESSTMT)
DataInfo
71
6 to 64100
Optional: This parcel is present if request was
IndicData parcel.
Record
10
• 5 to
64100(rec
ord mode)
• 6 to 64100
(indicator
mode)
Depending on the request (Data or IndicData) data is
returned in record or indicator mode. This record
contains information in StatementNo-2. For an
example of this record, see
“Statement Type: 2” on page 72.
EndStatement
11
6
StatementNo = 2-byte integer=1
EndRequest
12
4
None
Success
8
18 to 273
StatementNo = 3
ActivityCount = 1
ActivityType = 175 (PCLMONAWTRESSTMT)
DataInfo
71
6 to 64100
Optional: This parcel is present if request was
IndicData parcel.
Record
10
• 5 to
64100(rec
ord mode)
• 6 to 64100
(indicator
mode)
Depending on the request (Data or IndicData) data is
returned in record or indicator mode. This record
contains information in StatementNo-3. For an
example of this record, see
“Statement Type: 3” on page 74.
EndStatement
11
6
StatementNo = 3-byte integer=1
EndRequest
12
4
None
Application Programming Reference
71
Chapter 4: System PMPC APIs
MONITOR AWT RESOURCE
Response
The MONITOR AWT RESOURCE request returns the following information: the number of
AWTs in use within the MSGWORKNEW and MSGWORKONE message work types; the
number of AMPs currently in some form of Flow Control; and the number of AMPs having
the highest and lowest in-use counts within the system.
The output returns three statement types:
•
The first statement type provides information about the collection rate.
•
The second statement type provides information about AMPs and the AMPs AWT
distribution across the defined thresholds.
•
The third statement type provides AMP worker task usage information by each AMP.
Statement Type: 1
The first statement type is a Record parcel format containing:
Field Name
Data Type
Description
SampleSec
INTEGER,
NOT NULL
Duration of the collection period, in seconds. This field
contains the Monitor resource collection rate (ResMonitor).
CollectionDate
DATE,
NOT NULL
Date the Monitor AWT cache was last refreshed.
CollectionTime
FLOAT,
NOT NULL
Time the Monitor AWT cache was last refreshed
To avoid excessive AWT data collection, Monitor AWT Resource checks if the data in the
buffer is still valid in relation to the value set for SampleSec (ResMonitor rate) and only collects
new data if it has expired.
Statement Type: 2
The second statement type is a Record parcel format containing information about AMPs and
the AMPs AWT distribution across the defined thresholds.
72
Field Name
Data Type
Description
Interval 1 Count
INTEGER
Number of AMPs in the system whose in-use AWT
counts fall at, or above, the Threshold 1 value and do not
qualify for the higher thresholds.
Interval 2 Count
INTEGER
Number of AMPs in the system whose in-use AWT
counts fall at, or above, the Threshold 2 value and do not
qualify for the higher thresholds.
Interval 3 Count
INTEGER
Number of AMPs in the system whose in-use AWT
counts fall at, or above, the Threshold 3 value and do not
qualify for the higher thresholds.
Application Programming Reference
Chapter 4: System PMPC APIs
MONITOR AWT RESOURCE
Field Name
Data Type
Description
Interval 4 Count
INTEGER
Number of AMPs in the system whose in-use AWT
counts fall at, or above, the Threshold 4 value and do not
qualify for the higher thresholds.
Flow Control
INTEGER
Number of AMPs currently in some form of Flow
Control.
High AMP 1
VprocId
INTEGER
Vproc ID of the AMP with the highest in-use count in the
system. A value of -1 (or NULL) indicates this field is not
defined.
High AMP 1
In-Use Count
INTEGER
In-use count associated with the AMP 1 Vproc ID. This is
only applicable if AMP 1 is defined.
High AMP 2
VprocId
INTEGER
Vproc ID of the AMP with the next highest in-use count
in the system. A value of -1 (or NULL) indicates this field
is not defined.
High AMP 2
In-Use Count
INTEGER
In-use count associated with the AMP 2 Vproc ID. This is
only applicable if AMP 2 is defined.
High AMP 3
VprocId
INTEGER
Vproc ID of the AMP with the next highest in-use count
in the system. A value of -1 (or NULL) indicates this field
is not defined.
High AMP 3
In-Use Count
INTEGER
In-use count associated with the AMP 3 Vproc ID. This is
only applicable if AMP 3 is defined.
High AMP 4
VprocId
INTEGER
Vproc ID of the AMP with the next highest in-use count
in the system. A value of -1 (or NULL) indicates this field
is not defined.
High AMP 4
In-Use Count
INTEGER
In-use count associated with the AMP 4 Vproc ID. This is
only applicable if AMP 4 is defined.
High AMP 5
VprocId
INTEGER
Vproc ID of the AMP with the next highest in-use count
in the system. A value of -1 (or NULL) indicates this field
is not defined.
High AMP 5
In-Use Count
INTEGER
In-use count associated with the AMP 5 Vproc ID. This is
only applicable if AMP 5 is defined.
Low AMP 1 VprocId
INTEGER
Vproc ID of the AMP with the lowest in-use count in the
system. A value of -1 (or NULL) indicates this field is not
defined.
Low AMP 1
In-Use Count
INTEGER
In-use count associated with the AMP 1 Vproc ID. This is
only applicable if AMP 1 is defined.
Low AMP 2 VprocId
INTEGER
Vproc ID of the AMP with the lowest in-use count in the
system. A value of -1 (or NULL) indicates this field is not
defined.
Low AMP 2
In-Use Count
INTEGER
In-use count associated with the AMP 2 Vproc ID. This is
only applicable if AMP 2 is defined.
Application Programming Reference
73
Chapter 4: System PMPC APIs
MONITOR AWT RESOURCE
Field Name
Data Type
Description
Low AMP 3 VprocId
INTEGER
Vproc ID of the AMP with the lowest in-use count in the
system. A value of -1 (or NULL) indicates this field is not
defined.
Low AMP 3
In-Use Count
INTEGER
In-use count associated with the AMP 3 Vproc ID. This is
only applicable if AMP 3 is defined.
Low AMP 4 VprocId
INTEGER
Vproc ID of the AMP with the lowest in-use count in the
system. A value of -1 (or NULL) indicates this field is not
defined.
Low AMP 4
In-Use Count
INTEGER
In-use count associated with the AMP 4 Vproc ID. This is
only applicable if AMP 4 is defined.
Low AMP 5 VprocId
INTEGER
Vproc ID of the AMP with the lowest in-use count in the
system. A value of -1 (or NULL) indicates this field is not
defined.
Low AMP 5
In-Use Count
INTEGER
In-use count associated with the AMP 5 Vproc ID. This is
only applicable if AMP 5 is defined.
Flow Control 1
VprocId,
INTEGER
Vproc ID of the AMP in flow control. A value of -1 (or
NULL) indicates this field is not defined.
Flow Control 2
VprocId,
Flow Control 3
VprocId,
Flow Control 4
VprocId,
Flow Control 5
VprocId
Statement Type: 3
The third statement type is a Record parcel format containing AMP worker task usage
information by each AMP.
74
Field Name
Data Type
Description
VprocNo
SMALLINT,
NOT NULL
AMP vproc number.
AvailableAWTs
SMALLINT,
NOT NULL
Number of available AMP worker tasks in each AMP.
InUseAWTs
SMALLINT,
NOT NULL
Number of active AMP worker tasks in each AMP.
MsgCount
INTEGER,
NOT NULL
Number of messages currently queued for delivery to each
AMP.
Application Programming Reference
Chapter 4: System PMPC APIs
MONITOR AWT RESOURCE
Field Name
Data Type
Description
DQMsgCount
INTEGER,
NOT NULL
Number of messages processed by each AMP.
Sample Input
The following example shows how the parcels for a MONITOR AWT RESOURCE request,
built by CLIv2, appear when sent to the Teradata Database server.
Note: In this example, the size of the response buffer in the example is set at the maximum
(64,000 bytes), although you can set it to any size. However, the minimum size is 32,000 bytes.
Flavor
Length
Body
Num
Name
Bytes
Field
Value
0001
Req
16
Request
MONITOR AWT RESOURCE
0003
Data
57
MonVerId
6
Threshold 1
10
Threshold 2
12
Threshold 3
14
Threshold 4
15
Summary
1
Detail
0
BufferSize
64000
0004
Resp
6
Sample Output
The MONITOR AWT RESOURCE request returns values approximately as shown below
when Teradata ASM Workloads rule is enabled and the following input data is specified:
Threshold 1
Threshold 2
Threshold 3
Threshold 4
Summary
Detail
=
=
=
=
=
=
10
12
14
15
1
1
For information on Teradata ASM rules, see Teradata Viewpoint User Guide.
The MONITOR AWT RESOURCE request commonly returns values in text character format.
Your application program may return the values in a different format or display.
Note: You can rename the SampleSec field in your application. In the output below, the
SampleRate value is the SampleSec value.
Pay attention to SampleRate when interpreting the results of this request.
SampleRate: 30
Application Programming Reference
75
Chapter 4: System PMPC APIs
MONITOR AWT RESOURCE
Collection Date/Time:
06/15/2011 18:32:44.00
SUCCESS parcel:
StatementNo=2,
ActivityCount=1,
ActivityType=175, FieldCount=30
Intervals:
1
4
2
0
3
0
4
0
Flow Control = 0
*** HIGH AMP ***
VprocId:
InUseCount:
1
3
1
2
2
1
3
1
1
4
0
1
5
-1
0
1
3
1
2
2
1
3
1
1
4
0
1
5
-1
0
2
-1
3
-1
4
-1
5
-1
*** LOW AMP ***
VprocId:
InUseCount:
*** FLOW CONTROL INFO ***
1
VprocId
-1
SUCCESS parcel:
StatementNo=3,
ActivityCount=4,
ActivityType=175, FieldCount=5
VProcNo
------0
1
2
3
76
AvailableAWTs
------------49
49
49
49
InUseAWTs
--------2
1
1
1
MsgCount
-------0
0
0
0
DQMsgCount
---------111135
124561
156017
122913
Application Programming Reference
Chapter 4: System PMPC APIs
MONITOR PHYSICAL CONFIG
MONITOR PHYSICAL CONFIG
Purpose
Collects overall information on node availability. Node status information is returned for all
nodes in the system.
Input Data
Element
Data
Type
IndByte
BYTE
Description
Indicator bits that specify which fields to treat as NULL if using
indicator mode.
Each bit in the byte corresponds to one field in the input data.
If data is supplied for that field, then set the bit to zero.
If the data for that field is NULL (that is, there is no data
supplied for that field), then set the bit to 1.
Note: The IndByte field is only required if the PM/API request
is submitted in indicator mode.
mon_ver_id
SMALLINT,
NOT NULL
MONITOR software version ID. This can be version 2 or later.
For a general explanation of monitor version choices, see
“MONITOR VERSION” on page 136.
Monitor Privileges
To use this request, you must have any of the following monitor privileges as part of your
default role or any of these privileges must be granted directly to you:
•
ABORTSESSION
•
MONRESOURCE
•
MONSESSION
•
SETRESRATE
•
SETSESSRATE
For more information on roles and privileges, see Database Administration and Security
Administration.
Usage Notes
MONITOR PHYSICAL CONFIG is most useful when used with the MONITOR PHYSICAL
SUMMARY request for doing a quick overall system health check. For more information, see
Application Programming Reference
77
Chapter 4: System PMPC APIs
MONITOR PHYSICAL CONFIG
“Relationship Between MONITOR PHYSICAL CONFIG and MONITOR PHYSICAL
SUMMARY” on page 81.
You can use the MONITOR PHYSICAL CONFIG request instead of dumping the
DBC.SW_Event_Log table (accessible from the DBC.Software_Event_LogV view) to check for
a physical problem with the system.
Parcels
The MONITOR PHYSICAL CONFIG request is treated internally as a two statement request,
with each statement generating a response. Teradata Database returns the two statement
response containing the following sequence of parcels.
Parcel
Sequence
Parcel
Flavor
Length
(Bytes)
Comments/Key Parcel Body Fields
Success
8
18 to 273
StatementNo = 1
ActivityCount = 1
ActivityType = 92 (PCLMONPCONFIG)
DataInfo
71
6 to 64100
Optional; this parcel is present if request was
IndicData parcel.
Record
10
• 5 to 64100
(record
mode)
• 6 to
64100(indi
cator
mode)
Depending on request (Data or IndicData), data is
in record or indicator mode. This record contains
the BYNET status data and the type of system
running the Teradata Database software.
EndStatement
11
6
StatementNo = 2-byte integer
Success
8
18 to 273
StatementNo = 2
ActivityCount = Number of nodes
ActivityType = 92 (PCLMONPCONFIG)
78
DataInfo
71
6 to 64100
Optional; this parcel is present if request was
IndicData parcel.
Record
10
• 5 to 64100
(record
mode)
• 6 to 64100
(indicator
mode)
Depending on request (Data or IndicData), data is
in record or indicator mode. Multiple record parcels
are returned that consist of a record for each node in
the system. This record contains node-specific
information; one record per node.
EndStatement
11
6
StatementNo = 2-byte integer
EndRequest
12
4
None
Application Programming Reference
Chapter 4: System PMPC APIs
MONITOR PHYSICAL CONFIG
For descriptions of the flavor field and length field, see Teradata Call-Level Interface Version 2
Reference for Mainframe-Attached Systems or Teradata Call-Level Interface Version 2 Reference
for Network-Attached Systems. Within the parcel body fields, the order of items and their data
types and lengths are determined by the USING Phrase.
Statement Type: 1
The Record parcel in the first statement of the MONITOR PHYSICAL CONFIG response
returns two-column BYNET status values that are generated once for the whole system. The
following table shows these response values.
Column
Field Name
Data Type
Description
1
NetAUp
VARCHAR (1),
NOT NULL
Status of the BYNETs (if there are more than two,
the first two) on a system-wide basis:
• U = All node BYNETs are up/online.
• D = One or more node BYNETs is down/offline.
• “” = A temporary condition where the BYNET
data is not available.
2
NetBUp
VARCHAR (1),
NOT NULL
Status of the BYNETs (if there are more than two,
the first two) on a system-wide basis:
• U = All node BYNETs are up/online.
• D = One or more node BYNETs is down/offline.
• “” = A temporary condition where the BYNET
data is not available.
3
SystemType
VARCHAR (7),
NOT NULL
Type of system running the Teradata Database
software, such as 3400, 3500, 5100, or ‘Other’.
If all the nodes in the system are the same type, this
field returns the type of the system.
If any of the nodes are of a different type, this field
returns ‘Mixed’.
Statement Type: 2
The response to the second statement results in multiple Record parcels that consist of a
record for each node in the system, with six fields in each record. For example, if you have two
nodes, two records are returned with specific information for each processor, in addition to
the one record of BYNET data for the whole system.
Records are sorted based on NodeID. The following table shows the order in which the Record
parcel returns the data.
Application Programming Reference
79
Chapter 4: System PMPC APIs
MONITOR PHYSICAL CONFIG
Field Name
Data Type
Description
ProcId
SMALLINT,
NOT NULL
ID associated with a node. This value is computed as the module
number within a cabinet plus 100 times the cabinet number.
Usually formatted for display as zz9-99. However, this display
format can be changed by the user.
Status
VARCHAR (1),
NOT NULL
Status of the node associated with this record:
• U = Up/online
• D = Down/offline
• S = Standby
A node is up (U) when it is:
• Configured into the system
• Online
• Capable of actively performing tasks associated with normal
Teradata Database activity
Down (D) represents all other potential states.
Standby (S) indicates the node is ready to join the configuration
in place if another node goes down. When the node status is
Standby, the SystemType, NetAUp, and NetBUp fields are not
available and NULL or spaces will be returned.
CPUType
VARCHAR (7),
NOT NULL
Type of central processing unit (CPU) installed in this node, for
example, ‘Pentium’, ‘PentPro’, or ‘Unknown’.
CPUCount
INTEGER,
NOT NULL
Number of CPUs in this node.
SystemType
VARCHAR (7)
Type of system running the Teradata Database software, such as
3400, 3500, 5100, or ‘Other’.
CliqueNo
SMALLINT,
NOT NULL
Clique number of the node.
NetAUp
VARCHAR(1)
Status of the BYNETs (if there are more than two, the first two) on
a system-wide basis:
• U = Node BYNET is up/online.
• D = Node BYNET is down/offline.
• “” = A temporary condition where the BYNET data is not
available.
NetBUp
VARCHAR(1)
Status of the BYNETs (if there are more than two, the first two) on
a system-wide basis:
• U = Node BYNET is up/online.
• D = Node BYNET is down/offline.
• “” = A temporary condition where the BYNET data is not
available.
80
Application Programming Reference
Chapter 4: System PMPC APIs
MONITOR PHYSICAL CONFIG
Sample Input
The following example shows how the parcels for a MONITOR PHYSICAL CONFIG request,
built by CLIv2, look when sent to the Teradata Database server.
Note: In the following example, the size of the response buffer is set at the maximum (64,000
bytes), although you can set it to any size. However, a minimum response size is 32,000 bytes.
Flavor
Length
Body
Num
Name
Bytes
Field
Value
0001
Req
27
Request
MONITOR PHYSICAL CONFIG
0003
Data
6
MonVerID
9
0004
Resp
6
BufferSize
64000
Sample Output
This request might return the following values in character text format. Your application
program may display returned values in a different format.
SUCCESS parcel:
StatementNo=1,
ActivityType=92,
ActivityCount=1,
FieldCount=3
NetAUp: U NetBUp:
SystemType: 5500C
U
PCLSUCCESS parcel:
StatementNo=2,
ActivityCount=1,
ActivityType=92, FieldCount=8
1 node(s) found
ProcId:
33
Status:
SystemType: 5500C
CliqueNo: 0
NetAUp: U NetBUp: U
U
CPUType: Xeon
CPUCount: 1
Relationship Between MONITOR PHYSICAL CONFIG and
MONITOR PHYSICAL SUMMARY
Use the MONITOR PHYSICAL SUMMARY request with the MONITOR PHYSICAL
CONFIG request for an overall system status. These are low overhead requests.
•
Execute the MONITOR PHYSICAL SUMMARY request every 5 or 10 minutes for a lowcost, continuous monitoring of your system.
•
Execute the MONITOR PHYSICAL CONFIG request to get a picture of your system
configuration at defined times, such as at the beginning of a day, various times during the
day, or when the system is down.
Application Programming Reference
81
Chapter 4: System PMPC APIs
MONITOR PHYSICAL CONFIG
Use these requests to spot problems, such as abnormal Central Processing Unit (CPU) load
balancing, and possible sources of system performance bottlenecks. For example, if the High/
LowCPUUse figures are consistently widely separated and do not approximate the AvgCPU
figure, you may need to evaluate whether the system is using available resources efficiently.
How often you check your system depends on the size of your system and the type of
applications your system runs.
Knowledge of the overall system status can help you to determine these three concerns.
Concern
Comments
When to run production
applications, especially large ones
For example, if you have a down node, some Access Module
Processors (AMPs) and Parsing Engines (PEs) may migrate
to other nodes. It may be less costly to recover the node first
and run the job than to run the job without full system
availability.
Why an application runs more slowly
than usual
This situation may be caused by a down node, which causes
the online nodes to run more than the optimal number of
AMPs and PEs. This, in turn, could cause your application
to run more slowly.
Whether all nodes have come back
up after a system restart
Examine the Status value returned in a MONITOR
PHYSICAL CONFIG request to determine whether each
node is up or down.
If the data returned from a MONITOR PHYSICAL SUMMARY query does not give you
enough information (for example, you need BYNET or CPU% busy information), use the
MONITOR PHYSICAL RESOURCE request to obtain more detailed resource usage data.
The data returned by the MONITOR PHYSICAL CONFIG request is an abbreviated form of
the data returned by the MONITOR PHYSICAL RESOURCE request.
Note: The MONITOR PHYSICAL CONFIG and MONITOR PHYSICAL SUMMARY
requests do not return the status of non-Teradata Database nodes. However, the MONITOR
PHYSICAL RESOURCE and MONITOR PHYSICAL SUMMARY requests accumulate and
return data on some resources consumed by non-Teradata applications running on Teradata
Database nodes. To determine the resources consumed by non-Teradata applications,
compare:
82
•
Data returned by the MONITOR PHYSICAL RESOURCE request with that of the
MONITOR VIRTUAL RESOURCE request (that is, the subtotal of the various resource
statistics by node).
•
Data returned by the MONITOR PHYSICAL SUMMARY request with that of the
MONITOR VIRTUAL SUMMARY request (that is, the subtotal/average by node of the
various resource statistics in the MONITOR VIRTUAL SUMMARY).
Application Programming Reference
Chapter 4: System PMPC APIs
MONITOR PHYSICAL RESOURCE
MONITOR PHYSICAL RESOURCE
Purpose
Collects RSS data and returns node-specific data.
Input Data
Element
Data Type
Description
IndByte
BYTE
Indicator bits that specify which fields to treat as NULL if you are
using indicator mode.
Each bit in the byte corresponds to one field in the input data.
If data is supplied for that field, then set the bit to zero.
If the data for that field is NULL (that is, there is no data supplied
for that field), then set the bit to 1.
Note: The IndByte field is only required if the PM/API request is
submitted in indicator mode.
mon_ver_id
SMALLINT,
NOT NULL
MONITOR software version ID. This can be version 2 or later
only.
For a general explanation of monitor version choices, see
“MONITOR VERSION” on page 136.
Monitor Privileges
To use this request, you must have the MONRESOURCE privilege as part of your default role
or this privilege must be granted directly to you.
For more information on roles and privileges, see Database Administration and Security
Administration.
Usage Notes
Because information is given on the detailed resource usage of each node, performance
concerns can be isolated by node.
Use the MONITOR PHYSICAL RESOURCE request to:
•
Expand on the data reported by the MONITOR PHYSICAL SUMMARY request.
In your initial problem analysis, a MONITOR PHYSICAL SUMMARY request may
indicate a performance or system problem. MONITOR PHYSICAL RESOURCE allows
you to collect RSS data on a node by node basis.
•
Continually monitor your system.
Application Programming Reference
83
Chapter 4: System PMPC APIs
MONITOR PHYSICAL RESOURCE
Monitor your system on a periodic basis, for example, every 10 minutes. Use this request
to build a normal baseline profile for your system. When you notice something abnormal
or a user complains that a job is slow (such as the last reading is significantly different from
the normal baseline reading), this request can tell you:
•
•
If there is a parallel efficiency problem
•
A constraint to throughput
•
And which node is causing it.
Determine whether a new application can be added to the current system load without
disruption.
The node usage information collected by this request can help you evaluate the impact of
adding new applications to an already heavily utilized system and help you plan potential
system upgrades.
•
Help resolve problems that session-level usage information cannot resolve.
When the MONITOR SESSION request does not show any cause for the problem, the
MONITOR PHYSICAL RESOURCE request provides information on congestion,
memory allocations, BYNET outages, and system status.
The MONITOR PHYSICAL RESOURCE request provides the following information:
•
How the system is being used (for example, the percentage of CPU usage by node)
•
How system resource usage is spread across the nodes
•
How much physical disk Input/Output (I/O), BYNET traffic, or host reads and writes are
occurring
•
Whether congestion or excessive swapping is a problem on any node or group of nodes
The MONITOR PHYSICAL RESOURCE request returns some of the same fields found in the
resource usage tables. You can use both MONITOR PHYSICAL RESOURCE and resource
usage data for problem detection. Unlike resource usage data, MONITOR PHYSICAL
RESOURCE data is near real time, requires less overhead to produce, but is less
comprehensive. MONITOR PHYSICAL RESOURCE data helps detect:
•
Poor Node CPU parallel efficiency
•
Poor disk parallel efficiency
•
A higher than expected disk read/write ratio
•
A high swap I/O rate
If the MONITOR PHYSICAL RESOURCE request does not provide enough detailed data for
problem detection, run one or more of the resource usage macros. For more information, see
Resource Usage Macros and Tables.
For some of the MONITOR PHYSICAL RESOURCE and MonitorPhysicalResource fields,
NULL returns if:
84
•
A node is down or offline
•
The ResMonitor is set to zero
Application Programming Reference
Chapter 4: System PMPC APIs
MONITOR PHYSICAL RESOURCE
Note: You must set the ResMonitor rate to a nonzero value to allow the MONITOR
PHYSICAL RESOURCE request or MonitorPhysicalResource function to return
meaningful data.
•
A request for data is made before completion of the first collection period following either
a system outage or a change in the ResMonitor rate
After a system outage or a change in the ResMonitor rate, do not request data again until
after completion of the first collection period requested after the crash or change in rate.
Otherwise, the data returned will contain NULL except NetAUp, NetBUp, SampleSec,
ProcId, AMPCount, PECount, and Status, and may not be fully representative. The
in-memory counters reset after a crash. Typically the contents of the counters are not well
defined until a full collection period has elapsed. If you were logged on prior to the system
outage, and you issue the first MONITOR PHYSICAL RESOURCE request or
MonitorPhysicalResource function after the outage, then you will receive a warning that
the Teradata Database system has been restarted.
Parcels
The MONITOR PHYSICAL RESOURCE request is treated internally as a two statement
request with each statement generating a response. The Teradata Database returns a two
statement response containing the following sequence of parcel types.
Parcel
Sequence
Parcel
Flavor
Length
(Bytes)
Comments/Key Parcel Body Fields
Success
8
18 to 273
StatementNo = 1
ActivityCount = 1
ActivityType = 96 (PCLMONPRES)
DataInfo
71
6 to 64100
Optional; this parcel is present if request was
IndicData parcel.
Record
10
• 5 to 64100
(record
mode)
• 6 to 64100
(indicator
mode)
Depending on request (Data or IndicData),
data is in record or indicator mode. One
record is returned. It contains the duration of
the collection period (in seconds), BYNET
status, and the data and time of when the
Physical Resource cache was last refreshed.
EndStatement
11
6
StatementNo = 2-byte integer
Success
8
18 to 273
StatementNo = 2
ActivityCount = Number of nodes
ActivityType = 96 (PCLMONITOPRES)
DataInfo
Application Programming Reference
71
6 to 64100
Optional; this parcel is present if request was
IndicReq parcel.
85
Chapter 4: System PMPC APIs
MONITOR PHYSICAL RESOURCE
Parcel
Sequence
Parcel
Flavor
Length
(Bytes)
Record
10
• 5 to 64100
(record
mode)
• 6 to 64100
(indicator
mode)
Depending on request (Data or IndicData),
data is in record or indicator mode. One
record per node is returned. Each record
contains a description for each node,
including BYNET status.
EndStatement
11
6
StatementNo = 2-byte integer
EndRequest
12
4
None
Comments/Key Parcel Body Fields
Statement Type: 1
The response to the first statement results in a Record parcel containing global data about the
collection duration and BYNET status that is generated once for the whole system. The
following table shows the order in which the data is returned.
Field Name
Data Type
Description
NetAUp
VARCHAR (1),
NOT NULL
Status of the BYNETs (if there are more than two, the first
two) on a system-wide basis:
• U = All node BYNETs are up/online.
• D = One or more node BYNETs is down/offline.
• “” = A temporary condition where the BYNET data is not
available.
NetBUp
VARCHAR (1),
NOT NULL
Status of the BYNETs (if there are more than two, the first
two) on a system-wide basis:
• U = All node BYNETs are up/online.
• D = One or more node BYNETs is down/offline.
• “” = A temporary condition where the BYNET data is not
available.
SampleSec
SMALLINT,
NOT NULL
Duration of the collection period in seconds. This field is
equivalent to the ResMonitor rate. See “Data Collection”and
“SET RESOURCE RATE” for more information on
ResMonitor.
CollectionDate
DATE,
NOT NULL
Date the Physical Resource cache was last refreshed.
CollectionTime
FLOAT,
NOT NULL
Time the Physical Resource cache was last refreshed.
Statement Type: 2
The response to the second statement results in multiple Record parcels that consist of a one
record of 32 fields for each node in the system. For example, if you have 50 nodes, 50 records
86
Application Programming Reference
Chapter 4: System PMPC APIs
MONITOR PHYSICAL RESOURCE
are returned with specific information for each node. One record describes the collection
period and BYNET status for the entire system.
The following table shows the order in which the Record parcel returns the data.
Field Name
Data Type
Description
ProcId
SMALLINT,
NOT NULL
ID associated with a node. This value is computed as
the module number within a cabinet plus 100 times the
cabinet number. Usually formatted for display as zz999. However, this display format can be changed by the
user.
AmpCount
SMALLINT,
NOT NULL
Current number of AMPs currently executing on the
associated node.
PECount
SMALLINT,
NOT NULL
Current number of active PEs on the associated node.
CPUUse
FLOAT,
range 0 - 100%
% of CPU usage not spent being idle. This value is
computed from ResUsageSpma table data as:
PercntUser + PercntService
This value is NULL if certain conditions apply, see
“Usage Notes” on page 83 for details.
PercntIOWait
FLOAT
% of CPU resources in idle and waiting for I/O
completion. This value is computed from
ResUsageSpma data as follows, where x is the number
of CPUs:
CPUIOWAIT / (x * SampleSec)
This value is NULL if certain conditions apply, see
“Usage Notes” on page 83 for details.
PercntService
FLOAT
% of CPU resources spent in PDE user service
processing. The value is computed from the
ResUsageSpma table data, where x represents the
number of CPUs:
CPUUServ / (x * SampleSec)
This value is NULL if certain conditions apply, see
“Usage Notes” on page 83 for details.
PercntUser
FLOAT
% of CPU resources spent in non-service user code
processing. This value is computed from the
ResUsageSpma table data, where x represents the
number of CPUs:
CPUUExec / (x * SampleSec)
This value is NULL if certain conditions apply, see
“Usage Notes” on page 83 for details.
Application Programming Reference
87
Chapter 4: System PMPC APIs
MONITOR PHYSICAL RESOURCE
Field Name
Data Type
Description
Status
VARCHAR (1),
NOT NULL
Status of the node associated with this record:
• U = Up/online
• D = Down/offline
• S = Standby
A node is up (U) when it is:
• Configured into the system
• Online
• Capable of actively performing tasks associated with
normal Teradata Database activity
Down (D) represents all other potential states.
Standby (S) indicates the node is ready to join the
configuration in place if another node goes down.
When the node status is Standby, the SystemType,
NetAUp, and NetBUp fields are not available and NULL
or spaces will be returned.
NetAUse
FLOAT
% of BYNET A usage. This is the actual BYNET receiver
usage. (The BYNET transmitter usage is maintained in
resource usage separately and is typically lower than the
receiver usage. This is caused by multicasts, where one
transmitter sends a message to many receivers.) This
value is computed from the ResUsageSpma table data
as:
((NetSamples - NetTxIdle) / NetSamples)* 100.0
This value is NULL if certain conditions apply, see
“Usage Notes” on page 83 for details.
DiskUse
FLOAT
% of disk usage per node.
This value is computed from ResUsageSldv table data as
follows, assuming n is the number of ldv devices used
by this node:
(LdvOutReqTime 1 + ... + LdvOutReqTime n) /
(n*SampleSec)
This value is NULL if certain conditions apply, see
“Usage Notes” on page 83 for details.
Note: The DiskUse field does not take into account
overlapping of operations among multiple storage
devices, but it allows for the possibility of multiple
requests for the same device.
DiskReads
FLOAT
Total number of physical disk reads per node during the
collection period. This value is computed from
ResUsageSldv table data as follows, assuming n is the
number of ldv devices used by this node:
LdvReads 1 + ... + LdvReads n
This value is NULL if certain conditions apply, see
“Usage Notes” on page 83 for details.
88
Application Programming Reference
Chapter 4: System PMPC APIs
MONITOR PHYSICAL RESOURCE
Field Name
Data Type
Description
DiskWrites
FLOAT
Total number of physical disk writes per node during
the collection period. This value is computed from
ResUsageSldv table data as follows, assuming n is the
number of ldv devices used by this node:
LdvWrites 1 + ... + LdvWrites n
This value is NULL if certain conditions apply, see
“Usage Notes” on page 83 for details.
DiskOutReqAvg
FLOAT
Average number of outstanding disk requests per disks
(averaged over all the disks on a node). This value can
be used to monitor the load on the disks and indicate
problems with the throughput if the level becomes too
high.
This value is computed from ResUsageSldv table data as
follows, assuming n is the number of ldv devices used
by this node:
((LdvOutReqSum 1 / NULLIFZERO(LdvOutReqDiv
1)) + … + (LdvOutReqSum n /
NULLIFZERO(LdvOutReqDiv n))) / n
The range of the value is typically 0 to 25.
This value is NULL if certain conditions apply, see
“Usage Notes” on page 83 for details.
HostBlockReads
FLOAT
Number of message blocks (one or more messages sent
in one physical group) received from all clients. This
value is computed from ResUsageShst data, assuming n
is the number of host channel and network connections
on this node:
HostBlockReads1 + ... + HostBlockReadsn
This value is NULL if certain conditions apply, see
“Usage Notes” on page 83 for details.
HostBlockWrites
FLOAT
Number of message blocks (that is, one or more
messages sent in one physical group) sent to all hosts.
For node displays, this value is computed from
ResUsageShst data, assuming n is the number of host
channel and network connections on this node:
HostBlockWrites1 + ... + HostBlockWritesn
This value is NULL if certain conditions apply, see
“Usage Notes” on page 83 for details.
SwapReads
FLOAT
Number of pages/segments read into node memory
from the disk during the collection period after a prior
write/drop. This value is computed from the
ResUsageSpma table data as MemCtxtPageReads.
For information on MemCtxtPageReads, see Resource
Usage Macros and Tables.
This value is NULL if certain conditions apply, see
“Usage Notes” on page 83 for details.
Application Programming Reference
89
Chapter 4: System PMPC APIs
MONITOR PHYSICAL RESOURCE
Field Name
Data Type
Description
SwapWrites
FLOAT
Number of pages/segments written to swap area from
node memory during the collection period. This value
is computed from the ResUsageSpma table data as
MemCtxtPageWrites.
For information on MemCtxtPageReads, see Resource
Usage Macros and Tables.
This value is NULL if certain conditions apply, see
“Usage Notes” on page 83 for details.
SwapDrops
FLOAT
Number of pages/segments dropped from node
memory during the collection period due to swapping.
This field returns zero.
MemAllocates
FLOAT
Note: This field is obsolete and returns zero or NULL.
MemAllocateKB
FLOAT
Value represents the change in the node-level memory.
MemAllocateKB represents a delta from the previous
reporting period. It reports negative values as less
memory is used.
This value is calculated from the ResUsageSpma
column:
MemVprAllocKB
This value is NULL if certain conditions apply, see
“Usage Notes” on page 83 for details.
MemFailures
FLOAT
Note: This field is obsolete and returns zero or NULL.
MemAgings
FLOAT
Note: This field is obsolete and returns zero or NULL.
NetReads
FLOAT
Number of Reads from the BYNET to the node. This
value is computed from the ResUsageSpma table data
as:
NetRxCircBrd + NetRxCircPtP
This value is NULL if certain conditions apply, see
“Usage Notes” on page 83 for details.
NetWrites
FLOAT
Number of messages written from the node to the
BYNET during the collection period. For node-level
displays, the value is computed from the ResUsageSpma
table data as:
NetTxCircBrd + NetTxCircPtP
This value is NULL if certain conditions apply, see
“Usage Notes” on page 83 for details.
NetAUp
VARCHAR (1),
NOT NULL
Status of the BYNETs (if there are more than two, the
first two) on a system-wide basis:
• U = Node BYNET is up/online.
• D = Node BYNET is down/offline.
• “” = A temporary condition where the BYNET data
is not available.
90
Application Programming Reference
Chapter 4: System PMPC APIs
MONITOR PHYSICAL RESOURCE
Field Name
Data Type
Description
NetBUp
VARCHAR (1),
NOT NULL
Status of the BYNETs (if there are more than two, the
first two) on a system-wide basis:
• U = Node BYNET is up/online.
• D = Node BYNET is down/offline.
• “” = A temporary condition where the BYNET data
is not available.
Sample Input
The following example shows how the parcels built by CLIv2 for a MONITOR PHYSICAL
RESOURCE request look when sent to Teradata Database.
Note: In this example, the size of the response buffer is set at the maximum (64,000 bytes),
although you can set it to any size. However, a minimum response size is 32,000 bytes.
Flavor
Length
Body
Num
Name
Bytes
Field
Value
0001
Req
20
Request
MONITOR PHYSICAL RESOURCE
0003
Data
6
MonVerID
9
0004
Resp
6
BufferSize
64000
Sample Output
This request might return the following values in character text format (a record for each
node). Your application program may display returned values in a different format.
Note: You can rename the SampleSec field in your application. In the output below, the
SampleRate value is the SampleSec value.
Pay attention to SampleRate when interpreting the results of this request.
Success parcel:
StatementNo=1,
ActivityCount=1,
ActivityType=96, FieldCount=5
NetAUp: U NetBUp: U
SampleRate: 30
Collection Date/Time: 06/15/2011 18:28:01.00
EndStatement.
Success parcel:
StatementNo=2,
ActivityCount=1,
ActivityType=96, FieldCount=26
ProcId:
33
Status: U
AmpCount: 4
PECount: 2
CPUUse:
99.8
Application Programming Reference
91
Chapter 4: System PMPC APIs
MONITOR PHYSICAL RESOURCE
PrcntKernel:
0.2
DiskUse:
28.7
DiskReads:
74.00
NetAUse:
0.0
HstBlkRds:
1.00
MemAllocates:
MemFailures:
NetAUp: U NetBUp:
EndStatement.
EndRequest.
PrcntService:
1.4
PrcntUser: 98.4
DiskWrites: 14229.00
DiskOutReqAvg:
NetReads:
0.00
NetWrites:
0.00
HstBlkWrts:
0.00
0.00
MemAllocateKB: 116.00
0.00
MemAgings:
0.00
0.59
U
Relationship Between MONITOR PHYSICAL RESOURCE and ABORT
SESSION
If you executed an ABORT SESSION request, data returned in a MONITOR PHYSICAL
RESOURCE or MONITOR VIRTUAL RESOURCE request may be altered. Whether you
notice the change in data depends on the scope of the ABORT SESSION request. For example,
if you execute an ABORT SESSION and log off all of the sessions associated with a specific
host (or client), the PEs associated with that client will report a large decrease in resource
consumption. However, if the ABORT SESSION request only aborts one transaction from one
session, you may not notice a change in AMP or PE resource use.
Relationship Between MONITOR PHYSICAL RESOURCE and
SET RESOURCE RATE
You must execute the SET RESOURCE RATE request to activate resource data collection
before you execute a MONITOR VIRTUAL RESOURCE or MONITOR PHYSICAL
RESOURCE request. This means that you must set the resource monitoring rate (ResMonitor)
to nonzero. If the ResMonitor rate is set to zero, you will receive an error message.
A change in the resource collection rate by User A, for example, may affect the data reported
by MONITOR VIRTUAL RESOURCE or MONITOR PHYSICAL RESOURCE request made
by User B. If the ResMonitor rate has been altered, User B receives a warning message when
executing a subsequent MONITOR VIRTUAL RESOURCE or MONITOR PHYSICAL
RESOURCE request.
92
Application Programming Reference
Chapter 4: System PMPC APIs
MONITOR PHYSICAL SUMMARY
MONITOR PHYSICAL SUMMARY
Purpose
Collects global summary information that includes the following types of information:
•
CPU usage (average, high, and low)
•
Disk usage (average, high, and low)
•
BYNET usage (total, up/down)
•
Rate information (resource logging rate and resource monitoring rate)
•
Current software release and version numbers
Input Data
Element
Data Type
Description
IndByte
BYTE
Indicator bits that specify which fields to treat as NULL if you are
using indicator mode.
Each bit in the byte corresponds to one field in the input data.
If data is supplied for that field, then set the bit to zero.
If the data for that field is NULL (that is, there is no data supplied
for that field), then set the bit to 1.
Note: The IndByte field is only required if the PM/API request is
submitted in indicator mode.
mon_ver_id
SMALLINT,
NOT NULL
MONITOR software version ID. This can be version 2 or later.
For a general explanation of monitor version choices, see
“MONITOR VERSION” on page 136.
Monitor Privileges
To use this request, you must have any one of the following monitor privileges as part of your
default role or any of these privileges must be granted directly to you:
•
ABORTSESSION
•
MONRESOURCE
•
MONSESSION
•
SETRESRATE
•
SETSESSRATE
For more information on roles and privileges, see Database Administration and Security
Administration.
Application Programming Reference
93
Chapter 4: System PMPC APIs
MONITOR PHYSICAL SUMMARY
Usage Notes
For some of the MONITOR PHYSICAL SUMMARY and MonitorPhysicalSummary fields,
NULL returns if:
•
A node is down or offline
•
The ResMonitor is set to zero
Note: You must set the ResMonitor rate to a nonzero value to allow the MONITOR
PHYSICAL SUMMARY request or MonitorPhysicalSummary function to return
meaningful data.
•
A request for data is made before completion of the first collection period following either
a system outage or a change in the ResMonitor rate
After a system outage or a change in the ResMonitor rate, do not request data again until
after completion of the first collection period requested after the crash or change in rate.
Otherwise, the data returned will contain NULL except NetAUp, NetBUp, SampleSec,
ProcId, AMPCount, PECount, and Status, and may not be fully representative. The
in-memory counters reset after a crash. Typically the contents of the counters are not well
defined until a full collection period has elapsed. If you were logged on prior to the system
outage, and you issue the first MONITOR PHYSICAL SUMMARY request or
MonitorPhysicalSummary function after the outage, then you will receive a warning that
the Teradata Database system has been restarted.
Note: If PE only (AMP-less) nodes exist and if the nodes should be included in the
MONITOR PHYSICAL SUMMARY statistics calculation, you must set the DBS Control field,
MPS_IncludePEOnlyNodes, to TRUE. In normal use of Monitor Physical Summary, the
MPS_IncludePEOnlyNodes field is set to FALSE.
By default, the statistics for PE only nodes are excluded in the calculation of MONITOR
PHYSICAL SUMMARY statistics. For information about the MPS_IncludePEOnlyNodes
field, see Utilities.
Parcels
The response returned from the Teradata Database resembles a summary of the type of
response returned by a MONITOR PHYSICAL SUMMARY request. The response is one row
of 22 fields. The response returned from Teradata Database contains the following sequence of
parcel types.
Parcel
Sequence
Parcel
Flavor
Length
(Bytes)
Comments/Key Parcel Body Fields
Success
8
18 to 273
StatementNo = 1
ActivityCount = 1
ActivityType = 94 (PCLMONPSUMMARY)
DataInfo
94
71
6 to 64100
Optional; this parcel is present if request was
IndicData parcel.
Application Programming Reference
Chapter 4: System PMPC APIs
MONITOR PHYSICAL SUMMARY
Parcel
Sequence
Parcel
Flavor
Length
(Bytes)
Comments/Key Parcel Body Fields
Record
10
• 5 to 64100
(record mode)
• 6 to 64100
(indicator
mode)
Depending on request (Data or IndicData),
data is in record or indicator mode. This record
contains the Data or IndicData physical
summary information and the date and time
the Physical Resource cache was last refreshed.
EndStatement
11
6
StatementNo = 2-byte integer
EndRequest
12
4
None
For more information on parcel body fields, see the appropriate chapter in Teradata Call-Level
Interface Version 2 Reference for Mainframe-Attached Systems or Teradata Call-Level Interface
Version 2 Reference for Network-Attached Systems.
The following table describes the resource usage information returned from the Record parcel
for the MONITOR PHYSICAL SUMMARY response.
Field Name
Data Type
Description
AvgCPU
FLOAT
Average % CPU usage (CPUUse) time of all online
nodes currently in the Teradata Database configuration.
This value is NULL if certain conditions apply, see
“Usage Notes” on page 94 for details.
AvgDisk
FLOAT
Average % disk usage (from DiskUse) of all online nodes
currently in the Teradata Database configuration.
This value is NULL if certain conditions apply, see
“Usage Notes” on page 94 for details.
AvgDiskIO
FLOAT
Average number DiskReads and DiskWrites for all online
nodes currently in the Teradata Database configuration.
This value is NULL if certain conditions apply, see
“Usage Notes” on page 94 for details.
HighCPUUse
FLOAT
Highest CPUUse number associated with any online
node that is currently part of the Teradata Database
configuration.
This value is NULL if certain conditions apply, see
“Usage Notes” on page 94 for details.
HighCPUProcId
SMALLINT
ID of a node with CPPUse equal to the value reported as
HighCPUUse.
This value is NULL if certain conditions apply, see
“Usage Notes” on page 94 for details.
Application Programming Reference
95
Chapter 4: System PMPC APIs
MONITOR PHYSICAL SUMMARY
Field Name
Data Type
Description
LowCPUUse
FLOAT
Lowest CPUUse number associated with any online
node that is currently part of the Teradata Database
configuration.
This value is NULL if certain conditions apply, see
“Usage Notes” on page 94 for details.
LowCPUProcId
SMALLINT
ID of a node with CPPUse equal to the value reported as
LowCPUUse.
This value is NULL if certain conditions apply, see
“Usage Notes” on page 94 for details.
HighDisk
FLOAT
Highest % disk usage (from DiskUse) associated with
any online node that is currently part of the Teradata
Database configuration.
This value is NULL if certain conditions apply, see
“Usage Notes” on page 94 for details.
HighDiskProcId
SMALLINT
ID of a node with DiskUse equal to the value reported as
HighDisk.
This value is NULL if certain conditions apply, see
“Usage Notes” on page 94 for details.
LowDisk
FLOAT
Lowest % disk usage (from DiskUse) associated with any
online node that is currently part of the Teradata
Database configuration.
This value is NULL if certain conditions apply, see
“Usage Notes” on page 94 for details.
LowDiskProcId
SMALLINT
ID of a node with DiskUse equal to the value reported as
LowDisk.
This value is NULL when LowDisk is NULL.
HighDiskIO
FLOAT
Highest DiskReads and DiskWrites number associated
with any online node that is currently active in the
Teradata Database configuration.
This value is NULL if certain conditions apply, see
“Usage Notes” on page 94 for details.
HighDiskIOProcId
SMALLINT
ID of a node with DiskReads and DiskWrites equal to the
value reported as HighDiskIO.
This value is NULL if certain conditions apply, see
“Usage Notes” on page 94 for details.
LowDiskIO
FLOAT
Lowest DiskReads and DiskWrite number associated
with any online node that is currently part of the
Teradata Database configuration.
This value is NULL if certain conditions apply, see
“Usage Notes” on page 94 for details.
96
Application Programming Reference
Chapter 4: System PMPC APIs
MONITOR PHYSICAL SUMMARY
Field Name
Data Type
Description
LowDiskIOProcId
SMALLINT
ID of a node with DiskReads and DiskWrites equal to the
value reported as LowDiskIO.
This value is NULL when LowDiskIO is NULL.
NetUse
FLOAT
% of total BYNET use (that is, average of the online
BYNETs).
If both BYNETs are up, the value is computed from
ResUsageSpma table data as:
NetUse = Average NetAUse per node / NetCount
where:
• NetCount is 2 if both NetA and NetB are up or 1 if
only one of the BYNET is up.
• Average NetAUse is the sum of all NetAUse of each
node divided by the number of online nodes.
This value is NULL if certain conditions apply, see
“Usage Notes” on page 94 for details.
Note: NetUse returns a value of zero because resource
usage data is not currently available.
NetAUp
VARCHAR (1),
NOT NULL
Status of the BYNETs (if there are more than two, the
first two) on a system-wide basis:
• U = All node BYNETs are up/online.
• D = One or more node BYNETs is down/offline.
• “” = A temporary condition where the BYNET data is
not available.
NetBUp
VARCHAR (1),
NOT NULL
Status of the BYNETs (if there are more than two, the
first two) on a system-wide basis:
• U = All node BYNETs are up/online.
• D = One or more node BYNETs is down/offline.
• “” = A temporary condition where the BYNET data is
not available.
ResLogging
SMALLINT,
NOT NULL,
range 0-3600
seconds,
Interval in seconds at which resource usage data is
written to one or more active resource usage database
tables.
ResMonitor
SMALLINT,
NOT NULL,
range 0-3600
seconds
Interval in seconds at which all resource usage data is
collected in memory for reporting via the PM/API.
Release
VARCHAR (29),
NOT NULL
Release number of the currently running Teradata
Database software (for example, 14.00.00.00).
This value is supplied by Teradata Database.
Application Programming Reference
97
Chapter 4: System PMPC APIs
MONITOR PHYSICAL SUMMARY
Field Name
Data Type
Description
Version
VARCHAR (32),
NOT NULL
Version number of the currently running Teradata
Database software (for example, 14.00.00.00).
This value is supplied by Teradata Database.
CollectionDate
DATE,
NOT NULL
Date the Physical Resource cache was last refreshed.
CollectionTime
FLOAT,
NOT NULL
Time the Physical Resource cache was last refreshed.
Sample Input
The following example shows how the parcels for a MONITOR PHYSICAL SUMMARY
request, built by CLIv2, look when sent to Teradata Database.
Note: In this example, the size of the response buffer in the example is set at the maximum
(64,000 bytes), although you can set it to any size. However, a minimum response size is
32,000 bytes.
Flavor
Length
Body
Num
Name
Bytes
Field
Value
0001
Req
28
Request
MONITOR PHYSICAL SUMMARY
0003
Data
6
MonVerID
9
0004
Resp
6
BufferSize
64000
Sample Output
The following example shows the values returned in character text format for the MONITOR
PHYSICAL SUMMARY request. Your application program may display returned values in a
different format.
Success parcel:
StatementNo=1,
ActivityType=94,
AvgCPU:
ActivityCount=1,
FieldCount=24
99.87
AvgDisk:
29.47
AvgDiskIO:
14499.00
HighCPUUse:
99.87
HighCPUProcId:
33
HighDisk:
29.47
HighDiskProcId:
33
HighDiskIO:
14499.00
HighDiskIOProcId:
33
LowCPUUse:
LowCPUProcId:
LowDisk:
LowDiskProcId:
LowDiskIO:
14499.00
LowDiskIOProcId:
33
NetUse:
ResLogging:
99.87
33
0.00
600
NetAUp:
U
ResMonitor:
29.47
33
NetBUp:
U
30
Release: 14f.00.00.249 Version: 14f.00.00.249
98
Application Programming Reference
Chapter 4: System PMPC APIs
MONITOR PHYSICAL SUMMARY
Collection Date/Time:
EnStatement.
EndRequest.
06/15/2011 18:29:01.00
Warning and Error Messages
All users who are logged on and issue a MONITOR PHYSICAL SUMMARY request after a
system restart or after the last rate change can expect to receive a warning. Users will also
receive a warning if the resource monitoring rate (ResMonitor) is set to zero.
Either MONITOR PHYSICAL SUMMARY or MONITOR PHYSICAL RESOURCE requests
issues a warning for any sessions logged on prior to the database recovery, or prior to the
change in the ResMonitor collection rate.
For more detailed information on warning and error messages, see Messages.
Relationship Between MONITOR PHYSICAL SUMMARY and
MONITOR PHYSICAL CONFIG
Use the MONITOR PHYSICAL SUMMARY request with the MONITOR PHYSICAL
CONFIG request for an overall system status. These are low overhead requests.
•
Execute the MONITOR PHYSICAL SUMMARY request every 5 or 10 minutes for a lowcost, continuous monitoring of your system.
•
Execute the MONITOR PHYSICAL CONFIG request to get a picture of your system
configuration at defined times, such as at the beginning of a day, various times during the
day, or when the system is down.
For information on this PMPC CLIv2 request relationship, see “Relationship Between
MONITOR PHYSICAL CONFIG and MONITOR PHYSICAL SUMMARY” on page 81.
Relationship Between MONITOR PHYSICAL SUMMARY and
SET RESOURCE RATE
The SET RESOURCE RATE request sets the ResMonitor and ResLogging rates, which are
among the responses returned by the MONITOR PHYSICAL SUMMARY or MONITOR
VIRTUAL SUMMARY request. Any change to either the ResMonitor or ResLogging rate
results in changes in the corresponding response returned by the MONITOR VIRTUAL
SUMMARY or MONITOR PHYSICAL SUMMARY request.
You must set ResMonitor to a nonzero rate for MONITOR PHYSICAL SUMMARY or
MONITOR VIRTUAL SUMMARY to return meaningful resource utilization data. A zero
ResMonitor rate returns NULL values for resource utilization information.
Relationship Between MONITOR PHYSICAL SUMMARY and
SET SESSION RATE
Changes to the session-level rates (global and local) specified by SET SESSION RATE are
reported in the data returned by MONITOR PHYSICAL SUMMARY or MONITOR
VIRTUAL SUMMARY.
Application Programming Reference
99
Chapter 4: System PMPC APIs
MONITOR PHYSICAL SUMMARY
Note: The local rate reported is your own local rate. If the local rate is not set, the local rate is
reported as zero.
As more session-level monitoring is done (by setting a faster SET SESSION RATE), the
resulting overhead may increase the level of CPU usage (reported in MONITOR PHYSICAL
SUMMARY or MONITOR VIRTUAL SUMMARY data) by your system. However, this may
depend on the size of the rate change and the type of work done by other sessions.
100
Application Programming Reference
Chapter 4: System PMPC APIs
MONITOR SESSION
MONITOR SESSION
Purpose
Returns session or request resource usage statistics.
Input Data
Element
Data Type
Description
IndByte
BYTE
Indicator bits that specify which fields to treat as NULL if
you are using indicator mode.
Each bit in the byte corresponds to one field in the input
data.
If data is supplied for that field, then set the bit to zero.
If the data for that field is NULL (that is, there is no data
supplied for that field), then set the bit to 1.
Note: The IndByte field is only required if the PM/API
request is submitted in indicator mode.
mon_ver_id
SMALLINT
NOT NULL
MONITOR software version ID. This can be version 2 or
later.
Note: Version 6 or later can be used to determine if a
utility session is on the Teradata dynamic workload
management software delay queue. For information on
returning the utility delay queue, see
“TDWMGetDelayedUtilities” on page 373.
For a general explanation of monitor version choices, see
“MONITOR VERSION” on page 136.
host_id
SMALLINT
Logical ID of a host (or client) with sessions logged on.
host_id cannot exceed 1023. A host_id of zero identifies
the system console ID of the host on which sessions are
running.
session_no
INTEGER
Session number. The session number combined with the
host_id represents a unique session ID.
user_name
VARCHAR (30)
Name of the user or database that is running this session.
Note:
•
If you do not specify host_id, user_name, or session_no, all hosts, all users, or all sessions
are monitored. For example, if you specify 127 for host_id, PEDERSON for user_name,
Application Programming Reference
101
Chapter 4: System PMPC APIs
MONITOR SESSION
and do not specify session_no, the MONITOR SESSION request reports on all sessions
currently logged on from host 127 as user PEDERSON.
•
NULL in any field, with the exception of mon_ver_id, indicates a match for all potential
values of that field. A NULL for mon_ver_id will produce an error response. Remember
that IndicData parcels are used to specify the output fields that are null. For additional
information on IndicData, see “Creating a Request” on page 35.
For information on the data returned for each monitor version, see “Response Parcel
Groups” on page 108.
Monitor Privileges
To use this request, you must have MONSESSION privilege as part of your default role or this
privilege must be granted directly to you.
For more information on roles and privileges, see Database Administration and Security
Administration.
Usage Notes
Use this information, when a job hangs because of unavailable resources, to find out about the
following:
•
The user causing a block
•
The locked database or table
•
System usage data on a session-by-session basis
In the MONITOR partition, each job is a session. You can execute the MONITOR SESSION
request to query:
•
All hosts (or clients) with all sessions
•
Single host (or client) with all sessions
•
Single host (or client) with all sessions for a given user name
•
Single host (or client) with a single session and a given user name
MONITOR SESSION requests return data:
•
Identical for all sessions
•
Specific to a particular session
MONITOR SESSION requests return accumulated session statistics commencing with the last
time that one of the following events impacted a session:
•
The time that a session logged on.
•
The time that a session-switch changed the vproc with Session Control responsibility for a
session.
•
The time that a system crash or TPA restart occurred.
•
The time that system or local rate was set to a nonzero value.
A MONITOR SESSION request can also be used to track session-level AMP usage and provide
data on the three highest and lowest CPU/IO utilized AMPs. This can help identify:
102
Application Programming Reference
Chapter 4: System PMPC APIs
MONITOR SESSION
•
Skewed data
•
Possible hardware problems
•
Possible Teradata Database bugs
You can use the data returned by the MONITOR SESSION request as input for the IDENTIFY
request to determine lock activity. For more information, see “IDENTIFY” on page 61.
Be aware of the following rules:
•
To collect statistics, set the system or local rate to a nonzero value.
•
Data on a particular session is only reported for the last complete collection period. For
example, assume the collection rate is 600 seconds (or 10 minutes) and that you issue a
MONITOR SESSION request at 9:00 a.m. If the user for whom you are seeking data
logged onto the system at 9:01 a.m., no session data would be available until the next
MONITOR SESSION request is issued at 9:10 a.m. (upon completion of the current
collection period). A MONITOR SESSION request made at 9:05 a.m. (after the user
logged on at 9:01 a.m.) only reports on sessions that stayed logged on at 9:00 a.m.
•
When a session-switch changes the processor with session control responsibility for a
session, previous data in memory is lost and the data collection for the affected session
starts over again.
•
When a system crash occurs, the system crash clears out the previous data and data
collection starts over again.
The RSS data loss affects only specific sessions when a session logs off or a PE goes down,
forcing all sessions on that PE to switch to another PE. In other cases, such as a system outage,
the data loss affects all sessions.
If a system failure occurs, then the response to subsequent MONITOR SESSION requests
contains a warning message. For more information, see Messages.
The MONITOR SESSION request always returns an ActivityCount (one of the fields in the
Success parcel indicating total number of records selected, updated, and so forth) equal to 0 or
-1.
IF ActivityCount is...
THEN...
0
no session matched the requested combination of logical HostId,
UserName, and SessionNo.
-1
this request generates an unknown number of Response Rows. The
application must continue to gather data until it encounters the
EndStatement parcel.
A value of -1 is used because ActivityCount cannot be determined when
the request is executed. Because the response is collected from data shared
by all running Monitor sessions, that data can be updated while a request
is in progress. If that update adds or removes information on sessions, the
activity count calculated at the beginning of a particular session query
response generation does not become valid by the end of the response
processing for that session. Rather than return possibly incorrect data, the
ActivityCount is set to indicate that the count is unknown.
Application Programming Reference
103
Chapter 4: System PMPC APIs
MONITOR SESSION
The following CPU fields in the MONITOR SESSION response are affected by the
MonSesCPUNormalization field:
•
•
•
•
AMPCPUSec
AvgAmpCPUSec
HotAmp1CPU
HotAmp2CPU
•
•
•
•
HotAmp3CPU
LowAmp1CPU
LowAmp2CPU
LowAmp3CPU
• PECPUSec
• RequestAmpCPU
The MonSesCPUNormalization field, a DBS Control General Record field, controls whether
normalized or non-normalized statistical CPU data is reported by the MONITOR SESSION
request, and by the functions: MonitorMySessions and MonitorSession. For more
information about the MonSesCPUNormalization field and CPU normalization, see the DBS
Control utility in Utilities.
For a complete description of these fields, see “Response Parcel Groups” on page 108.
You can also refer to “MonitorMySessions” on page 211 or “MonitorSession” on page 240 for
a list of these CPU fields.
Collecting Session Data
After a collection interval is set to a nonzero rate, session usage data is accumulated in AMP
and PE storage areas (regardless of the rate set). When a user makes a MONITOR request, the
central coordinator task determines if more current data is necessary. If more current data is
required, the central coordinator task directs the processors to transmit data from processor
storage areas on the AMPs to the main memory repository on each PE where each PE is
simultaneously collecting its own session data. Otherwise, data in the main PE repositories is
considered current and is sent to the user.
All current data is associated with an internal timestamp not visible to the user. Every
MONITOR SESSION request issued by a user is associated with a session-level data collection
rate. This rate is the local rate if a local rate has been set. Otherwise, it is the global rate.
When a user executes a MONITOR SESSION request, the central coordinator task checks the
age of the current session-level data (current time minus the data timestamp). Depending on
the age determination, action is then taken on the data as shown in the table below.
104
IF data in the PE memory repository is...
THEN...
considered current (the age of the data is less
than or equal to the session collection rate)
this data is returned to the user.
not considered current (the age of the data is
greater than the session collection rate)
the coordinator task forces a data update
(causing its internal timestamp to be reset to the
current time) and returns the updated data to the
user.
Application Programming Reference
Chapter 4: System PMPC APIs
MONITOR SESSION
Unreported Session Partitions
Resource usage in some session partitions may not be reported or fully reported. MONITOR
SESSION requests do not report statistics on session resources used by the DBCUTIL utility.
Although resource usage is reported, not all resource usage data is accounted for. These
restrictions may affect the following data returned from a MONITOR SESSION request:
•
AMPCPUSec
•
AMPIO
•
Request_AMPSpool
•
AMPState
•
PECPUSec
•
PEState
•
ReqCount
As an example of how the returned data is affected, both AMPState and PEState data values
may be UNKNOWN if I/O is done on behalf of the unreported partitions. As another
example, in a Teradata SQL session, PECPUSec spent in a PE do not include time spent in
Gateway communications processing.
A Down Processor
When a previously active PE is down because of a system outage, the data returned for those
sessions logged on to the down processor may not be meaningful. If you encounter a system
outage, pay attention to the following information, because the PE data does not change:
•
•
•
•
•
HostId
LogonPENo
SessionNo
UserName
UserAccount
•
•
•
•
•
UserID
LSN
LogonTime
LogonDate
PartName
• PEState
• LogonSource
Internal Sessions
Internal sessions are a part of the database software and cannot be started or aborted from the
client. For example, the operation sending a message from a parser to an AMP is an internal
session.
Internal sessions can cause problems because:
•
They may be blocking an important session.
•
They are hard to recognize.
•
They may be blocked by other requests.
Internal sessions that are blocked are reported by MONITOR SESSION. These include:
•
Internal sessions associated with the user that show the blocking activity on the user
session itself.
Application Programming Reference
105
Chapter 4: System PMPC APIs
MONITOR SESSION
•
DBQL/Teradata dynamic workload management software artificial internal sessions that
appear in the Monitor Session output and exist only to show blocked DBQL/Teradata
dynamic workload management software internal express requests.
Note: For information on handling blocked DBQL/Teradata dynamic workload
management software internal express requests, see Database Administration.
You must determine what to do about a session that is blocking some important activity.
The following fields (returned by a MONITOR SESSION request) may provide information
about internal sessions blocking other sessions:
•
Blk_x_HostId
•
Blk_x_SessNo
•
Blk_x_UserID
Some internal sessions are not easy to recognize simply from the data returned in these Blk_x
fields. With an internal session, any or all of the Blk_x fields may be NULL. In this case, you
might mistake an internal session with a NULL Blk_x_SessNo for a client utility session. All
three fields could be filled in with legitimate looking values. In this case, you can frequently
recognize an internal session by a value of zero in the Blk_x_HostId field. Still, this is not
guaranteed, because a Teradata SQL session started from the system console running DBW
has a value of zero in the Blk_x_HostId field.
The following matrix provides some guidelines for recognizing internal sessions the HostId,
SessNo, and UserID Blk_x fields internal sessions.
106
For fields:
If Values Are:
Session Type is:
HostId, SessNo, UserID
NULL
Internal session
• HostId & SessNo
• UserID
• NULL
• Non-NULL
Idle Client utility
HostId, SessNo, UserID
Non-NULL
Special rule: A MONITOR SESSION
request does not return a record for an
internal session. If you specify internal
session in an IDENTIFY request to
specify the name of the session causing
the lock, the session returns an error
message.
If...
Then...
an internal session is blocking an important
session
you cannot abort the internal session.
the internal session lock request is waiting
you can abort the work of the sessions that are
blocking the internal sessions.
the internal session lock request is granted
you must wait for it to complete.
Application Programming Reference
Chapter 4: System PMPC APIs
MONITOR SESSION
Parcels
The MONITOR SESSION request is treated internally as a two statement request with each
statement generating a response. The two statement response returned from Teradata
Database contains the following sequence of parcel types:
Parcel
Sequence
Parcel
Flavor
Length
(Bytes)
Comments and Key Parcel Body Fields
Success
8
18 to 273
StatementNo = 1
ActivityCount = 1
ActivityType = 84 (PCLMONSESS)
DataInfo
71
6 to 64100
Optional; this parcel is present if request was
IndicData parcel.
Record
10
5 to 64100
(record mode)
Depending on request (Data or IndicData), data is
in record or indicator mode. This is the first record
returned.
6 to 64100
(indicator
mode)
EndStatement
11
6
StatementNo = 2-byte integer
Success
8
18 to 273
StatementNo = 2
ActivityCount = -1 or 0
ActivityType = 84 (PCLMONSESS)
DataInfo
71
6 to 64100
Optional; this parcel is present if request was
IndicData parcel.
Record
10
5 to 64100
(record mode)
6 to 64100
(indicator
mode)
Depending on request (Data or IndicData), data is
in record or indicator mode. This is the second
record returned. It contains data describing the
session. See “Response Parcel Groups” on page 108
for details.
EndStatement
11
6
StatementNo = 2-byte integer
EndRequest
12
4
None
The response to the first statement results in a Record parcel containing the following fields:
Field Name
Data Type
Description
CollectionInterval
SMALLIN,
NOT NULL
Actual interval in seconds between current and last
cache refresh.
CollectionSeqNum
INTEGER,
NOT NULL
Monitor session cache refresh sequence number.
Application Programming Reference
107
Chapter 4: System PMPC APIs
MONITOR SESSION
Field Name
Data Type
Description
CollectionDate
DATE,
NOT NULL
Database date of when the session cache was last
refreshed.
CollectionTime
FLOAT,
NOT NULL
Database time of when the session cache was last
refreshed.
SessionRate
SMALLINT,
NOT NULL
Session rate.
ExceptionInterval
SMALLINT,
NOT NULL
Exception interval. If the Teradata ASM Workloads
rule is disabled, then zero is returned. For information
on the Workloads rule, see Teradata Viewpoint User
Guide.
SessionRateThreshold
SMALLINT,
NOT NULL
DBS Control PMPC_SessionRateThreshold value. See
the DBS Control PMPC_SessionRateThreshold field in
Utilities, for details.
DBQLFlushRate
SMALLINT,
NOT NULL
DBS Control DBQLFlushRate value. See the DBS
Control DBQLFlushRate field in Utilities for details.
RedriveProtection
VARCHAR (2),
NOT NULL
Note: This field is reserved for future use.
The response to the second statement results in multiple Record parcels that consist of a
record for each session in the system. Records are sorted in order of LogonPENo, HostId, and
SessionNo.
Response Parcel Groups
There are five groups of response parcel fields returned by the MONITOR SESSION request.
The following table shows the different values returned from the mon_ver_id.
mon_ver_ID Entry
Response Parcel
Group Returned
2
Group I
Returns data fields concerned primarily with session-level
user status.
3
Groups I and II
In addition, returns data fields on session-specific AMP
resource usage.
4
Groups I-III
In addition, returns request level usage information.
5
Groups I-IV
Returns data fields concerned with Group I through IV
6
Groups I-IV
Returns data fields concerned with Group I through IV.
Description
Note: This value is required for Teradata Dynamic
Workload Management PM/APIs.
7 and 8
108
Groups I-V
Returns data fields concerned with Group I through
Group V.
Application Programming Reference
Chapter 4: System PMPC APIs
MONITOR SESSION
mon_ver_ID Entry
Response Parcel
Group Returned
Description
9
Groups I - VI
Returns data fields concerned with Group I through VI.
Group I Data Fields
The Record parcel returns the following Group I data values.
Field Name
Data Type
Description
HostId
SMALLINT
Logical host ID associated with a PE or session. For a
PE, the Host ID identifies one of the hosts or LANs
associated with the described PE. For a session, the
combination of a Host ID and a session number
uniquely identifies a user session on the system.
Note: This value is NULL for AMPs. A value of zero
represents the Supervisor window.
LogonPENo
SMALLINT,
NOT NULL
Vproc number of the PE the session is currently
logged on to; it identifies the PE that has control
responsibility for the session. Normally, this is the PE
that processed the logon request; but if that PE goes
offline, it will be the PE to which the session was
switched.
RunVprocNo
SMALLINT
Vproc number of the AMP or PE currently assigned to
process the session requests.
For sessions in Teradata SQL partitions, this value is
identical to the LogonPENo. For sessions in FastLoad
or MultiLoad partitions, this is the AMP that initially
processes the data being loaded. For HUTPARSE or
HUTCTL (archive/recovery) sessions, this value is
NULL.
If a RunVprocNo value of -1 in record mode or NULL
in indicator mode is returned by MONITOR
SESSION for FastLoad, MultiLoad or FastExport
sessions, this indicates that the session is in the process
of starting up.
SessionNo
INTEGER,
NOT NULL
Number of the current session. Together with a given
host ID, a session number uniquely identifies a session
on the Teradata Database system. This value is
assigned by the host (or client) at logon time.
UserName
VARCHAR (30),
NOT NULL
User name of the session. This is the name specified
when the user is created; it is used to log on to a
session. Within Teradata Database, user name is
almost equivalent to database name.
Application Programming Reference
109
Chapter 4: System PMPC APIs
MONITOR SESSION
Field Name
Data Type
Description
UserAccount
VARCHAR (30),
NOT NULL
Account currently with which the user is logged on.
When a user is created or altered, that user is allowed
to run in association with one or more accounts.
During the logon process, a particular user session
establishes its priority and charges resource usage to
one of the allowed accounts.
UserID
INTEGER,
NOT NULL
User or internal ID of a user for this session. Within
the Teradata Database, UserID is equivalent to
Database ID. Typically, UserID is used when the
associated record is known to be a user name, and
Database ID is used when the associated record is
known to be a database. However, UserID can identify
either a given user or database name.
LSN
INTEGER,
NOT NULL
Logon Sequence Number (LSN) that is associated
with a session when the session logs on. It identifies a
collection of sessions performing a related activity. For
example, in a FastLoad job, a user is logged on as a
Teradata SQL session, as well as n FastLoad sessions
with the same user name. Therefore, n+1 sessions (1
Teradata SQL and n FastLoad) with the same LSN are
all associated with the given FastLoad job. To see how
the FastLoad job is doing, the user can pick out all
sessions reported with the same LSN number.
Note: This information supplies the parent-child
relationship for sessions involved with FastLoad,
MultiLoad, and Archive/Recovery jobs.
110
LogonTime
FLOAT,
NOT NULL
Time portion of the information recorded by Session
Control when a session successfully logs on. Together
with LogonDate, it indicates when the session logged
on to the system. It is usually formatted for display as
99:99:99, which represents hours: minutes: seconds.
LogonDate
DATE,
NOT NULL
Date portion of the information recorded by Session
Control when a session successfully logs on. Together
with LogonTime, it indicates when the session logged
on to the system.
PartName
VARCHAR (16),
NOT NULL
Name of the session partition associated with this
session. Following a successful logon request by a
session or as part of a connect request, the session
identifies the partition with which the user wants the
session to be associated. FASTLOAD, Teradata SQL,
MONITOR, INTERNAL are examples of valid
partition names.
Reserved2
VARCHAR (2)
Note: This field is not currently used.
Application Programming Reference
Chapter 4: System PMPC APIs
MONITOR SESSION
Field Name
Data Type
Description
PEState
VARCHAR (18)
Current state of the session within the PE. This session
describes PARSING, DISPATCHING, and Monitor
activity. The session states are reported in decreasing
priority:
• DELAYED: The request is either waiting on a
queue table for rows to be inserted in to that table
or, because of a Teradata ASM System Throttle and
Session Control rule, the request is on the Teradata
dynamic workload management software delay
queue. See Teradata Viewpoint User Guide for
information on this rule.
• HOST-RESTART: A restart is in progress for the
associated host (or client).
• ABORTING: The transaction is being rolled back;
the session is aborting.
• PARSING-WAIT: Waiting for information from
the Data Dictionary.
• PARSING: The Parser portion of the PE is
processing a request.
• ELICIT CLIENT DATA: The Dispatcher is eliciting
data from the client and sending it to the AMP.
• DISPATCHING: The Dispatcher or Monitor is
having a request executed.
• BLOCKED: Some background activity is in
progress and the last request is on hold until this
background activity is completed.
• ACTIVE: Normal, on-going activity is being done
by this session.
• RESPONSE: The Dispatcher is returning query
responses to the session.
• IDLE: IN-DOUBT: A session using Two-Phase
Commit (2PC) is currently IN-DOUBT.
• IDLE: No work in progress for this session.
• QTDELAYED: A session is delayed due to a Queue
Table restriction.
• SESDELAYED: A utility session is on the Teradata
dynamic workload management software delay
queue.
• UNKNOWN: The Parser, Dispatcher, and Monitor
on the PE are unaware of this session.
This value is NULL when a request for data is made
before completion of the first collection period that
follows either a system outage or a change in the
ResMonitor rate.
Application Programming Reference
111
Chapter 4: System PMPC APIs
MONITOR SESSION
Field Name
Data Type
Description
PECPUsec
FLOAT
CPU time, in seconds, used in a PE by the associated
session for parsing and dispatching requests. It is
accurate to the second.
This value is valid only when associated with Teradata
SQL and MONITOR partition sessions.
This value is NULL when it is returned for all other
sessions.
XActCount
FLOAT
Number of explicit and implicit transactions executed
by the session.
This value is valid only when returned for Teradata
SQL sessions, and is NULL for all other partition
sessions. For this value, you must make a request for
data before completion of the first collection period
that follows either a system outage or a change in the
ResMonitor rate.
ReqCount
FLOAT
Number of requests (Tequel Start Request [TSR]
messages) initiated by the session.
This value is NULL when a request for data is made
before completion of the first collection period
following either a system outage or change in the
ResMonitor rate.
ReqCacheHits
FLOAT
Number of times that this session processed a request
using information from the Teradata SQL Parser
request cache, specifically, how many times there was a
request cache hit.
This value is valid only for Teradata SQL sessions, and
is NULL for all other partition sessions. This value is
also NULL when a request for data is made before
completion of the first collection period following
either a system outage or a change in the ResMonitor
rate.
112
Application Programming Reference
Chapter 4: System PMPC APIs
MONITOR SESSION
Field Name
Data Type
Description
AMPState
VARCHAR (18)
Current state of the associated session in AMP vprocs
in decreasing priority:
• ABORTING: The transaction is being rolled back;
session is aborting.
• BLOCKED: Some background activity is in
progress and the last request is on hold until this
background activity is completed.
• ACTIVE: Normal, on-going activity is being done
by this session.
• IDLE: No work in progress for this session on any
AMP.
• UNKNOWN: No recorded activity by this session
since monitoring began.
This value is NULL when a request for data is made
before completion of the first collection period
following either a system outage or a change in the
SesMonitorLoc or SesMonitorSys rate.
AMPCPUSec
FLOAT
Current elapsed CPU time, in seconds, used on all
AMPs by the associated session for executing requests.
For example, for Teradata SQL requests, this is the
time spent by the Teradata Database actively working
or rolling back an aborted transaction. This does not
include any PDE CPU time spent handling Teradata
Database requests.
This value is NULL when a request for data is made
before completion of the first collection period
following either a system outage or a change in the
ResMonitor rate.
AMPIO
FLOAT
Current number of logical Reads and Writes issued
across all AMPs by the associated session.
This value is NULL when a request for data is made
before completion of the first collection period
following either a system outage or a change in the
ResMonitor rate.
Request_AmpSpool
FLOAT
Current spool used by current request across all
AMPs, expressed as a number of bytes.
This value is NULL when a request for data is made
before completion of the first collection period
following either a system outage or a change in the
ResMonitor rate.
Application Programming Reference
113
Chapter 4: System PMPC APIs
MONITOR SESSION
Field Name
Data Type
Description
Blk_1_HostId,
SMALLINT
Logical host ID of a session causing a block. This value
is derived from equating the transactions causing a
Teradata Database lock conflict to the sessions that
issued those transactions. The Blk_x_HostId in
combination with Blk_x_SessNo uniquely identifies
the session that is causing a block.
Blk_2_HostId,
Blk_3_HostId
A valid value is not returned if an inactive Archive/
Recovery job is causing the lock conflict, because no
session is logged in.
This value is NULL if:
• The host ID is not available.
• The session does not have an AMPState of
BLOCKED.
If the Blk_x_HostId, Blk_x_SessNo, and
Blk_x_UserID values all return as NULLs and
AMPState is BLOCKED, a Host Utility (HUT) lock
left over after the session holding the lock was aborted
or logged off. The lock was never released, and no
blocking information is available because the session
no longer exists.
Use the Show Locks utility to obtain the user name
that placed the HUT lock. For more information, see
Utilities.
114
Application Programming Reference
Chapter 4: System PMPC APIs
MONITOR SESSION
Field Name
Data Type
Description
Blk_1_SessNo,
INTEGER
Number of the session causing a block. This value is
derived from associating the transactions causing a
lock conflict to the sessions that issued those
transactions. The Blk_x_SessNo in combination with
Blk_x_HostId uniquely identifies the session causing a
block.
Blk_2_SessNo,
Blk_3_SessNo
This information is unavailable if an inactive Archive/
Recovery job is causing the lock conflict.
This value is NULL if:
• SessNo is not available.
• Session does not have an AMPState of BLOCKED.
• A request for data is made before completion of the
first collection period following either a system
outage or a change in the SesMonitorLoc or
SesMonitorSys rate.
If the Blk_x_HostId, Blk_x_SessNo, and
Blk_x_UserID values all return as NULLs and
AMPState is BLOCKED, a host utility lock left over
after the session holding the lock was aborted or
logged off. The lock was never released, and no
blocking information is available because the session
no longer exists.
Use the Show Locks utility to obtain the user name
that placed the HUT lock. For more information, see
Utilities.
Blk_1_UserID,
Blk_2_UserID,
Blk_3_UserID
INTEGER
ID of the user or host utility job preventing the session
from being granted a lock. This information is
especially important when an Archive/Recovery job is
holding the lock, because the user ID is the only
information available about who placed the lock.
This value is NULL if:
• Session does not have an AMPState of BLOCKED.
• A request for data is made before completion of the
first collection period following either a system
outage or a change in the SesMonitorLoc or
SesMonitorSys rate.
If the Blk_x_HostId, Blk_x_SessNo, and
Blk_x_UserID values all return as NULLs and
AMPState is BLOCKED, a host utility lock left over
after the session holding the lock was aborted or
logged off. The lock was never released, and no
blocking information is available because the session
no longer exists.
Use the Show Locks utility to obtain the user name
that placed the HUT lock. For more information, see
Utilities.
Application Programming Reference
115
Chapter 4: System PMPC APIs
MONITOR SESSION
Field Name
Data Type
Description
Blk_1_LMode,
VARCHAR (1)
Mode (severity) of the lock involved in causing a
block:
Blk_2_LMode,
• E = Exclusive
• W = Write
• R = Read
• A = Access
Locks are reported in decreasing order of severity
because removing the most severe lock conflict may
eliminate the source of the lock conflict.
Blk_3_LMode
This value is NULL if:
• The session does not have an AMPState of
BLOCKED.
• A request for data is made before completion of the
first collection period following either a system
outage or a change in the SesMonitorLoc or
SesMonitorSys rate.
A session may be blocked by either a granted lock or
an ungranted lock that precedes the blocked lock in
the queue and is in conflict with the lock requested by
this blocked session. For information on whether the
lock is granted, see the MONITOR SESSSION fields:
Blk_1_Status, Blk_2_Status, and Blk_3_Status.
Blk_1_OType,
Blk_2_OType,
Blk_3_OType
VARCHAR (1)
Type of object whose lock is causing the session
described by the associated row to be blocked:
• D = Database
• T= Table
• R = Row hash
However, this object is not necessarily the type of
object the blocked session is trying to access. For
example, if the session is requesting a row hash lock,
the blocking object could be a database, table, or row
hash.
This value is NULL if:
• Session does not have an AMPState of BLOCKED.
• A request for data is made before completion of the
first collection period following either a system
outage or a change in the SesMonitorLoc or
SesMonitorSys rate.
For a Table T, it is possible for User A to block User B
with a table level lock on Table T on AMP_1 and with
a Row Hash Level lock on that same Table T on
AMP_2. When that occurs, the only lock conflict
reported is that User B is blocked by User A on a table.
116
Application Programming Reference
Chapter 4: System PMPC APIs
MONITOR SESSION
Field Name
Data Type
Description
Blk_1_ObjDBId,
INTEGER
Unique ID of the database object over which a lock
conflict is preventing the session from being granted a
lock.
Blk_2_ObjDBId,
Blk_3_ObjDBId
Within the Teradata Database system, Database ID is
equivalent to User ID. Typically, User ID is used when
the associated record is known to be a user name, and
Database ID is used when the associated record is
known to be a database. However, Database ID can
identify either a user or database name.
This value is NULL if:
• The session does not have an AMPState of
BLOCKED.
• A request for data is made before completion of the
first collection period following either a system
outage or a change in the SesMonitorLoc or
SesMonitorSys rate.
Blk_1_ObjTId,
INTEGER
Blk_2_ObjTId,
Blk_3_ObjTId
Unique ID of the table object over which a lock
conflict is preventing the session from being granted a
lock.
This value is NULL if:
• The session does not have an AMPState of
BLOCKED.
• The Blk_x_OType is D.
• A request for data is made before completion of the
first collection period following either a system
outage or a change in the SesMonitorLoc or
SesMonitorSys rate.
Blk_1_Status,
Blk_2_Status,
Blk_3_Status
VARCHAR (1)
Status of lock causing a block:
• W= Waiting
• G = Granted
This value is NULL if:
• Session does not have an AMPState of BLOCKED.
• A request for data is made before completion of the
first collection period following either a system
outage or a change in the SesMonitorLoc or
SesMonitorSys rate.
Note: A lock request may be blocked by either a
granted lock or an ungranted lock that precedes the
blocked lock request in the queue and is in conflict
with it.
A status of Waiting has a higher priority than that of
Granted when there is more than one lock involved.
For example, for a given object and a given session, a
session that is blocked by a Waiting lock on one AMP
and a Granted lock on another AMP has Waiting
reported as its status.
Application Programming Reference
117
Chapter 4: System PMPC APIs
MONITOR SESSION
Field Name
Data Type
Description
MoreBlockers
VARCHAR (1)
Indicator of more lock conflicts:
• Blank = Blk_x information is a complete list of
sessions blocking the session described.
• Asterisk (*) = additional sessions are blocking the
session described. The Blk_x information shows
only three blocking sessions.
This value is NULL if:
• The state of the session is not BLOCKED.
• A request for data is made before completion of the
first collection period following either a system
outage or a change in the SesMonitorLoc or
SesMonitorSys rate.
LogonSource
VARCHAR (128)
Logon source information. At logon time, this
information is optionally supplied by the Teradata
Director Program or the LAN Gateway to further
identify the physical or logical location of the session,
the logon user name, and the interface under which
the session was initiated. (For example, the data string
may include DBC as the user ID and BTEQ as the
interface.)
Data strings for TCP/IP sessions are inserted by
CLIv2, which truncates strings that exceed 128 bytes.
Note: A two-byte value precedes the LogonSource
data to indicate the length of the string. The length
value is zero if LogonSource is NULL.
For a list of the commonly seen LogonSource string
application names, see SQL Data Definition Language.
TempSpace
FLOAT
Total amount, in bytes, of temporary space used by the
session.
This value is NULL if the session did not materialize
any temporary tables.
Group II Data Fields
The Record parcel returns the following Group II data values.
Note: The values are NULL if the request is made before the collection period expires.
Field Name
Data Type
Description
HotAmp1CPU
FLOAT
CPU time of the highest CPU utilized
AMP during the collection interval.
This value is NULL if the request is made
before the collection period expires.
118
Application Programming Reference
Chapter 4: System PMPC APIs
MONITOR SESSION
Field Name
Data Type
Description
HotAmp2CPU
FLOAT
CPU time of the second highest CPU
utilized AMP during the collection
interval.
This value is NULL if the request is made
before the collection period expires.
HotAmp3CPU
FLOAT
CPU time of the third highest CPU
utilized AMP during the collection
interval.
This value is NULL if the request is made
before the collection period expires, and if
there are only two AMPs on the system.
HotAmp1IO
FLOAT
IO count of the highest IO utilized AMP
during the collection interval.
This value is NULL if the request is made
before the collection period expires.
HotAmp2IO
FLOAT
IO count of the second highest IO utilized
AMP during the collection interval.
This value is NULL if the request is made
before the collection period expires.
HotAmp3IO
FLOAT
IO count of the third highest IO utilized
AMP for the last collection interval.
This value is NULL if the request is made
before the collection period expires, and if
there are only two AMPs in the system.
HotAmp1CPUId
SMALLINT
Vproc ID of the highest CPU utilized
AMP for the last session collection
interval.
This value is NULL if the request is made
before the collection period expires.
HotAmp2CPUId
SMALLINT
Vproc ID of the second highest CPU
utilized AMP for the last session collection
interval.
This value is NULL if the request is made
before the collection period expires.
HotAmp3CPUId
SMALLINT
Vproc ID of the third highest CPU utilized
AMP for the last session collection
interval.
This value is NULL if the request is made
before the collection period expires, and if
there are only two AMPs in the system.
Application Programming Reference
119
Chapter 4: System PMPC APIs
MONITOR SESSION
Field Name
Data Type
Description
HotAmp1IOId
SMALLINT
Vproc ID of the highest IO utilized AMP
for the last session collection interval.
This value is NULL if the request is made
before the collection period expires.
HotAmp2IOId
SMALLINT
Vproc ID of the second highest IO utilized
AMP for the last session collection
interval.
This value is NULL if the request is made
before the collection period expires.
HotAmp3IOId
SMALLINT
Vproc ID of the third highest IO utilized
AMP for the last session collection
interval.
This value is NULL if the request is made
before the collection period expires, and if
there are only two AMPs in the system.
LowAmp1CPU
FLOAT
CPU time of the lowest CPU utilized AMP
during the collection interval.
This value is NULL if the request is made
before the collection period expires.
LowAmp2CPU
FLOAT
CPU time of the second lowest CPU
utilized AMP during the collection
interval.
This value is NULL if the request is made
before the collection period expires.
LowAmp3CPU
FLOAT
CPU time of the third lowest CPU utilized
AMP during the collection interval.
This value is NULL if the request is made
before the collection period expires, and if
there are only two AMPs on the system.
LowAmp1IO
FLOAT
IO count of the lowest IO utilized AMP
during the collection interval.
This value is NULL if the request is made
before the collection period expires.
LowAmp2IO
FLOAT
IO count of the second lowest IO utilized
AMP during the collection interval.
This value is NULL if the request is made
before the collection period expires.
LowAmp3IO
FLOAT
IO count of the third lowest IO utilized
AMP during the collection interval.
This value is NULL if the request is made
before the collection period expires, and if
there are only two AMPs on the system.
120
Application Programming Reference
Chapter 4: System PMPC APIs
MONITOR SESSION
Field Name
Data Type
Description
LowAmp1CPUId
SMALLINT
Vproc ID of the lowest CPU utilized AMP
for the last session collection interval.
This value is NULL if the request is made
before the collection period expires.
LowAmp2CPUId
SMALLINT
Vproc ID of the second lowest CPU
utilized AMP for the last session collection
interval.
This value is NULL if the request is made
before the collection period expires.
LowAmp3CPUId
SMALLINT
Vproc ID of the third lowest CPU utilized
AMP for the last session collection
interval.
This value is NULL if the request is made
before the collection period expires, and if
there are only two AMPs on the system.
LowAmp1IOId
SMALLINT
Vproc ID of the lowest IO utilized AMP
for the last session collection interval.
This value is NULL if the request is made
before the collection period expires.
LowAmp2IOId
SMALLINT
Vproc ID of the second lowest IO utilized
AMP for the last session collection
interval.
This value is NULL if the request is made
before the collection period expires.
LowAmp3IOId
SMALLINT
Vproc ID of the third lowest IO utilized
AMP for the last session collection
interval.
This value is NULL if the request is made
before the collection period expires, and if
there are only two AMPs on the system.
UpAMPCount
SMALLINT
Total number of AMPs participating for
this session during the last session
collection interval.
This value is NULL if the request is made
before the collection period expires.
Application Programming Reference
121
Chapter 4: System PMPC APIs
MONITOR SESSION
Field Name
Data Type
Description
AvgAmpCPUSec
FLOAT
Average AMP CPU utilization for the last
session collection interval. The average is
calculated as the sum of CPU utilization
for all AMPs participating divided by the
number of online AMPs.
This value is NULL if the request is made
before the collection period expires.
AvgAmpIOCnt
FLOAT
Average AMP IO utilization for the last
session collection interval. The average is
calculated as the sum of IO utilization for
all AMPs participating divided by the
number of online AMPs.
This value is NULL if the request is made
before the collection period expires.
Group III Data Fields
The Record parcel returns the following Group III data values.
Field Name
Data Type
Description
RequestStartTime
FLOAT
Time of the current request on the session started.
RequestStartDate
DATE
Date of the current request on the session started.
RequestAmpCPU
FLOAT
Total CPU usage by the current SQL request on the
session on all AMPs. This value contains proper requestlevel statistics for DBC/SQL sessions running SQL
requests only. Ignore the value returned in this field for
other types of sessions, such as DBC/SQL sessions linked
to a utility job.
This field is equivalent to the MonitorSession ReqCPU
field.
RequestAmpI/O
FLOAT
Total number of accesses by the current SQL request on
the session on all AMPs.
This value contains proper request-level statistics for
DBC/SQL sessions running SQL requests only. Ignore
the value returned in this field for other types of
sessions, such as DBC/SQL sessions linked to a utility
job.
This field is equivalent to the MonitorSession ReqIO
field.
Group IV Data Fields
The Record parcel returns the following Group IV data values.
122
Application Programming Reference
Chapter 4: System PMPC APIs
MONITOR SESSION
Field Name
Data Type
Description
Request Number
INTEGER
Active request number.
If no request is running, then a value of zero or NULL
is displayed in indicator mode.
WDId
INTEGER
Workload ID associated with the specified request.
Classification Mode
SMALLINT
Indicator if a running query or session is (or any
future queries will be) forced into a WD or not.
The classification mode is valid only for DBC/SQL
sessions and if the Teradata dynamic workload
management software is enabled. If the Teradata
dynamic workload management software is enabled, it
classifies all incoming queries into a WD.
If the Teradata dynamic workload management
software is enabled, the value is one of the following:
• 0 = Automatic
• 1 = Manual at Request Level
• 2 = Manual at Session Level
If the Teradata dynamic workload management
software is disabled and the DBC/SQL session is not a
valid session, the value is 255 or NULL.
Group V Data Field
The Record parcel returns the following Group V data value.
Field Name
Data Type
Description
ProxyUser
VARCHAR (30)
Name of the proxy user if the session has a
proxy connection.
Group VI Data Fields
The Record parcel returns the following Group VI data values.
Field Name
Data Type
Description
CPUDecayLevel
SMALLINT
Current most severe decay level as reached
due to CPU usage.
Note: Nodes can be at different levels of
decay (for example, 0, 1, or 2).
IODecayLevel
SMALLINT
Current most severe decay level as reached
due to I/O usage.
Note: Nodes can be at different levels of
decay (for example, 0, 1, or 2).
Application Programming Reference
123
Chapter 4: System PMPC APIs
MONITOR SESSION
Field Name
Data Type
Description
TacticalCPUException
INTEGER
Number of nodes that encountered a CPU
exception.
TacticalIOException
INTEGER
Number of nodes that encountered an I/O
exception.
ReqIOKB
FLOAT
Total logical I/O usage in KB.
ReqPhysIO
FLOAT
Number of physical I/Os.
ReqPhysIOKB
FLOAT
Physical I/O usage in KB.
ReqStepsCompletedCnt
INTEGER
Count of completed steps for the current
request. No change in the
ReqStepsCompletedCnt field from the
previous Monitor Session collection
indicates no new steps completed.
CurrentRedriveParticipation
VARCHAR (1)
Note: This field is reserved for future use.
ReqPersistentSpoolSpace
FLOAT
Note: This field is reserved for future use.
Sample Input
This example shows how the parcels for a MONITOR SESSION request, built by CLIv2,
appear when sent to the Teradata Database server using a host_id of 387, a session_no of 1098,
and a user_name of WEEKLY. In this example, the size of the response buffer is set at the
maximum (64,000 bytes), although you can set it to any size. However, a minimum response
size is 32,000 bytes.
Flavor
Length
Body
Num
Name
Bytes
Field
Value
0001
Req
19
Request
MONITOR SESSION
0003
Data
42
MonVerID
9
HostId
387
SessionNo
1098
UserName
WEEKLY
BufferSize
64000
0004
Resp
6
Sample Output
The following example shows the values returned for a mon_ver_ID setting of 9, which
includes Group I through Group VI data fields.
Pay attention to SessionRate when interpreting the results of this request.
124
Application Programming Reference
Chapter 4: System PMPC APIs
MONITOR SESSION
Example: mon_ver_id=9 (Returns Group I Through VI Data Fields)
Success parcel:
StatementNo=1,
ActivityType=84,
ActivityCount=1,
FieldCount=9
CollectionInterval:
Collection Seq Number:
Collection Date/Time:
SessionRate:
ExceptionInterval:
SessionRateThreshold:
DBQLFlushRate:
RedriveProtection:
EndStatement.
Success parcel:
StatementNo=2,
ActivityType=84,
HostId:
1
LogonPENo: 16383
PartName: DBC/SQL
7 seconds
61
06/15/2011 18:21:43.00
1 seconds
120 seconds
0 seconds
600 seconds
[]
ActivityCount=-1,
FieldCount=93
SessionNo: 1004
RunVprocNo: 16383
PEState:
DISPATCHING
LogonDate/Time: 06/15/2011 18:15:26.00
UserID: 1018 LSN: 0
UserName: JCK
UserAccount: DBC
PECPUSec:
ReqCount:
0.05
3.0
XactCount:
ReqCacheHits:
1.00
0.0
AMPState: ACTIVE
AMPCPUSec:
375.42
AMPIO: 178519.00
Request_AMPSpool: 22360919040.0
Blk_1_HostId:
Blk_1_SessNo:
Blk_1_UserID:
Blk_1_LMode:
Blk_1_OType:
Blk_1_ObjDBId:
Blk_1_ObjTId:
Blk_1_Status:
MoreBlockers:
0
0
0
Blk_2_HostId:
Blk_2_SessNo:
Blk_2_UserID:
Blk_2_LMode:
Blk_2_OType:
0
Blk_2_ObjDBId:
0
Blk_2_ObjTId:
Blk_2_Status:
0
Blk_3_HostId:
0
Blk_3_SessNo:
0
Blk_3_UserID:
Blk_3_LMode:
Blk_3_OType:
0
Blk_3_ObjDBId:
0
Blk_3_ObjTId:
Blk_3_Status:
LogonSource: (TCP/IP) 0a87 141.206.34.113 LONGSQL
LSS
HotAmp1CPU:
HotAmp1CPUId:
HotAmp1IO:
HotAmp1IOId:
LowAmp1CPU:
1.75
3
816.00
2
1.70
Application Programming Reference
HotAmp2CPU:
HotAmp2CPUId:
HotAmp2IO:
HotAmp2IOId:
LowAmp2CPU:
1.74
0
816.00
0
1.72
29968
HotAmp3CPU:
HotAmp3CPUId:
HotAmp3IO:
HotAmp3IOId:
LowAmp3CPU:
0
0
0
0
0
JK121219
BTEQ
01
1.72
2
813.00
1
1.74
125
Chapter 4: System PMPC APIs
MONITOR SESSION
LowAmp1CPUId:
LowAmp1IO:
LowAmp1IOId:
1
LowAmp2CPUId:
2
810.00
3
LowAmp2IO:
LowAmp2IOId:
813.00
1
AvgAmpCPUSec:
AmpCount:
1.73
4
AvgAmpIOCnt:
813.75
TempSpaceUsg:
0.00
LowAmp3CPUId:
LowAmp3IO:
LowAmp3IOId:
0
816.00
2
ReqStartTime: 06/15/2011 18:15:26.00
ReqCPU:
375.41 ReqIO: 178515.00
ReqNo:4
WlcId: 12
DontReclassifyFlag: 0
ProxyUser:
CPUDecayLevel=1,
IODecayLevel=2,
TacticalCPUException=0, TacticalIOException=0
ReqIOKB=89257.50, ReqPhysIO=13320, ReqPhysIOKB=477284
ReqStepsCompletedCnt=9
CurrentRedriveParticipation=[]
ReqPersistentSpoolSpace=0.00
EndStatement.
Relationship Between MONITOR SESSION and ABORT SESSION
When sessions are being aborted or sessions are being blocked by the sessions being aborted,
data returned from subsequent MONITOR SESSION queries may be affected. After the abort
operation starts, you can immediately notice the changes from aborting sessions. However,
you will not notice the changes resulting from sessions that were blocked by aborting sessions
in MONITOR SESSION responses until the abort operation is complete.
For information on this PMPC CLIv2 request relationship, see “Relationship Between ABORT
SESSION and MONITOR SESSION” on page 58.
Relationship Between MONITOR SESSION and IDENTIFY
PM/API can report on locks placed by any user or object with the MONITOR SESSION and
IDENTIFY requests. The MONITOR SESSION request helps you identify the types of locks
blocking a session.
For information on this PMPC CLIv2 request relationship, see “Relationship Between
IDENTIFY and MONITOR SESSION” on page 66.
Relationship Between MONITOR SESSION and SET SESSION RATE
You must execute the SET SESSION RATE request to activate session-level data collection
before you execute a MONITOR SESSION request. This means that either the global rate or
local rate must be set to nonzero. If both rates are set to zero, an error message is returned.
A change in the global session rate may affect the data reported by a MONITOR SESSION
request. Specifically, if User A makes a change in the global rate, this change could affect the
viewing for User B of displayed data from a MONITOR SESSION request. Unless User B is
126
Application Programming Reference
Chapter 4: System PMPC APIs
MONITOR SESSION
aware of the rate change, User B may draw incorrect conclusions from the observed data. In
this case, User B receives a warning message when executing a MONITOR SESSION request.
Example
The following example is a single user on a system that uses the SET SESSION RATE and
MONITOR SESSION requests.
1
User Morris uses the SET SESSION RATE request to set a session-level global rate of 600
seconds (or 10 minutes) at 9:00 a.m. The data time-stamp was set at 9:00 a.m. because that
was the last time data was requested.
2
Morris then uses the SET SESSION RATE request to set a session-level local rate of 300
seconds (5 minutes) at 9:05 a.m. Morris does not make a request for data at this time.
Therefore, the time-stamp is still set at 9:00 a.m.
3
Morris executes a MONITOR SESSION request at 9:08 a.m. for host_id of 510 and a
session_no of 1000:
MONITOR SESSION 2 510 1000
4
A collection occurs because the “current” data was not considered current (that is, the age
of the data is greater than the session collection rate). The system calculates that 9:08 a.m.
(current time) - 9:00 a.m. (time-stamp) = 8 minutes, which is the age of the data. The 8
minutes is greater than 5 minutes, which is the local collection rate. Because of the forced
update, Morris receives 8 minutes of data (from 9:00 a.m. to 9:08 a.m.), and the timestamp is reset to 9:08 a.m.
5
At 9:10 a.m., Morris decides to make another MONITOR SESSION request. This time, no
collection occurs, because the “current” available data was considered current. The system
calculates that 9:10 a.m. (current time) - 9:08 a.m. (time-stamp) = 2 minutes (age of the
data), which is less than 5 minutes (local collection rate). This means that the current data
available is considered current, because no data update to the session-level memory
repository occurs. Morris gets the same data that was returned at 9:08 a.m.
Two other events can cause data to be collected:
Event
Comments
A default system timer of 10 minutes has
elapsed without a request from a user.
Whenever 10 minutes has expired without a collection,
the system timer causes a default collection to occur.
This causes data in the main memory repository to be
updated, even if no request is made.
When the AMP Session Cache is full
A full AMP Session Cache forces an update of data in
the main memory repository. This is a rare occurrence.
Application Programming Reference
127
Chapter 4: System PMPC APIs
MONITOR SQL
MONITOR SQL
Purpose
Returns the step information (that is, a scaled-down version of the output of the EXPLAIN
request modifier) of the current or running request for the specified host, session, and vproc.
Input Data
Element
Data Type
Description
IndByte
BYTE
Indicator bits that specify which fields to treat as NULL if
you are using indicator mode.
Each bit in the byte corresponds to one field in the input
data.
If data is supplied for that field, then set the bit to zero.
If the data for that field is NULL (that is, there is no data
supplied for that field), then set the bit to 1.
Note: The IndByte field is only required if the PM/API
request is submitted in indicator mode.
mon_ver_id
SMALLINT,
NOT NULL
MONITOR software version ID. This can be version 3 or
later.
For a general explanation of monitor version choices, see
“MONITOR VERSION” on page 136.
host_id
SMALLINT,
NOT NULL
Logical ID of a host (or client) with sessions logged on.
host_id cannot exceed 1023 bytes. A host _id of zero
identifies the system console ID of the host on which the
sessions are running.
session_no
INTEGER,
NOT NULL
Session number. The session number combined with the
host_id represents a unique session ID.
RunPEVprocNo
SMALLINT,
NOT NULL
PE vproc number where the session runs. This is typically
obtained from the MONITOR SESSION response of the
RunVprocNo field. See the MONITOR SESSION
RunVprocNo field for more information.
Monitor Privileges
To use this request, you must have the MONSESSION privilege as part of your default role or
this privilege must be granted directly to you.
For more information on roles and privileges, see Database Administration and Security
Administration.
128
Application Programming Reference
Chapter 4: System PMPC APIs
MONITOR SQL
Usage Notes
When issuing a MONITOR SQL request, you must specify a minimum buffer size of 32,007
bytes or more. For some custom applications, an error message may appear.
The MONITOR SQL request can be used in the following ways:
•
A problematic query is utilizing a large amount of system resources. Use of this feature
provides the associated SQL text to the system administrator to help identify possible
bottlenecks, hardware problems and bugs. The query text and DDL statements can also be
forwarded to Teradata Support Center for help in diagnosing the problem.
•
The information provided by this request can help to identify specific SQL problems, such
as poorly structured tables and indexes.
•
Problems can even be traced down to the individual step within a query.
The MONITOR SQL request may not be used on internal sessions or sessions that are logged
onto the monitor. Request text and steps text are not stored for these types of sessions, and if
an attempt is made to query one of them, an error is returned indicating that it is not an SQL
session.
Abort processing is handled in the same way as when using the MONITOR SESSION request.
For further information about abort handling, see “MONITOR SESSION” on page 101.
If MONITOR SQL processing is not completed within the timeout interval, then an error is
returned to the client application. When a MONITOR SQL request is timed out, the
processing continues internally to its completion. If the client application submits a new
MONITOR SQL request for the same timed out target session while the previous timed out
one is still being processed, then an error is returned.
The timeout interval can be set in the DBS Control field, PMPC_TimeoutSecs. The default
timeout interval is 60 seconds. If the PMPC_TimeoutSecs field is set to zero, the MONITOR
SQL timeout request will be disabled and no timeout will occur. For more information on the
PMPC_TimeoutSecs field, see Utilities.
MONITOR SQL is most useful when used with the MONITOR VIRTUAL SUMMARY
request for doing a quick overall system health check. For more information, see
“Relationship Between MONITOR VIRTUAL CONFIG and MONITOR VIRTUAL
SUMMARY” on page 145.
Parcels
The MONITOR SQL request is treated internally as a three statement request with each
statement generating a response. The three-statement response returned from Teradata
Database contains the following sequence of parcel types:
Application Programming Reference
129
Chapter 4: System PMPC APIs
MONITOR SQL
Parcel
Sequence
Parcel
Flavor
Length
(Bytes)
Comments/Key Parcel Body Fields
Success
8
18 to 273
StatementNo = 1
ActivityCount = 1
ActivityType = 110 (PCLMONSQL)
DataInfo
71
6 to 64100
Optional; this parcel is present if request was
IndicData parcel.
Record
10
• 5 to 64100
(record
mode)
• 6 to 64100
(indicator
mode)
Depending on request (Data or IndicData), data
is in record or indicator mode. This record
contains the text of the SQL request (see
“Statement Type: 1” on page 131).
EndStatement
11
6
StatementNo = 2-byte integer
Success
8
18 to 273
StatementNo = 2
ActivityCount = 1
ActivityType = 107 (PCLMONSQL)
DataInfo
71
6 to 64100
Optional; this parcel is present if request was
IndicData parcel.
Record
10
• 5 to 64100
(record
mode)
• 6 to 64100
(indicator
mode)
Depending on request (Data or IndicData), data
is in record or indicator mode. This record
contains step count information (see “Statement
Type: 2” on page 131).
EndStatement
11
6
StatementNo = 2-byte integer
Success
8
18 to 273
StatementNo = 3
ActivityCount = Number of EXPLAIN steps
ActivityType = 110 (PCLMONSQL)
130
Datainfo
71
6 to 64100
Optional; this parcel is present if request was
IndicData parcel.
Record
10
• 5 to 64100
(record
mode)
• 6 to 64100
(indicator
mode)
Depending on request (Data or IndicData), data
is in record or indicator mode. Each record
contains step resource information (see
“Statement Type: 3” on page 131).
EndStatement
11
6
StatementNo = 2-byte integer
EndRequest
12
4
None
Application Programming Reference
Chapter 4: System PMPC APIs
MONITOR SQL
Statement Type: 1
The response to the first statement results in a Record parcel that contains the SQL request
text.
Field Name
Data Type
Description
RequestText
VARCHAR
(64000)
Actual SQL request for a specified session.
Note: If RequestText is 64001 bytes or greater in length, it
will automatically split into multiple records
Statement Type: 2
The response to the second statement returns information regarding the total number of steps
and which steps are currently executing.
Field Name
Data Type
Description
NumOfSteps
SMALLINT,
NOT NULL
Number of steps contained in the description text.
CurLev1StepNum
SMALLINT,
NOT NULL
Number of the currently executing level 1 step.
CurLev2StepNum
SMALLINT,
NOT NULL
Number of the currently executing level 2 or parallel step.
Note: If only one step is executing, then CurLevlStepNum and CurLEv2StepNum will be
identical.
Statement Type: 3
The response to the third statement returns a Record parcel that contains the step text for a
given request. Each step returns a separate row. This parcel description has changed from the
version 3 parcel. The response parcel received is contingent on whether you set mon_ver_id 3
or mon_ver_id 4. The values returned vary in format and content depending on the value of
mon_ver_id used.
If mon_ver_id 3 is set, then the response to the third statement returns a Record parcel that
contains the following steps text for a given request.
Field Name
Data Type
Description
StepNum
SMALLINT,
NOT NULL
Unique number identifying the EXPLAIN step.
StepText
VARCHAR (1024),
NOT NULL
Generated text of the step.
Application Programming Reference
131
Chapter 4: System PMPC APIs
MONITOR SQL
If mon_ver_id 4 is set, then the response to the third statement returns a Record parcel that
contains the following steps text for a given request.
Field
Data Type
Description
StepNum
SMALLINT,
NOT NULL
Unique number identifying the EXPLAIN step.
Confidence
SMALLINT,
NOT NULL
Confidence level as determined by the optimizer:
EstRowCount
FLOAT,
NOT NULL
Row count generated from the Optimizer plan.
ActRowCount
FLOAT,
NOT NULL
Row count returned from the AMP for this step.
EstElapTime
FLOAT,
NOT NULL
Estimated time for the query as generated from the
Optimizer plan.
ActElapTime
FLOAT,
NOT NULL
Actual elapsed time calculated by the dispatcher.
StepText
VARCHAR (1024),
NOT NULL
Generated text of the step.
•
•
•
•
0 = None
1= Foreign Key
2 = Low
3 = High
The estimated fields populate immediately. The low value supplied by the optimizer will be
used. The actual fields will be populated at the same time with a “-1”. After the step executes,
the actual values (or a zero for those kinds of steps with no row count) will be placed in the
actual fields to identify those steps that have been executed at the time of the API information
capture.
Sample Input
This example shows how the parcels for a MONITOR SQL request built by CLIv2 appear
when sent to the Teradata Database server. In this example, the size of the response buffer is
set at the maximum (64,000 bytes), although you can set it to any size. However, a minimum
response size is 32,000 bytes.
Flavor
132
Length
Body
Num
Name
Bytes
Field
Value
0001
Req
16
Request
MONITOR SQL
Application Programming Reference
Chapter 4: System PMPC APIs
MONITOR SQL
Flavor
0003
0004
Data
Resp
Length
Body
12
MonVerID
3
HostId
1
SessionNo
1002
RunPEVprocNo
16383
BufferSize
64000
6
Sample Output
This example shows the values returned in character text format for the MONITOR SQL
request. Your application program may display returned values in a different format.
Note: The EXPLAIN steps shown are not as inclusive as those provided by the EXPLAIN
request modifier.
The following is an Explain of a CREATE DATABASE SQL statement. This statement
generates 21 steps. Step 7 has 7 parallel steps. Steps 9 and 11 have 2 parallel steps and step 11
has 3 parallel steps.
Explain CD baseDT1b AS PERM=1E6;
Explanation
----------------------------------------------------------------------1) First, we lock data base baseDT1b for exclusive use.
2) Next, we lock a distinct DBC."pseudo table" for write on a RowHash
to prevent global deadlock for DBC.DataBaseSpace.
3) We lock a distinct DBC."pseudo table" for write on a RowHash to
prevent global deadlock for DBC.AccessRights.
4) We lock a distinct DBC."pseudo table" for write on a RowHash to
prevent global deadlock for DBC.Parents.
5) We lock a distinct DBC."pseudo table" for write on a RowHash to
prevent global deadlock for DBC.Owners.
6) We lock DBC.DataBaseSpace for write, we lock DBC.AccessRights for
write, we lock DBC.Parents for write, we lock DBC.Owners for write,
we lock DBC.Accounts for write on a RowHash, we lock DBC.DBase for
write on a RowHash, and we lock DBC.DBase for write on a RowHash.
7) We execute the following steps in parallel.
1) We do a single-AMP ABORT test from DBC.DBase by way of the
unique primary index with no residual conditions.
2) We do a single-AMP ABORT test from DBC.Roles by way of the
unique primary index with no residual conditions.
3) We do a single-AMP ABORT test from DBC.DBase by way of the
unique primary index.
4) We do a single-AMP ABORT test from DBC.DBase by way of the
unique primary index.
5) We do an INSERT into DBC.DBase.
6) We do a single-AMP UPDATE from DBC.DBase by way of the unique
primary index with no residual conditions.
7) We do a single-AMP RETRIEVE step from DBC.Parents by way of
the primary index with no residual conditions into Spool 1
(all_amps), which is redistributed by hash code to all AMPs.
Then we do a SORT to order Spool 1 by row hash.
8) We do an all-AMPs MERGE into DBC.Owners from Spool 1 (Last Use).
Application Programming Reference
133
Chapter 4: System PMPC APIs
MONITOR SQL
9) We execute the following steps in parallel.
1) We do an INSERT into DBC.Owners.
2) We do a single-AMP RETRIEVE step from DBC.Parents by way of
the primary index with no residual conditions into Spool 2
(all_amps), which is redistributed by hash code to all AMPs.
Then we do a SORT to order Spool 2 by row hash.
10) We do an all-AMPs MERGE into DBC.Parents from Spool 2 (Last Use).
11) We execute the following steps.
1) We do an INSERT into DBC.Parents.
2) We do an INSERT into DBC.Accounts.
3) We do a single-AMP RETRIEVE step from DBC.AccessRights by way
of the primary index into Spool 3 (all_amps), which is
redistributed by hash code to all AMPs.
12) We execute the following steps in parallel.
1) We do a single-AMP RETRIEVE step from DBC.AccessRights by way
of the primary index into Spool 3 (all_amps), which is
redistributed by hash code to all AMPs.
2) We do an all-AMPs RETRIEVE step from DBC.AccessRights by way
of an all-rows scan into Spool 4 (all_amps), which is
redistributed by hash code to all AMPs. Then we do a SORT to
order Spool 4 by row hash.
13) We do an all-AMPs JOIN step from DBC.Owners by way of a RowHash
match scan, which is joined to Spool 4 (Last Use). DBC.Owners and
Spool 4 are joined using a merge join. The result goes into Spool
3 (all_amps), which is redistributed by hash code to all AMPs.
Then we do a SORT to order Spool 3 by row hash.
14) We do an all-AMPs MERGE into DBC.AccessRights from Spool 3 (Last
Use).
15) We flush the DISKSPACE and AMPUSAGE caches.
16) We do an all-AMPs ABORT test from DBC.DataBaseSpace by way of the
unique primary index.
17) We do an INSERT into DBC.DataBaseSpace.
18) We do an all-AMPs UPDATE from DBC.DataBaseSpace by way of the
unique primary index with no residual conditions.
19) We flush the DISKSPACE and AMPUSAGE caches.
20) We spoil the parser's dictionary cache for the database.
21) Finally, we send out an END TRANSACTION step to all AMPs involved
in processing the request.
-> No rows are returned to the user as the result of statement 1.
=======================
The following is the output from a PM/API application capturing the step data of the SQL
statement above.
The first column of numbers is a sequential count of the rows returned from the DBS.
When a step number is repeated in the step number column, it indicates that it is a parallel
step. For instance, in the following example, the step number 7 is repeated 7 times. This
coincides with the 7 parallel steps found for step 7 in the above Explain. Step 9 and 12 have
two entries (they both have 2 parallel steps) and that step 11 is repeated 3 times for its 3
parallel steps. You will also note that the step text itself indicates when a block of parallel steps
begins, that a step is part of a parallel block and when a parallel block of steps ends.
The statement “Currently executing step 24 of 31” refers to the sequential row count and not
the actual step number. The PM/API application highlights the currently active step. You will
note that the data for the currently active step and those following it is blank. The data is only
134
Application Programming Reference
Chapter 4: System PMPC APIs
MONITOR SQL
available after the step completes. Remember that Step text is derived information and not the
true EXPLAIN text.
A sample of a PM/API application output appears as follows:
CD baseDT1b AS PERM=1E6;
Currently executing step 24 of 31 steps
Step
1
2
3
4
5
1
2
3
4
5
Est.
Time
0:00.00
0:00.00
0:00.00
0:00.00
0:00.00
Actual
Time
0:00.00
0:00.01
0:00.00
0:00.01
0:00.11
Est.
IOs
0
0
0
0
0
Actual
IOs
1
1
1
1
1
7
7
0:00.00
0:00.00
0
0
8
7
0:00.00
0:00.00
0
0
9
7
0:00.00
0:00.00
0
0
10 7
0:00.00
0:00.00
0
0
11 7
0:00.00
0:00.00
0
1
12 7
0:00.00
0:00.07
0
1
13 7
0:00.00
0:00.07
0
0
14 8
15 9
0:00.00
0:00.00
0:00.00
0:00.02
0
0
0
1
16 9
0:00.00
0:00.01
0
1
17 10
18 11
0:00.00
0:00.00
0:00.00
0:00.07
0
0
0
1
19 11
0:00.00
0:00.07
0
1
20 11
0:00.00
0:00.01
0
21
21 12
0:00.00
0:00.01
0
17
22 12
0:00.00
0:00.01
0
0
0:00.01
0
17
23 13
0:00.00
24 14
0:00.00
0
25 15
26 16
0:00.00
0:00.00
27 17
28 18
0:00.00
0:00.00
0
0
0
0
0
29 19
30 20
31 21
0:00.00
0:00.00
0:00.00
0
0
0
Application Programming Reference
Step Text
First, lock [DBId=0x0406].for exclusive.
Next, we lock DBC."pseudo table" for write on a row hash.
We lock DBC."pseudo table" for write on a row hash.
We lock DBC."pseudo table" for write on a row hash.
We lock DBC.DBSpace for write, we lock DBC.AccessRights
for write, we lock DBC.Parents for write, we lock
DBC.Owners for write, we lock DBC.Accounts for write on a
row hash, we lock DBC.DBase for write on a row hash and we
lock DBC.DBase for write on a row hash.
We do a Single-AMP ABORT test from DBC.DBase by way of
unique primary index. This step begins a parallel block
of steps.
We do a Single-AMP ABORT test from DBC.[TBId=0x0071] by
way of the unique primary index. This step is performed in
parallel.
We do a Single-AMP ABORT test from DBC.DBase by way of the
unique primary index. This step is performed in parallel.
We do a Single-AMP ABORT test from DBC.DBase by way of the
unique primary index. This step is performed in parallel.
We do an INSERT step into table DBC.DBase. This step is
performed in parallel.
We do a Single-AMP UPDATE from DBC.DBase by way of the
unique primary index. This step is performed in parallel.
We do a Single-AMP RETRIEVE step from DBC.Parents by way
of the primary index into Spool 6345, which is
redistributed by hash code to all AMPs. This step ends
aparallel block of steps.
We do a MERGE into table DBC.Owners from Spool 6345.
We do an INSERT step into table DBC.Owners. This step
begins a parallel block of steps.
We do a Single-AMP RETRIEVE step from DBC.Parents by way
of the primary index into Spool 6346, which is
redistributed by hash code to all AMPs. This step ends a
parallel block of steps.
We do a MERGE into table DBC.Parents from Spool 6346.
We do an INSERT step into table DBC.Parents. This step
begins a parallel block of steps.
We do an INSERT step into table DBC.Accounts. This step is
performed in parallel.
We do a Single-AMP RETRIEVE step from DBC.AccessRights by
way of the primary index into Spool 6347, which is
redistributed by hash code to all AMPs. This step ends a
parallel block of steps.
We do a Single-AMP RETRIEVE step from DBC.AccessRights by
way of the primary index into Spool 6347, which is
redistributed by hash code to all AMPs. This step begins a
parallel block of steps.
We do an All-AMPs RETRIEVE step from DBC.AccessRights by
way of an all-rows scan into Spool 6348, which is
redistributed by hash code to all AMPs. This step ends a
parallel block of steps.
We do an All-AMPs JOIN step from DBC.Owners by way
of an all-rows scan, which is joined to Spool 6348.
table Owners and Spool 6348 are joined using a
merge join. The result goes into Spool 6347, which
is redistributed by hash code to all AMPs.
We do a MERGE into table DBC.AccessRights from Spool
6347.
We flush the DISKSPACE and AMPUSAGE caches.
We do an All-AMPs ABORT test from DBC.DBSpace by way of
the unique primary index.
We do an INSERT step into table DBC.DBSpace.
We do an All-AMPs UPDATE from DBC.DBSpace by way of the
unique primary index.
We flush the DISKSPACE and AMPUSAGE caches.
We Spoil the parser's dictionary cache for the database.
We send out an END TRANSACTION step to all AMPs involved
in processing the request.
135
Chapter 4: System PMPC APIs
MONITOR VERSION
MONITOR VERSION
Purpose
Identifies the highest version number (MonVerId) the Teradata Database monitor function
supports, which determines the requests and data fields available for use.
Input Data
Element
Data Type
Description
IndByte
BYTE
Indicator bits that specify which fields to treat as NULL if you are
using indicator mode.
Each bit in the byte corresponds to one field in the input data.
If data is supplied for that field, then set the bit to zero.
If the data for that field is NULL (that is, there is no data supplied
for that field), then set the bit to 1.
Note: The IndByte field is only required if the PM/API request is
submitted in indicator mode.
mon_ver_id
SMALLINT,
NOT NULL
MONITOR software version ID. This can be version 3 or later.
Usage Notes
The MONITOR VERSION request does not check for access privileges.
Parcels
The MONITOR VERSION request is treated internally as a one-statement request that
generates one response. The statement response returned from Teradata Database contains
the following sequence of parcel types:
Parcel
Sequence
Parcel
Flavor
Length
(Bytes)
Comments/Key Parcel Body Fields
Success
8
18 to 273
StatementNo = 1
ActivityCount = Highest supported version
ActivityType = 108 (PCLMONVER)
DataInfo
136
71
6 to 64100
Optional; this parcel is present if request was
IndicData parcel.
Application Programming Reference
Chapter 4: System PMPC APIs
MONITOR VERSION
Parcel
Sequence
Parcel
Flavor
Length
(Bytes)
Comments/Key Parcel Body Fields
Record
10
• 5 to 64100
(record mode)
• 6 to 64100
(indicator
mode)
Depending on request (Data or IndicData),
data is in record or indicator mode. This
record contains a 2-byte bitmap field
indicating the supported functions and the
current version number.
EndStatement
11
6
StatementNo = 2-byte integer
EndRequest
12
4
None
For more information on parcel body fields, see Teradata Call-Level Interface Version 2
Reference for Mainframe-Attached Systems, or Teradata Call-Level Interface Version 2
Reference for Network-Attached Systems.
The statement response results in a Record parcel containing:
Field
Data Type
Description
FunctionBitmap
SMALLINT,
NOT NULL
Functions are:
SMALLINT,
NOT NULL
Current monitor version number.
CurrentVersion
• Bit0 = ModifyAccount
• Bit1 = Monitor SQL
• Bit2 = 15 - Set to zero (This bit is not currently used.)
Note: The bits are 1 if supported and 0 if not.
Sample Input
This example shows how the parcels for a MONITOR VERSION request built by CLIv2
appear when sent to the Teradata Database server. In this example, the size of the response
buffer is set at the maximum (64,000 bytes), although you can set it to any size. However, a
minimum response size is 32,000 bytes.
Application Programming Reference
137
Chapter 4: System PMPC APIs
MONITOR VERSION
Flavor
Length
Body
Num
Name
Bytes
Field
Value
0001
Req
19
Request
MONITOR VERSION
0003
Data
8
MonVerID
9
0004
Resp
6
BufferSize
64000
Sample Output
This example shows the values returned in character text format for the
MONITOR VERSION request. Your application program may display returned values in a
different format.
SUCCESS parcel:
StatementNo=1,
ActivityCount=1,
ActivityType=111, FieldCount=2
MONITOR VERSION:
Function bitmap: 3, Current monitor version=9
138
Application Programming Reference
Chapter 4: System PMPC APIs
MONITOR VIRTUAL CONFIG
MONITOR VIRTUAL CONFIG
Purpose
Collects information on virtual processor (vproc) availability.
Input Data
Element
Data Type
Description
IndByte
BYTE
Indicator bits that specify which fields to treat as NULL if
you are using the indicator mode.
Each bit in the byte corresponds to one field in the input
data.
If data is supplied for that field, then set the bit to zero.
If the data for that field is NULL (that is, there is no data
supplied for that field), then set the bit to 1.
Note: The IndByte field is only required if the PM/API
request is submitted in indicator mode.
mon_ver_id
SMALLINT,
NOT NULL
MONITOR software version ID. This can be version 2 or
later.
For a general explanation of monitor version choices, see
“MONITOR VERSION” on page 136.
Monitor Privileges
To use this request, you must have any one of the following monitor privileges as part of your
default role or any of these privileges must be granted directly to you:
•
ABORTSESSION
•
MONRESOURCE
•
MONSESSION
•
SETRESRATE
•
SETSESSRATE
For more information on roles and privileges, see Database Administration and Security
Administration.
Usage Notes
Information regarding vproc status is returned for all AMP, PE, and TVS vprocs in the system.
MONITOR VIRTUAL CONFIG is most useful when used with the MONITOR VIRTUAL
SUMMARY request for doing a quick overall system health check. For more information, see
Application Programming Reference
139
Chapter 4: System PMPC APIs
MONITOR VIRTUAL CONFIG
“Relationship Between MONITOR VIRTUAL CONFIG and MONITOR VIRTUAL
SUMMARY” on page 145.
If you use MONITOR VIRTUAL CONFIG, you do not need to dump out the
DBC.SW_Event_Log table (accessible from the DBC.Software_Event_LogV view) to see if
there is a physical problem with the system.
Parcels
The MONITOR VIRTUAL CONFIG request is treated internally as a two statement request
with each statement generating a response. The two statement response returned from
Teradata Database contains the following sequence of parcel types:
Parcel
Sequence
Parcel
Flavor
Length
(Bytes)
Comments/Key Parcel Body Fields
Success
8
18 to 273
StatementNo =1
ActivityCount = 1
ActivityType = 91 (PCLMONVCONFIG)
DataInfo
71
6 to 64100
Optional; this parcel is present if request was
IndicData parcel.
Record
10
• 5 to 64100
(record mode)
• 6 to 64100
(indicator
mode)
Depending on request (Data or IndicData),
data is in record or indicator mode. This
record contains the BYNET status data and
the type of system running the Teradata
Database software.
EndStatement
11
6
StatementNo = 2-byte integer
Success
8
18 to 273
StatementNo = 2
ActivityCount = Number of vprocs
ActivityType = 91 (PCLMONVCONFIG)
140
DataInfo
71
6 to 64100
Optional; this parcel is present if request was
IndicData parcel.
Record
10
• 5 to 64100
(record mode)
• 6 to 64100
(indicator
mode)
Depending on request (Data or IndicData),
data is in record or indicator mode. This
record contains the vproc-specific
information; one record per vproc.
EndStatement
11
6
StatementNo = 2-byte integer
EndRequest
12
4
None
Application Programming Reference
Chapter 4: System PMPC APIs
MONITOR VIRTUAL CONFIG
Statement Type: 1
The following table describes the order in which the Record parcel in the first statement of the
MONITOR VIRTUAL CONFIG returns the BYNET status values and the system type.
Column
Field
Data Type
Description
1
NetAUp
VARCHAR (1),
NOT NULL
Status of the BYNETs (if there are more than two,
the first two) on a system-wide basis.
• U = All node BYNETs are up/online.
• D = One or more node BYNETs is down/
offline.
• “” = A temporary condition where the BYNET
data is not available.
2
NetBUp
VARCHAR (1),
NOT NULL
Status of the BYNETs (if there are more than two,
the first two) on a system-wide basis:
• U = All node BYNETs are up/online.
• D = One or more node BYNETs is down/
offline.
• “” = A temporary condition where the BYNET
data is not available.
3
SystemType
VARCHAR (7),
NOT NULL
Type of system running the Teradata Database
software, such as 3400, 3500, 5100, or ‘Other’.
If all the nodes in the system are the same type,
this field returns the type of the system.
If any of the nodes are of a different type, this
field returns ‘Mixed’.
Statement Type: 2
The Record parcels in the second statement of the MONITOR VIRTUAL CONFIG response
return one record for each processor, with six fields in each record. Records are sorted based
on VProcNo. For example, if you have 32 vprocs, 32 records are returned with specific
information for each vproc, in addition to the one record of BYNET data for the whole
system.
Application Programming Reference
141
Chapter 4: System PMPC APIs
MONITOR VIRTUAL CONFIG
Field Name
Data Type
Description
ProcId
SMALLINT
ID associated with a node. This value is computed as the
module number within a cabinet plus 100 times the cabinet
number. Usually formatted for display as zz9-99. However, this
display format can be changed by the user.
VProcNo
SMALLINT,
NOT NULL
ID of an AMP (that is, a set of disk) and the associated tasks or
processes that, in combination, make up the AMP), PE or TVS
vproc.
VProcType
VARCHAR (3),
NOT NULL
Type of vproc:
HostId
SMALLINT
Logical host ID for the PEs. This field shows NULL for the
AMP or TVS vprocs associated with this record. Each channelor LAN-connected host is assigned an ID at the time the system
is configured. Each PE is assigned to a (single)
channel-connected host (or client) or a LAN-connected host.
The host ID of zero is reserved for the PEs processing internal
sessions.
Status
VARCHAR (1),
NOT NULL
Status of the vproc associated with this record. A vproc is
considered up or down from the standpoint of whether the
vproc is helping a query process SQL statements. For example,
an AMP doing offline recovery is considered to be down
because the AMP is not helping to process SQL statements. On
the other hand, an up vproc is one that is online and fully up or
is in online recovery.
• AMP
• PE
• MISC
The status of the vproc:
• U = The vproc is up/online.
• D = The vproc is down/offline.
DiskSlice
SMALLINT
Virtual disk ID defining the portion of a physical disk assigned
to an AMP.
This value is NULL for TVS vprocs.
Sample Input
This example shows how the parcels for a MONITOR VIRTUAL CONFIG request built by
CLIv2 appear when sent to the Teradata Database server. In this example, the size of the
response buffer is set at the maximum (64,000 bytes), although you can set it to any size.
However, a minimum response size is 32,000 bytes.
142
Application Programming Reference
Chapter 4: System PMPC APIs
MONITOR VIRTUAL CONFIG
Flavor
Length
Body
Num
Name
Bytes
Field
Value
0001
Req
26
Request
MONITOR VIRTUAL CONFIG
0003
Data
6
MonVerID
2
0004
Resp
6
BufferSize
64000
Sample Output
This example shows the values returned in character text format for the MONITOR VIRTUAL
CONFIG request. Your application program may display returned values in a different format.
Success parcel:
StatementNo: 1
ActivityCount: 1
ActivityType: 91
FieldCount: 3
DataInfo parcel:
FieldCount: 3
Record parcel.
Parcel flavor:
10
Parcel body length:
NetAUp = 'U', NetBUp = 'U', SystemType = "5100
EndStatement.
Success parcel:
StatementNo: 2
ActivityCount: 20
ActivityType: 91
FieldCount: 6
DataInfo parcel:
FieldCount: 6
Record parcel.
Parcel flavor:
10
Parcel body length:
NodeId = 746, VProcNo = 0, VProcType = "AMP",
VProcStatus = 'U', DiskSlice = 0.
Record parcel.
Parcel flavor:
10
Parcel body length:
NodeId = 736, VProcNo = 1, VProcType = "AMP",
VProcStatus = 'U', DiskSlice = 1.
Record parcel.
Parcel flavor:
10
Parcel body length:
NodeId = 746, VProcNo = 2, VProcType = "AMP",
VProcStatus = 'U', DiskSlice = 2.
Record parcel.
Parcel flavor:
10
Parcel body length:
NodeId = 736, VProcNo = 3, VProcType = "AMP",
VProcStatus = 'U', DiskSlice = 3.
Record parcel.
Parcel flavor:
10
Parcel body length:
NodeId = 746, VProcNo = 4, VProcType = "AMP",
VProcStatus = 'U', DiskSlice = 4.
Record parcel.
Parcel flavor:
10
Parcel body length:
NodeId = 736, VProcNo = 5, VProcType = "AMP",
VProcStatus = 'U', DiskSlice = 5.
Record parcel.
Parcel flavor:
10
Parcel body length:
NodeId = 746, VProcNo = 6, VProcType = "AMP",
Application Programming Reference
10
".
13
HostId = <null>,
13
HostId = <null>,
13
HostId = <null>,
13
HostId = <null>,
13
HostId = <null>,
13
HostId = <null>,
13
HostId = <null>,
143
Chapter 4: System PMPC APIs
MONITOR VIRTUAL CONFIG
VProcStatus = 'U', DiskSlice = 6.
Record parcel.
Parcel flavor:
10
Parcel body length:
13
NodeId = 736, VProcNo = 7, VProcType = "AMP", HostId = <null>,
VProcStatus = 'U', DiskSlice = 7.
Record parcel.
Parcel flavor:
10
Parcel body length:
13
NodeId = 746, VProcNo = 8, VProcType = "AMP", HostId = <null>,
VProcStatus = 'U', DiskSlice = 8.
Record parcel.
Parcel flavor:
10
Parcel body length:
13
NodeId = 736, VProcNo = 9, VProcType = "AMP", HostId = <null>,
VProcStatus = 'U', DiskSlice = 9.
Record parcel.
Parcel flavor:
10
Parcel body length:
13
NodeId = 746, VProcNo = 10, VProcType = "AMP", HostId = <null>,
VProcStatus = 'U', DiskSlice = 10.
Record parcel.
Parcel flavor:
10
Parcel body length:
13
NodeId = 736, VProcNo = 11, VProcType = "AMP", HostId = <null>,
VProcStatus = 'U', DiskSlice = 11.
Record parcel.
Parcel flavor:
10
Parcel body length:
13
NodeId = 746, VProcNo = 12, VProcType = "AMP", HostId = <null>,
VProcStatus = 'U', DiskSlice = 12.
Record parcel.
Parcel flavor:
10
Parcel body length:
13
NodeId = 736, VProcNo = 13, VProcType = "AMP", HostId = <null>,
VProcStatus = 'U', DiskSlice = 13.
Record parcel.
Parcel flavor:
10
Parcel body length:
13
NodeId = 746, VProcNo = 14, VProcType = "AMP", HostId = <null>,
VProcStatus = 'U', DiskSlice = 14.
Record parcel.
Parcel flavor:
10
Parcel body length:
13
NodeId = 736, VProcNo = 15, VProcType = "AMP", HostId = <null>,
VProcStatus = 'U', DiskSlice = 15.
Record parcel.
Parcel flavor:
10
Parcel body length:
13
NodeId = 746, VProcNo = 1020, VProcType = "PE ", HostId = 52,
VProcStatus = 'U', DiskSlice = <null>,
Record parcel.
Parcel flavor:
10
Parcel body length:
13
NodeId = 746, VProcNo = 1021, VProcType = "PE ", HostId = 52,
VProcStatus = 'U', DiskSlice = <null>,
Record parcel.
Parcel flavor:
10
Parcel body length:
13
NodeId = 736, VProcNo = 1022, VProcType = "PE ", HostId = 52,
VProcStatus = 'U', DiskSlice = <null>,
Record parcel.
Parcel flavor:
10
Parcel body length:
13
NodeId = 736, VProcNo = 1023, VProcType = "PE ", HostId = 52,
VProcStatus = 'U', DiskSlice = <null>,
EndStatement.
EndRequest.
144
Application Programming Reference
Chapter 4: System PMPC APIs
MONITOR VIRTUAL CONFIG
Relationship Between MONITOR VIRTUAL CONFIG and
MONITOR VIRTUAL SUMMARY
Use MONITOR VIRTUAL SUMMARY with the MONITOR VIRTUAL CONFIG request for
an overall system status. These are low overhead requests.
•
Execute the MONITOR VIRTUAL SUMMARY request every 5 or 10 minutes for a lowcost, continuous monitoring of your system.
•
Execute the MONITOR VIRTUAL CONFIG request to get a picture of your system
configuration at defined times, such as at the beginning of a day, various times during the
day, or when the system is down.
Using these requests to spot problems, such as abnormal AMP CPU load balancing, and
possible sources of system performance bottlenecks. For example, if the HiCPUAMPUse,
HiCPUPEUse, LoCPUAMPUse, and LoCPUPEUse figures are consistently widely separated
and do not approximate the AMPAvgCPU figure, you may need to evaluate whether the
system is using available resources efficiently. Alternatively, if the PEAvgCPU is consistently
much higher than the AMPAvgCPU, the system may not be configured to efficiently use AMP
resources. How often you perform a health check of your system depends on the size of your
system and the type of applications run.
Knowledge of the overall system status can help you to determine:
Concern
Comments
When to run production
applications, especially large ones
For example, if you have a down AMP, you may decide that it is
less costly to recover the AMP first and run the job than to run
the job without full system availability.
Why an application runs more
slowly than usual
This situation may be caused by a down AMP, which results in
the backup AMP doing more work, specifically, doing backup
and primary processing. This, in turn, could cause your
application to run more slowly.
Whether all vprocs have come
back up after a system restart
Examine the Status value returned in a MONITOR VIRTUAL
CONFIG request to determine whether each vproc is up or
down (see the MONITOR VIRTUAL CONFIG Status field).
The response data returned by MONITOR VIRTUAL CONFIG is similar in content to the
response data returned by a MONITOR VIRTUAL RESOURCE request, but it is in an
abbreviated form. In your initial problem analysis, if the information returned from a
MONITOR VIRTUAL SUMMARY query does not give you enough data. For example, you
need BYNET or CPU% busy information and you may want to use MONITOR VIRTUAL
RESOURCE to obtain more detailed resource usage data.
Application Programming Reference
145
Chapter 4: System PMPC APIs
MONITOR VIRTUAL RESOURCE
MONITOR VIRTUAL RESOURCE
Purpose
Collects performance information for each AMP, PE, or TVS vproc and returns:
•
System-wide (identical for all vprocs) data
•
vproc-specific data
Input Data
Element
Data Type
Description
IndByte
BYTE
Indicator bits that specify which fields to treat as NULL if you
are using the indicator mode.
Each bit in the byte corresponds to one field in the input data.
If data is supplied for that field, then set the bit to zero.
If the data for that field is NULL (that is, there is no data
supplied for that field), then set the bit to 1.
Note: The IndByte field is only required if the PM/API request
is submitted in indicator mode.
mon_ver_id
SMALLINT,
NOT NULL
MONITOR software version ID. This can be version 2 or later.
For a general explanation of monitor version choices, see
“MONITOR VERSION” on page 136.
Monitor Privileges
To use this request, you must have the MONRESOURCE privilege as part of your default role
or this privilege must be granted directly to you.
For more information on roles and privileges, see Database Administration and Security
Administration.
Usage Notes
You can use the MONITOR VIRTUAL RESOURCE request to:
•
Expand on the data reported by the MONITOR VIRTUAL SUMMARY request.
In your initial problem analysis, a MONITOR VIRTUAL SUMMARY request may indicate
a performance or system problem. MONITOR VIRTUAL RESOURCE allows you to
collect RSS data on a vproc by vproc basis.
•
Continually monitor your system.
Monitor your system continually on a periodic basis, for example, every 10 minutes. Use
this request to build a normal baseline profile for your system. When you notice
146
Application Programming Reference
Chapter 4: System PMPC APIs
MONITOR VIRTUAL RESOURCE
something abnormal, such as the last reading is significantly different from the normal
baseline reading, or when a user complains that a job is slow, this request can tell you if
there is a parallel efficiency problem or a constraint to throughput, and which vproc is
causing it. For example, if one PE shows a much higher usage than the other PEs, that PE
might be overloaded. Also, if one AMP is loaded more heavily than the other AMPs, you
may have problems with a skewed index.
•
Determine whether a new application can be added to the current system load without
disruption.
The vproc usage information collected by this request can help you evaluate the impact of
adding new applications to an already heavily utilized system and help you plan potential
system upgrades.
•
Help resolve problems that session-level usage information cannot resolve.
When the MONITOR SESSION request does not show any cause for the problem, this request
can supply information regarding congestion, memory allocations, BYNET outages, and
system status.
The MONITOR VIRTUAL RESOURCE request can provide information about:
•
How the system is being used (for example, the number of sessions associated with each
vproc and the percentage of CPU usage by vproc).
•
How system resource usage is spread across the vprocs (for example, whether the vprocs
are used evenly).
•
How much physical disk I/O, BYNET traffic, or host reads and writes are occurring.
•
Whether congestion or excessive swapping is a problem on any vproc or group of vprocs.
The MONITOR VIRTUAL RESOURCE request returns some of the same fields found in the
resource usage tables. You can use both MONITOR VIRTUAL RESOURCE and resource
usage data for problem detection. Unlike resource usage data, MONITOR VIRTUAL
RESOURCE data is near real time, and requires less overhead to produce, but is less
comprehensive. MONITOR VIRTUAL RESOURCE data can help detect:
•
Poor AMP CPU parallel efficiency
•
Poor disk parallel efficiency
•
A higher than expected disk read/write ratio
•
A high swap I/O rate
If MONITOR VIRTUAL RESOURCE does not give you all the detailed data you need for
problem detection, run one or more of the resource usage macros for the AMP, PE, or TVS
vprocs. See Resource Usage Macros and Tables for more information on problem detection and
the resource usage macros.
Note: You must set the rate by which vproc resource usage data is updated in memory
(ResMonitor rate) to nonzero for the MONITOR VIRTUAL RESOURCE request to return
meaningful data. If you set the ResMonitor rate to zero, NULL is returned for all vproc usage
data.
Also note that if the TVS vproc is configured on a node without any AMPs, all fields will
return a value of zero.
Application Programming Reference
147
Chapter 4: System PMPC APIs
MONITOR VIRTUAL RESOURCE
After a system outage or a change in the ResMonitor rate, do not request data again until after
completion of the first collection period requested after the crash or change in rate.
Otherwise, the data returned will contain NULL for all columns except NetAUp, NetBUp,
SampleSec, CollectionDate, CollectionTime, VProcType, ProcId, VProcNo, HostId/
ClusterNo, and Status, and may not be fully representative. This is because after a system
failure, the in-memory counters are reset, and typically the contents of the counters are not
well defined until a full collection period has elapsed. In fact, if you were logged on prior to
the system outage and you issue your first MONITOR VIRTUAL RESOURCE request after the
outage, you will receive a warning that the Teradata Database system has been restarted.
Parcels
The MONITOR VIRTUAL RESOURCE request is treated internally as a two statement
request, with each statement generating a response. The two statement response returned
from Teradata Database contains the following sequence of parcel types:
Parcel
Sequence
Parcel
Flavor
Length
(Bytes)
Comments/Key Parcel Body Fields
Success
8
18 to 273
StatementNo = 1
ActivityCount = 1
ActivityType = 95 (PCLMONVRES)
DataInfo
71
6 to 64100
Optional; this parcel is present if request was
IndicData parcel.
Record
10
• 5 to 64100
(record
mode)
• 6 to 64100
(indicator
mode)
Depending on request (Data or IndicData),
data is in record or indicator mode. One record
is returned that contains the duration of the
collection period (in seconds), BYNET status,
and the date and time the Virtual Resource
cache was last refreshed.
EndStatement
11
6
StatementNo = 2-byte integer
Success
8
18 to 273
StatementNo = 2
ActivityCount = Number of vprocs
ActivityType = 95 (PCLMONVRES)
148
DataInfo
71
6 to 64100
Optional; this parcel is present if request was
IndicData parcel.
Record
10
• 5 to 64100
(record
mode)
• 6 to 64100
(indicator
mode)
Depending on request (Data or IndicData),
data is in record or indicator mode. One record
per vproc is returned that contains a
description for each vproc in the system.
EndStatement
11
6
StatementNo = 2-byte integer
EndRequest
12
4
None
Application Programming Reference
Chapter 4: System PMPC APIs
MONITOR VIRTUAL RESOURCE
Statement Type: 1
The Record parcel in the first statement of the MONITOR VIRTUAL RESOURCE response
returns global data about collection duration and BYNET status in the order listed below.
Field Name
Data Type
Description
NetAUp
VARCHAR (1),
NOT NULL
Status of the BYNETs (if there are more than two, the first
two) on a system-wide basis:
• U = All node BYNETs are up/online.
• D = One or more node BYNETs is down/offline.
• “” = A temporary condition where the BYNET data is not
available.
NetBUp
VARCHAR (1),
NOT NULL
Status of the BYNETs (if there are more than two, the first
two) on a system-wide basis:
• U = All node BYNETs are up/online.
• D = One or more node BYNETs is down/offline.
• “” = A temporary condition where the BYNET data is not
available.
SampleSec
SMALLINT,
NOT NULL
Duration of the collection period in seconds. This field
returns the ResMonitor rate. See “Data Collection” and “SET
RESOURCE RATE” for more information on ResMonitor.
CollectionDate
DATE,
NOT NULL
Date the Virtual Resource cache was last refreshed.
CollectionTime
FLOAT,
NOT NULL
Time the Virtual Resource cache was last refreshed.
Statement Type: 2
The response to the second statement results in multiple Record parcels that consist of a
record for each vproc in the system. The Record parcels in the second statement of the
MONITOR VIRTUAL RESOURCE response can return multiple records, specifically, one
record of 32 fields for each vproc in the system. For example, if you have 50 vprocs, 50 records
are returned with specific information for each vproc, one record describing the collection
period, and BYNET status for the entire system. Records are sorted by VProcType and
VProcNo.
The following table shows the order in which the data is returned from the Record parcel.
Column Name
Data Type
Description
VprocType
VARCHAR (3),
NOT NULL
Type of vproc:
Application Programming Reference
• AMP
• PE
• MISC
149
Chapter 4: System PMPC APIs
MONITOR VIRTUAL RESOURCE
Column Name
Data Type
Description
ProcId
SMALLINT
ID associated with a node. This value is computed as the
module number within a cabinet plus 100 times the
cabinet number. Usually formatted for display as zz9-99.
However, this display format can be changed by the user.
VprocNo
SMALLINT,
NOT NULL
ID of an AMP (that is, a set of disks and the associated tasks
or processes that, in combination, make up the AMP), PE
or TVS vproc.
HostId/ClusterNo
SMALLINT
For a PE vproc, this field, HostId, identifies one of the hosts
or LANs associated with the described PE.
For an AMP vproc, this field, ClusterNo, identifies the
cluster to which this AMP has been assigned.
Note: This field is not applicable to TVS vproc and returns
NULL.
CPUUse
FLOAT, range 0
- 100%
% of CPU usage not spent being idle.
The value is computed from ResUsageSvpr table data as:
100.00 * (CPUUExecPart00 + CPUUExecPart01 + ... +
CPUUExecPart47 + CPUUServPart00 + CPUUServPart01
+ ... + CPUUServPart47) / (NCPUs * SampleSec * 100)
where NCPUs is the number of CPUs in the node.
This value is NULL if certain conditions apply, see “Usage
Notes” on page 146 for more information.
Status
VARCHAR (1),
NOT NULL
Status of the node, AMP, PE, or TVS vproc associated with
this record:
• U = Up/online.
• D = Down/offline.
A node is up (U) when it is:
• Configured into the system
• Online
• Capable of actively performing tasks associated with
normal Teradata Database activity
Down (D) represents all other potential states.
SessLogCount
SMALLINT
Number of current sessions logged to this PE. A logged on
session is either a session whose logon request was
delivered to this PE, or a session that was switched to this
PE following its logon.
Note: The SessLogCount field contains the SubPoolId if
the vproc type is TVS.
SubpoolId identifies the subpool associated with the
allocator vproc. A subpool defines a set of storage and
allocator vprocs assigned to that storage.
This value is NULL if certain conditions apply, see “Usage
Notes” on page 146 for more information.
150
Application Programming Reference
Chapter 4: System PMPC APIs
MONITOR VIRTUAL RESOURCE
Column Name
Data Type
Description
SessRunCount
SMALLINT
Number of current sessions whose Initiate Requests (TSR
messages) are addressed to this vproc. For example:
• PEs have a SessRunCount that includes all the Teradata
SQL and MONITOR sessions logged on to that PE.
• AMPs may have a nonzero SessRunCount, since AMPs
receive TSR messages from FastLoad or MultiLoad
logons.
Note: Sessions involving Archive/Recovery jobs are not
included in this SessRunCount because HUT sessions do
not deliver TSR messages to a fixed AMP or PE.
This value is NULL if certain conditions apply, see “Usage
Notes” on page 146 for more information.
Note: This field is not applicable to TVS vprocs.
DiskUse
FLOAT
% of disk usage per AMP.
This value is computed from the ResUsageSvdsk table data:
(OutReqTime 1 + ... + OutReqTime n) / SampleSec
where n is the number of vdisks used by this AMP.
Note: DiskUse does not take into account overlapping of
operations among multiple storage controllers, but it
allows for the possibility of multiple requests for the same
controller.
This value is NULL if certain conditions apply, see “Usage
Notes” on page 146 for more information.
DiskReads
FLOAT
Total number of physical disk reads per AMP during the
collection period.
This value is computed from the ResUsageSvpr table data
as:
FilePCiAcqReads + FilePDbAcqReads + FileSCiAcqReads +
FileSDbAcqReads + FileTjtAcqReads + FileAPtAcqReads;
This value is NULL if certain conditions apply, see “Usage
Notes” on page 146 for more information.
Note: This field is not applicable to TVS and PE vprocs.
Application Programming Reference
151
Chapter 4: System PMPC APIs
MONITOR VIRTUAL RESOURCE
Column Name
Data Type
Description
DiskWrites
FLOAT
Total number of physical disk writes per AMP during the
collection period.
For PE and AMP-level displays, this value is computed
from ResUsageSvpr table data as:
FilePCiFWrites + FilePDbFWrites + FileSCiFWrites +
FilesDbFWrites + FileTjtFWrites + FileAPtFWrites +
FilePCiDyaWrites + FilePDbDyaWrites + FileSciDyaWrites
+ FilesDbDyaWrites + FileTjtDyaWrites +
FileAptDyaWrites
For TVS vproc displays, this value is computed from
ResUsageSvpr table data as:
AllocatorMapIOsDone
This value is NULL if certain conditions apply, see “Usage
Notes” on page 146 for more information.
DiskOutReqAvg
FLOAT
Average number of outstanding disk requests.
For AMP-level displays, this value is computed from
ResUsageSvdsk table data, assuming n is the number of
storage devices used by this vproc:
(ReadRespTot 1 + WriteRespTot 1 + ... + ReadRespTot n +
WriteRespTot n) / CentiSecs
Note: This field is not applicable to PE vprocs.
For TVS vproc-level displays, this value is computed from
ResUsageSvpr table data as:
AllocatorMapIOsStarted - AllocatorMapIOsDone
This value is NULL if certain conditions apply, see “Usage
Notes” on page 146 for more information.
HostBlockReads
FLOAT
Number of message blocks (one or more messages sent in
one physical group) received from all clients.
This value corresponds to the column totals in the
ResUsageShst table supplying HostBlockReads for this
vproc.
This value is NULL if certain conditions apply, see “Usage
Notes” on page 146 for more information.
Note: This field is not applicable to AMP or TVS vprocs.
HostBlockWrites
FLOAT
Number of message blocks (that is, one or more messages
sent in one physical group) sent to all hosts.
This value corresponds to the column totals in the
HstBlkWrts column of the ResUsageShst table.
Note: This field is not applicable to AMP or TVS vprocs.
152
Application Programming Reference
Chapter 4: System PMPC APIs
MONITOR VIRTUAL RESOURCE
Column Name
Data Type
Description
MemAllocates
FLOAT
Number of segments allocated to memory resources.
This value is calculated from the following ResUsageSvpr
table column:
MemCtxtAllocs
This value is NULL if certain conditions apply, see “Usage
Notes” on page 146 for more information.
MemAllocateKB
FLOAT
Value represents the change in vproc-level memory.
MemAllocateKB represents a delta from the previous
reporting period. It reports negative values as less memory
is used.
This value is calculated from the following ResUsageSvpr
column:
MemCtxAllocs * FIXEDPAGESIZE
This value is NULL if certain conditions apply, see “Usage
Notes” on page 146 for more information.
PercentService
FLOAT
% of CPU resources spent in PDE user service processing.
This value is computed from the ResUsageSvpr table data,
where x represents the number of CPUs:
(CPUUServPart00 + CPUUServPart01 + ... +
CPUUServPart47) /(x * SampleSec)
This value is NULL if certain conditions apply, see “Usage
Notes” on page 146 for more information.
PercntAMPWT
FLOAT,
range 0 - 100%
% of CPU resources used by either the AMP Worker Task
(Partition 11) or by the TVS Task (Partition 31) depending
on the type of vproc this record represents. For
information on partition assignments, see Resource Usage
Macros and Tables.
This value depends on the number of CPUs in the node but
does not exceed 100%. It is computed from the
ResUsageSvpr table data, where x represents the number of
CPUs on a node:
For AMP vprocs:
(CPUUExecPart11) / (x * SampleSec)
For TVS vprocs:
(CPUUExecPart31) / (x * SampleSec)
This value is NULL if certain conditions apply, see “Usage
Notes” on page 146 for more information.
PercntParser
Application Programming Reference
FLOAT,
range 0 - 100%
Note: This field is obsolete and returns zero or NULL.
153
Chapter 4: System PMPC APIs
MONITOR VIRTUAL RESOURCE
Column Name
Data Type
Description
PercntDispatcher
FLOAT,
range 0 - 100%
% of CPU resources spent in PE Dispatcher processing.
This value depends on the number of CPUs in the node
but does not exceed 100%. This value is computed from
the ResUsageSvpr table data, where x represents the
number of CPUs on a node:
(CPUUExecPart13 + CPUUServPart13) / (x * SampleSec)
Note: The PercntParser CPU time is included in the
PercntDispatcher value.
This value is NULL if certain conditions apply, see “Usage
Notes” on page 146 for more information.
Note: PercntDispatcher is not applicable to AMP and TVS
vprocs.
NetReads
FLOAT
Number of Reads from the BYNET to the vproc.
This value is computed from the ResUsageSvpr table data
as follows:
NetBrdReads + NetPtPReads
This value is NULL if certain conditions apply, see “Usage
Notes” on page 146 for more information.
NetWrites
FLOAT
Number of messages written from the AMP, PE, or vproc to
the BYNET during the collection period.
This value is computed from the ResUsageSvpr table data
as follows:
NetBrdWrites + NetPtPWrites
This value is NULL if certain conditions apply, see “Usage
Notes” on page 146 for more information.
MaxIOResp
FLOAT
Value is computed from ResUsageSvpr table data using the
IoRespMax field. IoRespMax is the maximum I/O response
time in milliseconds. That is, the number of operations for
each AMP vproc on that node. For details, see Resource
Usage Macros and Tables.
Note: This field is not applicable to PE and TVS vprocs.
This value is NULL if certain conditions apply, see “Usage
Notes” on page 146 for more information.
Sample Input
This example shows how the parcels for a MONITOR VIRTUAL RESOURCE request built by
CLIv2 look when sent to the Teradata Database server. The size of the response buffer is set in
154
Application Programming Reference
Chapter 4: System PMPC APIs
MONITOR VIRTUAL RESOURCE
the example at the maximum (64,000 bytes), although you can set it to any size. However, a
minimum response size is 32,000 bytes.
Flavor
Length
Body
Num
Name
Bytes
Field
Char/Decimal
0001
Req
28
Request
MONITOR VIRTUAL RESOURCE
0003
Data
6
MonVerID
9
0004
Resp
6
BufferSize
64000
Sample Output
This example shows the values returned in character text format (a record for each vproc) for
the MONITOR VIRTUAL RESOURCE request. Your application program may display
returned values in a different format.
Note: You can rename the SampleSec field in your application. In the output below, the
SampleRate value is the SampleSec value.
Pay attention to SampleRate when interpreting the results of this request.
Success parcel:
StatementNo=1,
ActivityType=95,
ActivityCount=1,
FieldCount=5
NetAUp: U NetBUp: U
SampleRate: 30
Collection Date/Time:
06/15/2011 18:29:31.00
Success parcel: StatementNo=2,ActivityCount=8,ActivityType=95, FieldCount=23
VprocNo:
ProcId:
0
33
SessLogCount: 0
CPUUse:
PctAMPWT:
DiskReads:
0.0
0.0
0.00
Vproctype: AMP
Status:
HostId/ClusterNo: 0
U
SessRunCount: 0
PctService: 0.0
DiskUse: 32.2
DiskWrites: 3445.00
NetReads:
51.00
NetWrites:
NVMemAllocSegs: 283.00
DiskOutReqAvg:
1.18
48.00
--------------------------------------------------------VprocNo:
1
Vproctype: AMP
Status: U
ProcId:
33
HostId/ClusterNo: 0
SessLogCount: 0
CPUUse:
PctAMPWT:
DiskReads:
0.0
0.0
0.00
SessRunCount: 0
PctService: 0.0
DiskUse: 32.4
DiskWrites: 3440.00
Application Programming Reference
DiskOutReqAvg:
1.52
155
Chapter 4: System PMPC APIs
MONITOR VIRTUAL RESOURCE
NetReads:
38.00
NetWrites:
NVMemAllocSegs: 307.00
39.00
--------------------------------------------------------VprocNo:
2
Vproctype: AMP
Status: U
ProcId:
33
HostId/ClusterNo: 1
SessLogCount: 0
CPUUse:
PctAMPWT:
DiskReads:
0.0
0.0
0.00
SessRunCount: 0
PctService: 0.0
DiskUse: 32.6
DiskWrites: 3441.00
NetReads:
38.00
NetWrites:
NVMemAllocSegs: 277.00
DiskOutReqAvg:
1.48
39.00
--------------------------------------------------------VprocNo:
3
Vproctype: AMP
Status: U
ProcId:
33
HostId/ClusterNo: 1
SessLogCount: 0
CPUUse:
PctAMPWT:
DiskReads:
0.0
0.0
0.00
SessRunCount: 0
PctService: 0.0
DiskUse: 32.3
DiskWrites: 3357.00
NetReads:
37.00
NetWrites:
NVMemAllocSegs: 258.00
DiskOutReqAvg:
1.06
38.00
--------------------------------------------------------VprocNo: 10237
Vproctype: TVS
Status: U
ProcId:
33
HostId/ClusterNo: 0
SubPoolId: 1
CPUUse:
0.0
PctService: 0.0
CPUExecPart31:
0.0
DiskUse: 0.0
AllocatorMapIOsDone:
75.00
PendingAllocatorMapIOs:
NetReads:
76.00
NetWrites:
NVMemAllocSegs:
0.00
0.00
77.00
--------------------------------------------------------VprocNo: 10238
Vproctype: TVS
Status: U
ProcId:
33
HostId/ClusterNo: 0
SubPoolId: 0
CPUUse:
0.0
PctService: 0.0
CPUExecPart31:
0.0
DiskUse: 0.0
AllocatorMapIOsDone:
76.00
PendingAllocatorMapIOs:
NetReads:
77.00
NetWrites:
NVMemAllocSegs:
0.00
0.00
76.00
--------------------------------------------------------VprocNo: 16382
Vproctype: PE
Status: U
ProcId:
33
HostId/ClusterNo: 1025
156
Application Programming Reference
Chapter 4: System PMPC APIs
MONITOR VIRTUAL RESOURCE
SessLogCount: 1
CPUUse:
PctParser:
.00
SessRunCount: 0
0.0
0.0
PctService: 0.0
PctDispatcher: 0.0
NetReads:
7.00
NetWrites:
NVMemAllocSegs:
0.00
HstBlkRds:
0.00
HstBlkWrts:
0
0.00
HstBlkWrts:
0
7.00
--------------------------------------------------------VprocNo: 16383
Vproctype: PE
Status: U
ProcId:
33
HostId/ClusterNo: 1025
SessLogCount: 1
CPUUse:
PctParser:
.00
SessRunCount: 0
0.0
0.0
PctService: 0.0
PctDispatcher: 0.0
NetReads:
0.00
NetWrites:
NVMemAllocSegs:
0.00
EndStatement.
EndRequest.
HstBlkRds:
1.00
Warning and Error Messages
All users who are logged on and issue a MONITOR VIRTUAL RESOURCE request after a
system restart, or after the last rate change can expect to receive a warning message. Generally,
two types of situations can produce warning messages:
•
After a system restart, before and after a collection period has expired.
If the collection period has not expired and the user issues the next MONITOR VIRTUAL
RESOURCE request, many of the values returned are NULL.
•
After the last rate change, before and after a collection period has expired.
If the collection period has not expired and the user issues the next MONITOR VIRTUAL
RESOURCE request, many of the values returned are NULL.
In addition, these specific messages may be returned by the MONITOR VIRTUAL
RESOURCE request:
For a discussion of general warning and error messages that may be returned by MONITOR
VIRTUAL RESOURCE and other requests, see “Common Warning and Error Messages” on
page 48.
For more detailed information on warning and error messages, see Messages.
Relationship Between MONITOR VIRTUAL RESOURCE and
ABORT SESSION
If you executed an ABORT SESSION request, data returned in a MONITOR PHYSICAL
RESOURCE or MONITOR VIRTUAL RESOURCE request may be altered. Whether you
notice the change in data depends on the scope of the ABORT SESSION request. For example,
if you execute an ABORT SESSION and log off all of the sessions associated with a specific
Application Programming Reference
157
Chapter 4: System PMPC APIs
MONITOR VIRTUAL RESOURCE
host (or client), the PEs associated with that client will report a large decrease in resource
consumption. However, if the ABORT SESSION request only aborts one transaction from one
session, you may not notice a change in AMP or PE resource use.
Relationship Between MONITOR VIRTUAL RESOURCE and
SET RESOURCE RATE
You must execute the SET RESOURCE RATE request to activate resource data collection
before you execute a MONITOR VIRTUAL RESOURCE or MONITOR PHYSICAL
RESOURCE request. This means that you must set the resource monitoring rate (ResMonitor)
to nonzero. If the ResMonitor rate is set to zero, you will receive an error message.
A change in the resource collection rate by User A, for example, may affect the data reported
by MONITOR VIRTUAL RESOURCE or MONITOR PHYSICAL RESOURCE request made
by User B. If the ResMonitor rate has been altered, User B receives a warning message when
executing a subsequent MONITOR VIRTUAL RESOURCE or MONITOR PHYSICAL
RESOURCE request.
158
Application Programming Reference
Chapter 4: System PMPC APIs
MONITOR VIRTUAL SUMMARY
MONITOR VIRTUAL SUMMARY
Purpose
Collects global summary information on system utilization.
Input Data
Element
Data Type
Description
IndByte
BYTE
Indicator bits that specify which fields to treat as NULL if you are
using indicator mode.
Each bit in the byte corresponds to one field in the input data.
If data is supplied for that field, then set the bit to zero.
If the data for that field is NULL (that is, there is no data supplied
for that field), then set the bit to 1.
Note: The IndByte field is only required if the PM/API request is
submitted in indicator mode.
mon_ver_id
SMALLINT,
NOT NULL
MONITOR software version ID. This can be version 2 or later.
For a general explanation of monitor version choices, see
“MONITOR VERSION” on page 136.
Monitor Privileges
To use this request, you must have any one of the following monitor privileges as part of your
default role or any of these privileges must be granted directly to you:
•
ABORTSESSION
•
MONRESOURCE
•
MONSESSION
•
SETRESRATE
•
SETSESSRATE
For more information on roles and privileges, see Database Administration and Security
Administration.
Usage Notes
The MONITOR VIRTUAL SUMMARY request reports the following types of information:
•
CPU usage (average by vproc type online only)
•
Disk usage (average, high, and low by Vproc ID)
•
AMP usage (average, high, and low by AMP ID)
Application Programming Reference
159
Chapter 4: System PMPC APIs
MONITOR VIRTUAL SUMMARY
•
PE usage (average, high, and low by PE ID)
•
Number of logged on sessions
•
Rate information:
•
•
Vproc resource logging rate
•
Vproc resource monitoring rate
•
Session-level system
•
Local monitoring rates
Current software release and version numbers
You must set the ResMonitor rate (the rate at which vproc resource usage data is updated in
memory) to a nonzero value for the MONITOR VIRTUAL SUMMARY request to return
meaningful data. If you set the ResMonitor rate to zero, NULL is returned for all columns
related to vproc utilization.
After a system outage or a change in the ResMonitor rate, do not request data again until after
the completion of the first collection period requested after the outage or change in rate. If you
ignore this, the data returned will contain NULL. This is because after an outage, the
in-memory counters are reset, and usually the contents of the counters are not well defined
until a full collection period has elapsed. For example, if you were logged on prior to the
system outage and you issue your first MONITOR VIRTUAL SUMMARY request after the
outage, you will receive a warning that the Teradata Database server has been restarted.
Parcels
The response returned from the Teradata Database resembles a summary of the type of
response returned by a MONITOR VIRTUAL RESOURCE request. The response is one row of
35 fields.
The response returned from the Teradata Database contains the following sequence of parcel
types.
Parcel
Sequence
Parcel
Flavor
Length
(Bytes)
Comments/Key Parcel Body Fields
Success
8
18 to 273
ActivityCount =1
ActivityType = 93 (PCLMONVSUMMARY)
160
DataInfo
71
6 to 64100
Optional; this parcel is present if request was
IndicData parcel.
Record
10
• 5 to 64100
(record mode)
• 6 to 64100
(indicator
mode)
Depending on request (Data or IndicData),
data is in record or indicator mode. This
contains the IndicData virtual summary
information and the date and time the Virtual
Resource cache was last refreshed.
EndStatement
11
6
StatementNo = 2-byte integer
EndRequest
12
4
None
Application Programming Reference
Chapter 4: System PMPC APIs
MONITOR VIRTUAL SUMMARY
The Record parcel in the MONITOR VIRTUAL SUMMARY response returns the following
resource usage information.
Field Name
Data Type
Description
AMPAvgCPU
FLOAT,
range 0 to 100%
Average % CPU usage (CPUUse) of all online
AMPs in the configuration.
Assuming n is the number of online AMPs in the
configuration, AMPAvgCPU is computed from
CPUUse data as:
(CPUUse1 + ... + CPUUsen) / n
This value is NULL if certain conditions apply. See
“Usage Notes” on page 159 for more information.
AMPAvgDisk
FOAT
Average physical disk usage (DiskUse) of all online
AMPs in the configuration.
Assuming n is the number of online AMPs in the
configuration, AMPAvgDisk is computed from
DiskUse data as:
(DiskUse1 + ... + DiskUsen) / n
This value is NULL if certain conditions apply. See
“Usage Notes” on page 159 for more information.
AMPAvgDiskIO
FLOAT
Average physical disk DiskReads and DiskWrites of
all online AMPs in the configuration.
Assuming n is the number of online AMPs in the
configuration, AMPAvgDiskIO is computed from
DiskReads and DiskWrites data as:
(DiskReads1 + DiskWrites1 + ... + DiskReads1 +
DiskWritesn) / n
This value is NULL if certain conditions apply. See
“Usage Notes” on page 159 for more information.
HiCPUAMPUse
FLOAT
Highest CPUUse percentage currently associated
with any online AMP.
This value is NULL if certain conditions apply. See
“Usage Notes” on page 159 for more information.
HiCPUAMPNo
SMALLINT
VProcNo of an AMP with CPUUse equal to the
value reported as HiCPUAMPUse.
This value is NULL if certain conditions apply. See
“Usage Notes” on page 159 for more information.
HiCPUAMPProc
SMALLINT
ID of the node currently responsible for managing
the AMP reported as HiCPUAMPNo.
This value is NULL if certain conditions apply. See
“Usage Notes” on page 159 for more information.
Application Programming Reference
161
Chapter 4: System PMPC APIs
MONITOR VIRTUAL SUMMARY
Field Name
Data Type
Description
LoCPUAMPUse
FLOAT
Lowest CPUUse percentage currently associated
with any online AMP.
This value is NULL if certain conditions apply. See
“Usage Notes” on page 159 for more information.
LoCPUAMPNo
SMALLINT
VProcNo of an AMP with CPUUse equal to the
value reported as LoCPUAMPUse.
This value is NULL if certain conditions apply. See
“Usage Notes” on page 159 for more information.
LoCPUAMPProc
SMALLINT
ID of the node currently responsible for managing
the AMP reported as LoCPUAMPNo.
This value is NULL if certain conditions apply. See
“Usage Notes” on page 159 for more information.
HiDiskAMP
FLOAT
Highest DiskUse percentage currently associated
with any online AMP.
This value is NULL if certain conditions apply. See
“Usage Notes” on page 159 for more information.
HiDiskAMPNo
SMALLINT
Number of an AMP with DiskUse equal to the
value reported as HiDiskAMP.
This value is NULL if certain conditions apply. See
“Usage Notes” on page 159 for more information.
HiDiskAMPProc
SMALLINT
ID of the node currently responsible for managing
the AMP reported in HiDiskAMPNo.
This value is NULL when HiDiskAMPNo is NULL.
LoDiskAMP
FLOAT
Lowest DiskUse percentage currently associated
with any online AMP.
This value is NULL if certain conditions apply. See
“Usage Notes” on page 159 for more information.
LoDiskAMPNo
SMALLINT
Number of an AMP with DiskUse equal to the
value reported as LoDiskAMP.
This value is NULL if certain conditions apply. See
“Usage Notes” on page 159 for more information.
LoDiskAMPProc
SMALLINT
ID of the node currently responsible for managing
the AMP reported as LoDiskAMPNo.
This value is NULL when LoDiskAMPNo is NULL.
HiDiskAMPIO
FLOAT
Highest DiskReads and DiskWrites value currently
associated with any online AMP.
This value is NULL if certain conditions apply. See
“Usage Notes” on page 159 for more information.
162
Application Programming Reference
Chapter 4: System PMPC APIs
MONITOR VIRTUAL SUMMARY
Field Name
Data Type
Description
HiDiskAMPIONo
SMALLINT
Number of an AMP with the highest DiskReads
and DiskWrites equal to the value reported as
HiDiskAMPIO.
This value is NULL if certain conditions apply. See
“Usage Notes” on page 159 for more information.
HiDiskAMPIOProc
SMALLINT
ID of the node currently responsible for managing
the AMP reported in HiDiskAMPIONo.
This value is NULL when HiDiskAMPIONo is
NULL.
LoDiskAMPIO
FLOAT
Lowest DiskReads and DiskWrites number
currently associated with any online AMP.
This value is NULL if certain conditions apply. See
“Usage Notes” on page 159 for more information.
LoDiskAMPIONo
SMALLINT
ID of an AMP with lowest DiskReads and
DiskWrites equal to the value reported as
LoDiskAMPIO.
This value is NULL if certain conditions apply. See
“Usage Notes” on page 159 for more information.
LoDiskAMPIOProc
SMALLINT
ID of the node currently responsible for managing
the AMP reported as LoDiskAMPIONo.
This value is NULL when LoDiskAMPIONo is
NULL.
PEAvgCPU
FLOAT
Average CPUUse for all online PEs in the
configuration.
This value is NULL if certain conditions apply. See
“Usage Notes” on page 159 for more information.
HiCPUPEUse
FLOAT
Highest CPUUse percentage currently associated
with any online PE.
This value is NULL if certain conditions apply. See
“Usage Notes” on page 159 for more information.
HiCPUPENo
SMALLINT
VProcNo of a PE with CPUUse equal to the value
reported as HiCPUPEUse.
This value is NULL if certain conditions apply. See
“Usage Notes” on page 159 for more information.
HiCPUPEProc
SMALLINT
ID of the node currently responsible for managing
the PE reported in HiCPUPENo.
This value is NULL when HiCPUPENo is NULL.
LoCPUPEUse
FLOAT
Lowest CPUUse percentage currently associated
with any online PE.
This value is NULL if certain conditions apply. See
“Usage Notes” on page 159 for more information.
Application Programming Reference
163
Chapter 4: System PMPC APIs
MONITOR VIRTUAL SUMMARY
Field Name
Data Type
Description
LoCPUPENo
SMALLINT
VProcNo of a PE with CPUUse equal to the value
reported as LoCPUPEUse.
This value is NULL when LoCPUPEUse is NULL.
LoCPUPEProc
SMALLINT
ID of the node currently responsible for managing
the PE reported as LoCPUPENo.
This value is NULL if certain conditions apply. See
“Usage Notes” on page 159 for more information.
SessLogCount
FLOAT
Total number of sessions currently logged onto the
system. This value is usually equal to the sum of the
SessLogCount values for all PEs.
This value is NULL if certain conditions apply. See
“Usage Notes” on page 159 for more information.
SesMonitorSys
SMALLINT,
NOT NULL,
range 0-3600
seconds,
Maximum acceptable age of collected session-level
data in memory to the PM/API application or end
user.
This global rate is the default collection rate for all
MONITOR sessions. If the value is set to zero, the
collection capability is disabled.
This rate can be changed with the SET SESSION
RATE request by specifying a system-wide option
and can be saved on disk (in the version record)
when it is changed.
SesMonitorLoc
SMALLINT,
NOT NULL,
range 0-3600
seconds,
Sets the maximum acceptable age of collected
session-level data in memory for an individual
Monitor partition session that submits a
MONITOR SESSION request.
A rate of zero allows SesMonitorSys to override the
current local rate for that session.
This rate can be changed with the SET SESSION
RATE request by specifying the a LOCAL rate
change option and can be saved on disk and may be
lost during a system outage.
ResLogging
SMALLINT,
NOT NULL,
range 0- 3600
seconds
Interval in seconds at which resource usage data is
written to one or more active resource usage
database tables.
ResMonitor
SMALLINT,
NOT NULL
Interval in seconds at which all resource usage data
is collected in memory for reporting via the PM/
API.
Release
VARCHAR (29),
NOT NULL
Release number of the currently running Teradata
Database software (for example, 14.00.00.00).
This value is supplied by Teradata Database.
164
Application Programming Reference
Chapter 4: System PMPC APIs
MONITOR VIRTUAL SUMMARY
Field Name
Data Type
Description
Version
VARCHAR (32),
NOT NULL
Version number of the currently running Teradata
Database software (for example, 14.00.00.00).
This value is supplied by Teradata Database.
CollectionDate
DATE,
NOT NULL
Date the Virtual Resource cache was last refreshed.
CollectionTime
FLOAT,
NOT NULL
Time the Virtual Resource cache was last refreshed.
Sample Input
This example shows how the parcels for a MONITOR VIRTUAL SUMMARY request built by
CLIv2 look when sent to the Teradata Database. The size of the response buffer in the example
is set at the maximum (64,000 bytes), although you can set it to any size. However, a
minimum response size is 32,000 bytes.
Flavor
Length
Body
Num
Name
Length
Field
Value
0001
Req
27
Request
MONITOR VIRTUAL SUMMARY
0003
Data
6
MonVerID
2
0004
Resp
6
BufferSize
64000
Sample Output
This example shows the values returned in character text format for the MONITOR VIRTUAL
SUMMARY request. Your application program may display returned values in a different
format.
Success parcel:
StatementNo=1,
ActivityCount=1,ActivityType=93, FieldCount=37
AMPAvgCPU:
0.00
AMPAvgDisk:
HiCPUAMPUse:
HiCPUAMPNo:
HiCPUAMPProc:
0.00
3
33
HiDiskAMP:
31.13
HiDiskAMPNo:
2
HiDiskAMPProc:
33
HiDiskAMPIO:
3448.00
HiDiskAMPIONo:
3
HiDiskAMPIOProc:
33
LoCPUAMPUse:
LoCPUAMPNo:
LoCPUAMPProc:
0.00
0
33
LoDiskAMP:
29.74
LoDiskAMPNo:
0
LoDiskAMPProc:
33
LoDiskAMPIO:
3440.00
LoDiskAMPIONo:
1
LoDiskAMPIOProc:
33
PEAvgCPU:
HiCPUPEUse:
HiCPUPENo:
HiCPUPEProc:
0.00
0.00
16383
33
LoCPUPEUse:
LoCPUPENo:
LoCPUPEProc:
Application Programming Reference
30.39
AMPAvgDiskIO:
3444.25
0.00
16383
33
165
Chapter 4: System PMPC APIs
MONITOR VIRTUAL SUMMARY
SessionCnt:
SesMonitorSys:
VprocLogging:
2.00
1
600
SesMonitorLoc:
VprocMonitor:
0
30
Release: 14f.00.00.249 Version: 14f.00.00.249
Collection Date/Time:
06/15/2011 18:30:31.00
Warning and Error Messages
All users who are logged on and issue a MONITOR VIRTUAL SUMMARY request after a
system restart or after the last rate change can expect to receive one of the warnings. Typically,
the types of situations that can produce warning messages are:
•
After a system restart, before and after a collection period has expired.
If the collection period has not expired and the user issues the next MONITOR VIRTUAL
SUMMARY request, many of the values returned are NULL.
•
After the last rate change, before and after a collection period has expired.
If the collection period has not expired and the user issues the next MONITOR VIRTUAL
SUMMARY request, many of the values returned are NULL.
•
If the resource monitoring rate (ResMonitor) is not enabled, that is, if rate is set to zero.
When the user issues the next MONITOR VIRTUAL SUMMARY request, many of the
values returned are NULL.
Relationship Between MONITOR VIRTUAL SUMMARY and
SET RESOURCE RATE
The SET RESOURCE RATE request sets the ResMonitor and ResLogging rates, which are
among the responses returned by the MONITOR PHYSICAL SUMMARY or MONITOR
VIRTUAL SUMMARY request. Any change to either the ResMonitor or ResLogging rate
results in changes in the corresponding response returned by the MONITOR VIRTUAL
SUMMARY or MONITOR PHYSICAL SUMMARY request.
You must set ResMonitor to a nonzero rate for MONITOR PHYSICAL SUMMARY or
MONITOR VIRTUAL SUMMARY to return meaningful resource utilization data. A zero
ResMonitor rate returns NULL values for resource utilization information.
Relationship Between MONITOR VIRTUAL SUMMARY and
SET SESSION RATE
Changes to the session-level rates (global and local) specified by SET SESSION RATE are
reported in the data returned by MONITOR PHYSICAL SUMMARY or MONITOR
VIRTUAL SUMMARY.
Note: The local rate reported is your own local rate. If the local rate is not set, the local rate is
reported as zero.
As more session-level monitoring is done (by setting a faster SET SESSION RATE), the
resulting overhead may increase the level of CPU usage (reported in MONITOR PHYSICAL
166
Application Programming Reference
Chapter 4: System PMPC APIs
MONITOR VIRTUAL SUMMARY
SUMMARY or MONITOR VIRTUAL SUMMARY data) by your system. However, this may
depend on the size of the rate change and the type of work done by other sessions.
Relationship Between MONITOR VIRTUAL SUMMARY and
MONITOR VIRTUAL CONFIG
Use MONITOR VIRTUAL SUMMARY with the MONITOR VIRTUAL CONFIG request for
an overall system status. These are low overhead requests.
•
Execute the MONITOR VIRTUAL SUMMARY request every 5 or 10 minutes for a lowcost, continuous monitoring of your system.
•
Execute the MONITOR VIRTUAL CONFIG request to get a picture of your system
configuration at defined times, such as at the beginning of a day, various times during the
day, or when the system is down.
For information on this PMPC CLIv2 request relationship, see “Relationship Between
MONITOR VIRTUAL CONFIG and MONITOR VIRTUAL SUMMARY” on page 145.
Application Programming Reference
167
Chapter 4: System PMPC APIs
MONITOR WD
MONITOR WD
Purpose
Returns a subset of the RSS ResUsageSps data.
Input Data
Element
Data Type
Description
IndByte
BYTE
Indicator bits that specify which fields to treat as NULL if
you are using indicator mode.
Each bit in the byte corresponds to one field in the input
data.
If data is supplied for that field, then set the bit to zero.
If the data for that field is NULL (that is, there is no data
supplied for that field), then set the bit to 1.
Note: The IndByte field is only required if the PM/API
request is submitted in indicator mode.
mon_ver_id
SMALLINT,
NOT NULL
MONITOR software version ID. This must be version 9
or later.
For a general explanation of monitor version choices, see
“MONITOR VERSION” on page 136.
Monitor Privileges
To use this request, you must have the MONRESOURCE privilege as part of your default role
or this privilege must be granted directly to you.
For more information on roles and privileges, see Database Administration and Security
Administration.
Usage Notes
The data returned through MONITOR WD is ResUsageSps data from the RSS memory buffer.
You can use Teradata Viewpoint, CNS commands via Database Window, or SET RESOURCE
RATE to enable RSS collection.
168
Application Programming Reference
Chapter 4: System PMPC APIs
MONITOR WD
On SLES 10 or earlier systems ...
On SLES 11 or later systems ...
the data in the buffer is summarized to unique
VprType, PGId, and PPId field values.
the data in the buffer is summarized to unique
service-level-goal-driven Priority Scheduler
workload definition ID (pWDid) and VprType
field values. For a description of the pWDid
field, see Resource Usage Macros and Tables. For
details on the service-level-goal-driven Priority
Scheduler WD, see Teradata Viewpoint User
Guide.
any Performance Group that is not assigned to a
Workload Definition returns a WDId field value
of zero.
the WDId and pWDid fields return valid ID
values.
Note: Zero is a valid value for the pWDid field.
For information on the pWDid field, see the
PGId field in the following table.
if Teradata ASM Workloads rule is not enabled,
the WDId fields in all rows contain zeros.
Teradata ASM Workloads rule is always enabled.
For information on Teradata ASM rules, see Teradata Viewpoint User Guide.
Parcels
Parcel Sequence
Parcel
Flavor
Length
(Bytes)
Comments/Key Parcel Body Fields
Success
8
18 to 273
Statement No =1
ActivityCount = 1
ActivityType = PCLMONWDRESRSTMT
(202)
DataInfo
71
6 to 64100
Optional: this parcel is present if request was
IndicData parcel.
Record
10
• 5 to 64100
(record mode)
• 11 to 64100
(indicator
mode)
Depending on the request (Data or
IndicData) data is returned in record or
indicator mode. See “Statement Type: 1” on
page 170 for details on the data returned.
EndStatement
11
6
StatementNo = 2-byte integer
Success
8
18 to 273
Statement No =2
ActivityCount = Number of Record parcels
in statement 2
ActivityType = PCLMONWDRESRSTMT
(202)
DataInfo
Application Programming Reference
71
6 to 64100
Optional: this parcel is present if request was
IndicData parcel.
169
Chapter 4: System PMPC APIs
MONITOR WD
Parcel Sequence
Parcel
Flavor
Length
(Bytes)
Record
10
• 5 to 64100
(record mode)
• 11 to 64100
(indicator
mode)
Depending on the request (Data or
IndicData) data is returned in Record or
indicator mode. See “Statement Type: 2” on
page 170 for details on the data returned.
EndStatement
11
6
StatementNo = 2-byte integer
End Request
12
4
None
Comments/Key Parcel Body Fields
Statement Type: 1
The response to the first statement results in a Record parcel containing the fields below.
Field Name
Data Type
Description
SampleSec
SMALLINT,
NOT NULL
Duration of the collection period in seconds.
AMPNodes
SMALLINT,
NOT NULL
Number of nodes with at least one online AMP.
PENodes
SMALLINT,
NOT NULL
Number of nodes with at least one online PE.
CollectionDate
DATE,
Date the WD resource cache was last refreshed.
NOT NULL
CollectionTime
FLOAT,
NOT NULL
Time the WD resource cache was last refreshed.
Statement Type: 2
The second statement of the response results in multiple Record parcels.
For more information on the following columns, see the “ResUsageSps Table” and the
“ResSpsView” in Resource Usage Macros and Tables.
Field Name
Data Type
Description
PPId
SMALLINT,
NOT NULL
• On SLES 10 or earlier systems, this field
returns the Performance Period ID.
• On SLES 11 or later systems, this field is
obsolete and returns a value of zero.
PGId
SMALLINT,
NOT NULL
• On SLES 10 or earlier systems, this field
returns the Performance Group ID.
• On SLES 11 or later systems, this field
returns the pWDid value.
170
Application Programming Reference
Chapter 4: System PMPC APIs
MONITOR WD
Field Name
Data Type
Description
VprType
VARCHAR (4),
NOT NULL
Type of vproc:
INTEGER,
NOT NULL
WD ID.
WDId
• AMP
• PE
• MISC
Note:
• On SLES 10 or earlier systems, if Teradata
ASM Workloads rule is not enabled, the
WDId fields in all rows return zeros.
• On SUSE Linux Enterprise Server 11 or later
systems, Teradata ASM Workloads rule is
always enabled. For information on Teradata
ASM rules, see Teradata Viewpoint User
Guide.
AGId
SMALLINT,
NOT NULL
• On SLES 10 or earlier systems, this field
returns the Allocation Group ID.
• On SLES 11 or later systems, this field is
obsolete and returns a value of zero.
RelWgt
SMALLINT,
NOT NULL
• On SLES 10 or earlier systems, this field
returns the Active Relative Weight. That is,
the dynamically assigned relative weight that
considers, in its calculation, the activity of all
other Allocation Groups present on the
system. The RelWgt field constantly changes,
unlike the relative weight assignment the
Database Administrator assigns in the
Teradata Viewpoint Workload Designer
portlet.
RelWgt is the average relative weight of active
online nodes (that is, divide the sum of the
non-zero RelWgt by the count of online
nodes with the non-zero RelWgt).
• On SLES 11 or later systems, this field is
obsolete and returns a value of zero.
NumTasks
INTEGER,
NOT NULL
Average number of tasks of online nodes. The
field is the result of:
NumTasks = SUM of (NumTasks-i) / N
where:
• NumTasks-i is the number of tasks:
• On SLES 10 or earlier systems, assigned to
the PG at the end of the reporting period.
• On SLES 11 or later systems, assigned to
the WD at the end of the reporting period.
• i varies from 1 to N, where N is the number of
online nodes.
Application Programming Reference
171
Chapter 4: System PMPC APIs
MONITOR WD
Field Name
Data Type
Description
QWaitTime
FLOAT,
NOT NULL
Total wait time in milliseconds that work
requests waited on an input queue before being
serviced.
QWaitTimeMax
FLOAT,
NOT NULL
Maximum time in milliseconds that work
requests waited on an input queue before being
serviced.
The field is the result of:
QWaitTimeMax = MAX (QWaitTimeMax-i)
where:
• QWaitTimeMax-i is QWaitTimeMax in each
online node.
• i varies from 1 to N, where N is the number of
online nodes.
CPUUserPct
FLOAT,
NOT NULL
Weighted average of CPUUserPct of each node.
This field is the result of:
CPUUserPct = SUM of (CPUUserPct-i *
ScalingFactor-i) / SUM of (ScalingFactor-i)
where:
• CPUUserPct-i is calculated as:
CPUUServAwt + CPUUServDisp +
CPUUServMisc + CPUUExecAwt +
CPUUExecDisp + CPUUExecMisc) * 100 /
(NCPUs*Centisecs*10)
Note: NCPUs is the number of CPUs in the
node.
• i varies from 1 to N, where N is the number of
online nodes.
• ScalingFactor-i is the node CPU
normalization factor in each node.
Note: The CPU times are in milliseconds.
The Parser CPU times are included in the
Dispatcher CPU times.
172
Application Programming Reference
Chapter 4: System PMPC APIs
MONITOR WD
Field Name
Data Type
Description
WorkMsgMaxDelay
FLOAT,
NOT NULL
General indicator only. This field is result of the
following calculation:
WorkMsgMaxDelay = MAX
(WorkMsgMaxDelay-i)
where:
• WorkMsgMaxDelay-i is calculated in each
online node as:
WorkMsgsendDelayMax +
WorkMsgReceiveDelayMax
• i varies from 1 to N, where N is the number of
online nodes.
Note: WorkMsgMaxDelay does not represent
the subtotal of the same message on the send and
receive side.
WorkTypeInuseMax
INTEGER,
NOT NULL
Total of the AMP Worker Task (AWT) columns:
WorkTypeInuseMax = MAX
(WorkTypeInuseMax-i)
where:
• WorkTypeInuseMax-i is the sum of
WorkTypeMax00 through WorkTypeMax15
in each node.
• i varies from 1 to N, where N is the number of
online nodes.
WorkTimeInuseAvg
FLOAT,
NOT NULL
Average number of AWTs used. This field is
result of:
WorkTimeInuseAvg = SUM of (WorkTimeInuse-i)
/N
where:
• WorkTimeInuse-i is calculated in each online
node as:
WorkTimeInuse/(Centisecs * 10 * NCPUs)
Note: NCPUs is the number of CPUs in the
node.
• i varies from 1 to N, where N is the number of
online nodes.
Note: This value is available in the ResSpsView
view as AwtUsedAvg.
IODelay
FLOAT,
NOT NULL
Number of I/Os that are delayed. This field is
result of:
ProcBlksFsgRead + ProcBlksFsgWrite +
ProcBlksFsgNIOs
Application Programming Reference
173
Chapter 4: System PMPC APIs
MONITOR WD
Field Name
Data Type
Description
IODelayTime
FLOAT,
NOT NULL
Total time the I/O is delayed for. This field is the
result of:
ProcWaitFsgRead + ProcWaitFsgWrite +
ProcWaitFsgNIOs
PhysicalRead
FLOAT,
NOT NULL
Number of physical reads performed for this
period. This field is the result of:
FilePDbAcqReads + FilePDbPreReads +
FilePCiAcqReads + FileSDbAcqReads +
FileSCiAcqReads + FileTJtAcqReads +
FileAPtAcqReads + FilePCiPreReads +
FileSDbPreReads + FileSCiPreReads +
FileTJtPreReads + FileAPtPreReads
PhysicalReadKB
FLOAT,
NOT NULL
Number of physical reads in KB performed for
this period. This field is result of:
FilePDbAcqReadKB + FilePDbPreReadKB +
FilePCiAcqReadKB + FileSDbAcqReadKB +
FileSCiAcqReadKB + FileTJtAcqReadKB +
FileAPtAcqReadKB + FilePCiPreReadKB +
FileSDbPreReadKB + FileSCiPreReadKB +
FileTJtPreReadKB + FileAPtPreReadKB
PhysicalWrite
FLOAT,
NOT NULL
Number of physical writes performed for this
period. This field is result of:
FilePDbFWrites + FilePCiFWrites +
FileSDbFWrites + FileSCiFWrites +
FileTJtFWrites + FileAPtFWrites
PhysicalWriteKB
FLOAT,
NOT NULL
Number of physical writers in KB performed for
this period. This field is result of:
FilePDbFWriteKB + FilePCiFWriteKB +
FileSDbFWriteKB + FileSCiFWriteKB +
FileTJtFWriteKB + FileAPtFWriteKB
LogicalRead
FLOAT,
NOT NULL
Number of logical reads performed for this
period. This field is result of:
FilePDbAcqs + FilePDbPres + FilePCiAcqs +
FileSDbAcqs + FileSCiAcqs + FileTJtAcqs +
FileAPtAcqs + FilePCiPres + FileSDbPres +
FileSCiPres + FileTJtPres + FileAPtPres
LogicalReadKB
FLOAT,
NOT NULL
Number of logical reads in KB performed for this
period. This field is result of:
FilePDbAcqKB + FilePDbPresKB +
FilePCiAcqKB + FileSDbAcqKB + FileSCiAcqKB
+ FileTJtAcqKB + FileAPtAcqKB +
FilePCiPresKB + FileSDbPresKB +
FileSCiPresKB + FileTJtPresKB + FileAPtPresKB
174
Application Programming Reference
Chapter 4: System PMPC APIs
MONITOR WD
Field Name
Data Type
Description
LogicalWrite
FLOAT,
NOT NULL
Number of logical writes performed for this
period. This field is result of:
FilePDbDyRRels + FilePCiDyRRels +
FileSDbDyRRels + FileSCiDyRRels +
FileTJtDyRRels + FileAPtDyRRels
LogicalWriteKB
FLOAT,
NOT NULL
Number of logical writes in KB performed for
this period. This field is result of:
FilePDbDyRRelKB + FilePCiDyRRelKB +
FileSDbDyRRelKB + FileSCiDyRRelKB +
FileTJtDyRRelKB + FileAPtDyRRelKB
VPId
FLOAT,
NOT NULL
Virtual partition ID.
WaitIO
FLOAT,
NOT NULL
Number of milliseconds tasks in WD waited for
I/O over the reporting period.
WaitIO is updated when the wait for I/O is
completed.
WaitOther
FLOAT,
NOT NULL
Number of milliseconds tasks in WD waited for
reasons other than I/O over the reporting period
(for example, a task waiting for a message).
WaitOther is updated when wait is completed.
CPURunDelay
FLOAT,
NOT NULL
Number of milliseconds tasks in the WD sat in
the CPU runqueue waiting to run over the
reporting period.
This data can be used in determining demand for
the virtual partition and WD Share workload
management method (see “Glossary” for a
description of this method). If the CPU and I/O
percentages for a virtual partition or WD are
below their relative share values and the
CPURunDelay values are low, there was
insufficient demand to meet the share
percentage. If the CPURunDelay values are high,
higher tier SQL requests were allocated more
resources so that there were insufficient
resources remaining to allocate to SQL requests
in this WD to meet its relative share.
Note: A virtual partition divides a system so that
a percentage of resources are allocated to a
collection of workloads. A virtual partition can
consist of WDs from all management methods.
IOSubmitted
FLOAT,
NOT NULL
Number of I/Os submitted on behalf of this WD.
IOSubmittedKB
FLOAT,
NOT NULL
KB of I/O submitted on behalf of this WD.
Application Programming Reference
175
Chapter 4: System PMPC APIs
MONITOR WD
Field Name
Data Type
Description
IOCompleted
FLOAT,
NOT NULL
Number of I/Os completed on behalf of this WD.
IOCompletedKB
FLOAT,
NOT NULL
KB of I/O completed on behalf of this WD.
IOCriticalSubmitted
FLOAT,
NOT NULL
Number of I/Os submitted with critical status.
These I/Os execute at top priority instead of
being based on the I/O priority of the SQL
request.
IOCriticalSubmittedKB
FLOAT,
NOT NULL
KB of I/O submitted with critical status. These
I/Os execute at top priority instead of being
based on the I/O priority of the SQL request.
DecayLevel1IO
FLOAT,
NOT NULL
Number of times SQL requests in the WD hit
decay level 1 due to I/O.
Note: DecayLevel1IO is used for Timeshare
WDs only (see “Glossary” for a description of
this workload management method).
DecayLevel2IO
FLOAT,
NOT NULL
Number of times SQL requests in the WD decay
level 2 due to I/O.
Note: DecayLevel2IO is used for Timeshare
WDs only (see “Glossary” for a description of
this workload management method).
DecayLevel1CPU
FLOAT,
NOT NULL
Number of times SQL requests in the WD hit
decay level 1 due to CPU.
Note: DecayLevel1CPU is used for Timeshare
WDs only (see “Glossary” for a description of
this workload management method).
DecayLevel2CPU
FLOAT,
NOT NULL
Number of times SQL requests in the WD hit
decay level 2 due to CPU.
Note: DecayLevel2CPU is used for Timeshare
WDs only (see “Glossary” for a description of
this workload management method).
TacticalExceptionIO
FLOAT,
NOT NULL
Number of times SQL requests in the WD hit a
tactical per-node exception due to I/O.
An exception, used only for Tactical WDs, is
created for each Tactical WD (see “Glossary” for
a description of this workload management
method).
TacticalExceptionCPU
FLOAT,
NOT NULL
Number of times SQL requests in the WD hit a
tactical per-node exception due to CPU.
Note: TacticalExceptionCPU is used for Tactical
WDs only (see “Glossary” for a description of
this workload management method).
176
Application Programming Reference
Chapter 4: System PMPC APIs
MONITOR WD
Sample Input
The following example shows how the parcels for a MONITOR WD request, built by CLIv2,
appear when sent to the Teradata Database server.
Note: In this example, the size of the response buffer in the example is set at the maximum
(64,000 bytes), although you can set it to any size. However, a minimum response size is
32,000 bytes.
Flavor
Length
Body
Num
Name
Bytes
Field
Value
0001
Req
14
Request
MONITOR WD
0003
Data
6
MonVerID
9
0004
Resp
6
Buffer Size
64000
Sample Output
The MONITOR WD request returns values approximately as shown below when Teradata
ASM Workloads rule is enabled (see Teradata Viewpoint User Guide for information on this
rule):
Note: The Monitor WD request commonly returns values in text character format. Your
application program may return the values in a different format or display.
ResRate: 30;
AMP Nodes: 1;
PE Nodes: 1
Collection Date/Time: 06/15/2011 18:34:01.00
PGId VT
PP
WDId AGId RWgt
NPrc
VPId
CPUUsrPct
IODelay
Reserved1
WaitIO
IOsubmit
Decay1IO
==== ==== ==== =========
QWaitTime
IODelayTi
Reserved2
WaitOther
IOSubmKB
Decay2IO
=========
QWTimeMax
PhyRead
LogRead
CPURunDly
IOComplet
Decay1CPU
=========
WkMsgMaxD WTypeMax
PhyReadMB PhyWrite
LogReadMB LogWrite
WTimeAvg
PhyWriteMB
LogWriteMB
IOComplKB IOCriticl IOCritKB
Decay2CPU TacExcpIO TacExcpCPU
========= ========= =========
SUCCESS parcel:
StatementNo=2,
ActivityCount=10,
ActivityType=202, FieldCount=39
0 AMP
12
0
0
0
132
1
98.56
0.00
0.00
0.00
4
3.99
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
300.00
7558.00 82602.00
151.00
9664.00
151.00
9664.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
-------------------------------------------------------------------------0 PE
0
0.00
0.00
0.00
0.00
0
0.00
12
0
0
0.00
0.00
0.00
0.00
0.00
0.00
33
0.00
0.00
0.00
0.00
0.00
0.00
1
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
-------------------------------------------------------------------------250 AMP
0
0.00
0.00
0.00
0.00
1
1.00
0
0
0
0.00
0.00
0.00
0.00
0.00
0.00
2288
0.00
0.00
0.00
0.00
0.00
0.00
100
0.00 119692.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
-------------------------------------------------------------------------251 MISC
0
0.00
0.00
0.00
0.00
0
0.00
Application Programming Reference
177
Chapter 4: System PMPC APIs
MONITOR WD
0
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
-------------------------------------------------------------------------251 AMP
0
0.00
0.00
0.00
0.00
0
0.00
0
0
0
0.00
0.00
0.00
0.00
0.00
0.00
892
0.00
0.00
0.00
0.00
0.00
0.00
100
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
-------------------------------------------------------------------------254 MISC
0
0.32
0.00
0.00
0.00
0
0.00
0
0
0
0.00
0.00
0.00
0.00
0.00
0.00
4400
0.00
0.00
0.00
0.00
0.00
0.00
102
0.00 218950.00
318.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
-------------------------------------------------------------------------254 AMP
0
0.00
0.00
0.00
0.00
0
0.01
0
0
0
0.00
0.00
0.00
0.00
0.00
0.00
79844
0.00
0.00
0.00
0.00
0.00
0.00
102
359.00 3511485.00
1701.00
38.00
228.00
38.00
228.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
-------------------------------------------------------------------------254 PE
0
0.00
0.00
0.00
0.00
0
0.00
0
0
0
0.00
0.00
0.00
0.00
0.00
0.00
58034
0.00
0.00
0.00
0.00
0.00
0.00
102
272.00 2644347.00
399.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
-------------------------------------------------------------------------255 MISC
0
0.09
0.00
0.00
0.00
0
0.00
0
0
0
0.00
0.00
0.00
0.00
0.00
0.00
2992
0.00
0.00
0.00
0.00
0.00
0.00
101
0.00 548164.00
2922.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
-------------------------------------------------------------------------255 AMP
0
0.03
0.00
0.00
0.00
0
0.00
0
0
0
0.00
0.00
0.00
0.00
0.00
0.00
3520
0.00
0.00
0.00
0.00
0.00
0.00
101
0.00 315555.00 45137.00
13567.00 1722001.00 13569.00 1722255.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
.
.
.
178
0
0
160
100
Application Programming Reference
Chapter 4: System PMPC APIs
SET RESOURCE RATE
SET RESOURCE RATE
Purpose
Sets either the ResMonitor or ResLogging rate.
Input Data
Element
Data Type
Description
IndByte
BYTE
Indicator bits that specify which fields to treat as NULL
if you are using indicator mode.
Each bit in the byte corresponds to one field in the input
data.
If data is supplied for that field, then set the bit to zero.
If the data for that field is NULL (that is, there is no data
supplied for that field), then set the bit to 1.
Note: The IndByte field is only required if the PM/API
request is submitted in indicator mode.
mon_ver_id
SMALLINT,
NOT NULL
MONITOR software version ID. This can be version 2 or
later.
For a general explanation of monitor version choices, see
“MONITOR VERSION” on page 136.
sample_rate
SMALLINT,
NOT NULL,
range 0-3600 secs
Value of the collection rate. This field is used either to
collect resource data or to log resource data to the
resource usage tables.
You can specify one of the following:
• The ResMonitor rate value if you want to change the
resource monitoring rate.
• The ResLogging rate value if you want to change the
resource logging rate.
Note: The value should be an integral divisor of
3600.
• Zero to turn off the resource collection or logging.
log_change
VARCHAR (1)
Indicator of whether this rate applies to the ResLogging
or ResMonitor rate:
• Y or y = ResLogging rate
• N, n, NULL, or blank = ResMonitor rate
virtual_change
Application Programming Reference
VARCHAR (1)
Note: This field is obsolete.
179
Chapter 4: System PMPC APIs
SET RESOURCE RATE
Monitor Privileges
To use this request, you must have the SETRESRATE privilege as part of your default role or
this privilege must be granted directly to you.
For more information on roles and privileges, see Database Administration and Security
Administration.
Usage Notes
You can set the ResMonitor or ResLogging rates using the SET RESOURCE RATE request. For
a description of these rates, see “Data Collection” on page 21.
ResMonitor and ResLogging are independent of each other because you can monitor without
wanting to log to the resource usage tables, or you can log without monitoring.
Note: You can set only one ResMonitor or ResLogging rate within one SET RESOURCE RATE
request. For example, to set both the ResMonitor and ResLogging rates at the same time, you
must issue two SET RESOURCE RATE requests and specify the USING Data String
appropriately.
Resource data is placed in a memory repository separate and independent from session usage
data. Therefore, any changes in the ResMonitor rate does not impact session usage data.
Remember that resource utilization data collected by the ResMonitor rate is collected and
reported differently from session utilization data. Whereas session usage data is collected
cumulatively, resource data is collected for a particular collection period. The data reported is
based on the activity that occurred during that collection period and does not include any
cumulative data over collection periods.
There is a difference between saving statistics in the resource memory repository and
returning the data for display. Resource data can be saved after a collection rate is set to a
nonzero rate, but no return of data occurs until a MONITOR request is issued.
The ResMonitor rate and the ResLogging rate are saved on disk in the Version Record when
they are changed. For this reason, the SET RESOURCE RATE request can block if someone
else is updating the GDO control record. If a block occurs, you must wait until the block
clears.
Note: When you execute the SET RESOURCE RATE request, the change is saved in the
DBC.SW_Event_Log table (accessible from the DBC.Software_Event_LogV view) and written
to the system console running Database Windows.
Parcels
The response returned from Teradata Database contains the following sequence of parcel
types.
180
Application Programming Reference
Chapter 4: System PMPC APIs
SET RESOURCE RATE
Parcel
Sequence
Parcel
Flavor
Length
(Bytes)
Comments/Key Parcel Body Fields
Success
8
18 to 273
Activity Count = Contains previous rate.
Activity Type = 87 (PCLSETRESSR)
DataInfo
71
6 to 64100
This parcel is present if request was IndicReq
parcel; depends on the data type.
EndStatement
11
6
StatementNo: 2-byte integer
EndRequest
12
4
None
Sample Input
This example shows how the parcels for a SET RESOURCE RATE request built by CLIv2 look
when sent to the Teradata Database server using a sample_rate of 600 seconds and a
logging_change of Y. The size of the response buffer is set in the example at the maximum
(64,000 bytes), although you can set it to any size. However, a minimum response size is
32,000 bytes.
Flavor
Length
Body
Num
Name
Bytes
Field
Value
0001
Req
21
Request
SET RESOURCE RATE
0030
Data
11
MonVerID
2
SampleRate
600
LoggingChg
Y
VirtualChg
N
Buffer Size
64000
0004
Resp
6
Sample Output
With a sample_rate of 600 and a logging_change of y, this example shows the values returned in
character text format for the SET RESOURCE RATE request. Your application program may
display returned values in a different format.
Success parcel:
StatementNo: 1
ActivityType: 87
DataInfo parcel:
FieldCount: 0
EndStatement.
EndRequest.
Application Programming Reference
ActivityCount: 60
FieldCount: 0
181
Chapter 4: System PMPC APIs
SET RESOURCE RATE
Relationship Between SET RESOURCE RATE and
MONITOR PHYSICAL RESOURCE or MONITOR VIRTUAL RESOURCE
You must execute the SET RESOURCE RATE request to activate resource data collection
before you execute a MONITOR VIRTUAL RESOURCE or MONITOR PHYSICAL
RESOURCE request. This means that you must set the ResMonitor rate to nonzero. If the
ResMonitor rate is set to zero, you will receive an error message.
A change in the resource collection rate by User A, for example, may affect the data reported
by MONITOR VIRTUAL RESOURCE or MONITOR PHYSICAL RESOURCE request made
by User B. If the ResMonitor rate has been altered, User B receives a warning message when
executing a subsequent MONITOR VIRTUAL RESOURCE or MONITOR PHYSICAL
RESOURCE request.
Relationship Between SET RESOURCE RATE and
MONITOR PHYSICAL SUMMARY or MONITOR VIRTUAL SUMMARY
The SET RESOURCE RATE request sets the ResMonitor and ResLogging rates, which are
among the responses returned by the MONITOR PHYSICAL SUMMARY or MONITOR
VIRTUAL SUMMARY request. Any change to either the ResMonitor or ResLogging rate
results in changes in the corresponding response returned by the MONITOR VIRTUAL
SUMMARY or MONITOR PHYSICAL SUMMARY request.
You must set ResMonitor to a nonzero rate for MONITOR PHYSICAL SUMMARY or
MONITOR VIRTUAL SUMMARY to return meaningful resource utilization data. A zero
ResMonitor rate returns NULL values for resource utilization information.
182
Application Programming Reference
Chapter 4: System PMPC APIs
SET SESSION ACCOUNT
SET SESSION ACCOUNT
Purpose
Changes the account string for the session or for the request.
Input Data
Element
Data Type
Description
IndByte
BYTE
Indicator bits that specify which fields to treat as NULL if you
are using indicator mode.
Each bit in the byte corresponds to one field in the input data.
If data is supplied for that field, then set the bit to zero.
If the data for that field is NULL (that is, there is no data
supplied for that field), then set the bit to 1.
Note: The IndByte field is only required if the PM/API
request is submitted in indicator mode.
mon_ver_id
SMALLINT,
NOT NULL
MONITOR software version ID. This can be version 2 or
later.
For a general explanation of monitor version choices, see
“MONITOR VERSION” on page 136.
host_id
SMALLINT,
NOT NULL
ID of the host upon which the session was issued. host_id
cannot exceed 1023. A host_id of zero identifies the database
operator console. If you do not specify a valid host_id, an
error message is returned to CLIv2. Use only if you have DBA
privileges.
session_no
INTEGER,
NOT NULL
Number of the session. session_no combined with the host_id
produces a unique Session ID. If you do not specify a valid
session_no, an error message is returned to CLIv2. Use only if
you have DBA privileges.
account
VARCHAR (30),
NOT NULL
Account string for the session or request.
Application Programming Reference
183
Chapter 4: System PMPC APIs
SET SESSION ACCOUNT
Element
Data Type
Description
sess_req
VARCHAR (1)
Indicator of how the new account or priority affects requests
for a specified session.
If you specify Y or y, the change applies to all current and
future requests for a specified session. If no requests or steps
are executing, the new account/priority takes effect at the
next request, and the DBC.SessionTbl table reflects the new
account/priority for the current session.
If you specify NULL, blank, N, or n, then the change applies
to the current request for the specified session. If no request is
executing, the next request for the specified session has the
old account/priority.
Monitor Privileges
To use this request, you must have the ABORTSESSION or an equivalent privilege as part of
your default role or this privilege must be granted directly to you.
For more information on roles and privileges, see Database Administration and Security
Administration.
Usage Notes
The account or priority change is recorded in the DBC.SW_Event_Log table (accessible from
the DBC.Software_Event_LogV view) with the following text in the TEXT column:
SESSION session_no HOSTID host_id CHANGED FROM ACCOUNT account TO
ACCOUNT account ON sess_req
The EVENT_TAG field contains an event number. THEDATE and THETIME fields, which
make up the index of the DBC.SW_Event_Log table (accessible from the
DBC.Software_Event_LogV view), contain the date and time of the account/priority change.
All other fields of the table are blank.
When Teradata ASM Workloads rule is enabled, the SET SESSION ACCOUNT request will:
•
Fail and return an error.
•
Or succeed for a session, but the request in which it is running will continue to run the old
(existing) account string. Future requests will run with the new account string.
For information on Teradata ASM rules, see Teradata Viewpoint User Guide.
Parcels
The response returned from Teradata Database contains the following sequence of parcel
types:
184
Application Programming Reference
Chapter 4: System PMPC APIs
SET SESSION ACCOUNT
Parcel
Sequence
Parcel
Flavor
Length
(Bytes)
Comments/Key Parcel
Success
8
18 to 273
StatementNo = 1
ActivityCount = 1
ActivityType = 108 (SET SESSION ACCOUNT)
DataInfo
71
6 to 64100
Optional; this parcel is present if request was
IndicReq parcel.
Record
10
• 5 to 64100
(record
mode)
• 6 to64100
(indicator
mode)
This record contains the old account and an error
code.
EndStatement
11
6
StatementNo = 2-byte integer
EndRequest
12
4
None
The Data parcel sent from the host should be 39 bytes long for record mode or 40 bytes long
for indicator mode.
The Record parcel returns the following fields:
Note: The Column Name and Column Contents field values are not returned in the Record
parcel. These values are returned in an IDENTIFY request.
Element
Data Type
Description
Old Account
VARCHAR (30),
NOT NULL
Existing account string.
Error Code
INTEGER,
NOT NULL
An error code.
The Error Code column can contain any of the following return codes:
Error-Name
Code
Text
ErrPFMNoAr
3250
No access right.
ErrPFMBadSes
3256
User entered invalid session x HostId.
ErrPFMBadAcc
3292
User entered invalid account.
ErrPFMUpdSesTbl
3293
Failed to update the session table with the new
account.
ErrPFMBadSesReqInd
3294
Invalid session/request indicator value for set
session account.
Application Programming Reference
185
Chapter 4: System PMPC APIs
SET SESSION ACCOUNT
Error-Name
Code
Text
ErrPFMInvSes
3295
Invalid session.
ErrPFMTimeOut
3296
Asynchronous account change time-out.
Sample Input
This is an example of the request parcels sent from a mainframe client. It shows how the
parcels for a SET SESSION ACCOUNT request built by CLIv2 look when sent to the Teradata
Database server, where account is $Haccnt, sess_req is Y, host_id is 348, and session_no is 1000.
In this sample, the size of the response buffer is set at the maximum (64,000 bytes), although
you can set it to any size. However, a minimum response size is 32,000 bytes.
Flavor
Length
Body
Num
Name
Bytes
Field
Value
0001
Req
22
Request
SET SESSION ACCOUNT
0003
Data
45
MonVerID
2
HostId
348
SessionNo
1000
Account
$Haccnt
Session/Request
Indicator
Y
BufferSize
64000
0004
Resp
6
Sample Output
This sample shows typical values returned in character text format for SET SESSION
ACCOUNT. Your application may return values in a different format.
Success Parcel:
Statement No: 1Activity Count: 1Activity Type: 108FieldCount: 2DataInfo Parcel:Field
Count: 2Record Parcel:Parcel Flavor: 10Parcel Body Length:32OldAcct: "$MAcct", ErrorCode
= 0EndStatement.EndRequest.
186
Application Programming Reference
Chapter 4: System PMPC APIs
SET SESSION RATE
SET SESSION RATE
Purpose
Sets the global and local rates for updating session-level statistics in memory.
Input Data
Element
Data Type
Description
IndByte
BYTE
Indicator bits that specify which fields to treat as NULL if you
are using indicator mode.
Each bit in the byte corresponds to one field in the input data.
If data is supplied for that field, then set the bit to zero.
If the data for that field is NULL (that is, there is no data
supplied for that field), then set the bit to 1.
Note: The IndByte field is only required if the PM/API
request is submitted in indicator mode.
mon_ver_id
SMALLINT,
NOT NULL
MONITOR software version ID. This can be version 2 or
later.
For a general explanation of monitor version choices, see
“MONITOR VERSION” on page 136.
sample_rate
SMALLINT,
NOT NULL,
range 0-3600
seconds
Value of the collection interval. If this value is set to zero, the
collection capability is disabled.
local_change
VARCHAR (1)
Type of session to which this rate change applies.
Specify Y or y if the rate is set within a local session or N, n,
NULL, or blank if the rate applies to global queries.
Monitor Privileges
To use this request, you must have the SETSESSRATE privilege as part of your default role or
this privilege must be granted directly to you.
If you make changes to either the system or local rate, this can reset the starting point at which
data is collected. Therefore, Teradata recommends that the SETSESSRATE privilege be
granted to a restricted number of users (such as DBAs or certain application programmers)
For more information on roles and privileges, see Database Administration and Security
Administration.
Application Programming Reference
187
Chapter 4: System PMPC APIs
SET SESSION RATE
Usage Notes
You can set the SET SESSION RATE request to either a global (SesMonitorSys) or local
(SesMonitorLoc) rate. For descriptions of these rates, see “Data Collection” on page 21.
Use the local rate to collect data more frequently than the global rate. After the local rate is
done collecting data and is set back to zero, the local rate is no longer in effect. The rate in
effect then for that session becomes the global rate that has been saved on disk. The local rate
is not saved on disk, and it may be lost during a system outage. In a system outage, the
running sessions default to the global rate.
Even though you are using the local rate from your own session, session-level data is still
collected across all sessions (global). The impact of the local rate may not be transparent to
those users who are issuing MONITOR SESSION requests at the global rate. For an example,
see “Rate Scenario 2: Affects On Other Users When Increasing the Local Rate” on page 190.
If the global rate has not been set, data will not be collected by the local rate.
The following are examples of when you might want to set a local rate:
•
When your are troubleshooting an application that is hung, set the local rate to collect
more frequently than the global rate. For example, if data is being collected system-wide
every 10 minutes (or 600 seconds), setting a faster local rate of 6 seconds collects more
current information on session status and locks for the application that requires
resolution.
•
If you have coded a new application and you want to troubleshoot its implementation,
setting a more frequent local collection rate enables you to better monitor its impact on
the system.
•
For performance analysis.
In addition to altering the specified rate, this request is recorded in the DBC.SW_Event_Log
table (accessible from the DBC.Software_Event_LogV view) and also written to the DBW.
Global rate updates are recorded only in the GDO control record.
Session usage data is placed in a separate, independent memory repository from the processor
resource data. As a result, any changes in the session monitoring rate have no impact on the
resource data. However, a user who sets a local collection rate could affect the session usage
data that other users see because all session usage data is stored in the same memory
repository.
Session-level usage data is collected differently from the way processor resource usage data is
collected. Processor resource usage data is collected for a particular collection period, while
session usage data is collected cumulatively. The report can include cumulative data over
many collection periods.
Monitoring a system may cause some form of global performance degradation. To limit the
overhead cost, Teradata recommends that you set the global rate at 3600 seconds (or 1 hour)
for general system monitoring. To perform problem analysis more quickly, you can set a more
frequent local rate. After the analysis is done, terminate the session or set the local rate to zero.
The lower global rate takes effect again in that session.
188
Application Programming Reference
Chapter 4: System PMPC APIs
SET SESSION RATE
If both the global and local rates are set to zero at the same time, session-level monitoring
stops, and all accumulated session-level data is discarded. PM/API starts collecting
session-level data again the next time the global or local rate is reset to a nonzero value.
To avoid confusion, Teradata recommends that applications not query data more frequently
than the faster of the two rates. If MONITOR SESSION requests are executed too frequently,
one of the following may occur:
•
The user application program sees duplicated data and CPU resources are wasted.
•
The user application program sees data showing the result of an alteration caused by
another user.
It is also recommended that you restrict the SET SESSION RATE privilege to the database
administrator or system administrator.
A change to the global rate may cause a block because:
•
Someone else is changing the global rate at the same time.
Rate change requests are queued and processed in the order received because the system
does not allow different rates to be used on different processors. The system ensures that
all processors use the same rate.
•
The GDO control record is being updated.
Rate Scenario 1: Affects on Other Users When Increasing the Global Rate
User A has the SET SESSION RATE privilege. User B does not.
Step
Action
1
User A changes the global rate from 10 minutes to 5 minutes at 8:55. User A now
requests data every 5 minutes instead of 10 minutes.
2
User A makes a request at 8:57. Data returned shows data from the interval of 8:50
to 8:57, plus the cumulative data from 8:00 to 8:50. By forcing an update of the data
at 8:57, User A has reset the collection start time (or time-stamp) to 8:57 because
the current time (8:57) minus the time-stamp of the data (8:50) is greater than the
session collection rate of 5 minutes. Resetting the collection start time means
resetting the time from which the interval is calculated to 8:57.
3
User A makes a next request at 9:00. Data returned is the same data that was
returned at 8:57. The reason is that the current session-level data that was available
was considered current, that is, the age of the data (9:00 - 8:57 = 3) is less than the
session collection rate of 5.
If User B is not aware that the global rate has been changed to 5 minutes, then the application
for User B continues to request data every 10 minutes. User B is requesting data at a less
frequent rate than the data collection rate. User B may not notice a difference in data, since the
data is cumulative. However, since all session resource data is deposited in the same memory
pool, a change in collection rate by another user could affect the data User B sees.
Application Programming Reference
189
Chapter 4: System PMPC APIs
SET SESSION RATE
Although it is transparent to the user, the user data impacted depends on which user request is
received first. This usually happens when the user is not requesting data at the same rate as
data is collected.
For example, User A makes a request at 9:00 and the request made by User A is received before
the request (also at 9:00) made by User B. As described previously, User A sees data returned
that is cumulative from 8:00 to 8:57.
Step
Action
1
The request made by User B at 9:00 is queued. User B gets the cumulative data from
8:00 to 8:57 because User A made a request at 8:57. The request made by User B does
not trigger an update because the request made by User A resets the time-stamp (or
start time) to 8:57, and the elapsed time between 8:57 to 9:00 is less than 5 minutes
(the data collection rate of the session). Thus, User B gets data from 8:50 to 8:57,
plus the cumulative data from 8:00 to 8:50. In this case, there is no difference in the
data User A or User B sees as a result of the request order.
2
User B gets a warning message that the rate has been changed to 5 minutes. User B
can check to see what the new global rate is if MONITOR SESSION is being run.
The data returned in the first Record parcel is the SampleSec, which indicates the
duration of the collection period in seconds. User B can observe that SampleSec
reports 300 seconds (or 5 minutes) instead of 600 seconds (or 10 minutes).
Rate Scenario 2: Affects On Other Users When Increasing the Local Rate
Users A and B are requesting session-level data at the same rate as data is collected.
Step
Action
1
User A wants to troubleshoot a new application program and at 9:00 sets a local rate
of 1 minute within his session. The local rate now overrides the global rate of 10
minutes within the session for User A. User A now requests data every 1 minute
instead of 10 minutes.
2
User A makes a request at 9:01. Data returned shows data from the interval of 9:00
to 9:01 (because User A has reset the session beginning collection time to 9:00), plus
the cumulative data from 8:00 to 9:00.
3
User A makes the next request at 9:02. Data returned shows data from the interval of
9:01 to 9:02, plus the cumulative data from 8:00 to 9:01. From now on, responses to
queries for User A returns data updated every 1 minute.
The actions made by User A in setting a local rate does not change the current global
collection rate of 10 minutes.
The way the session for User B is calculating its collection interval does not change. Therefore,
the collection rate and request rate for User B continues at 10-minute intervals. However,
since all session usage data is stored in the same memory repository, the more frequent
collection for User A may affect the cumulative data that User B might see.
190
Application Programming Reference
Chapter 4: System PMPC APIs
SET SESSION RATE
User B may see more dynamic data than previously and receive more data than expected.
Each of the requests made by User B could potentially include data from one collection period
mixed in with data from a subsequent collection period that was initiated by a different use. In
this case, the 1-minute interval collection for User A.
While the local rate for User A is in effect, User B makes a request at 9:00. Data returned shows
data from the interval of 8:50 to 9:00, plus the cumulative data from 8:00 to 8:50.
If User B were to make a request at 9:04, User B would see data returned from 9:00 to 9:04,
plus the cumulative data from 8:00 to 9:00. Because of the local data collecting for User A,
User B can take advantage of the faster collection rate and thus receive more data than
expected.
On the other hand, if the local rate for User A were not in effect and User B makes a request at
9:04, the data returned would be from the interval of 8:00 to 9:00 only.
Rate Scenario 3: How Request Order Affects Data Reported
The DBA sets the global rate at 8:00 a.m. to collect every 10 minutes. User A decides to reset
the global or global rate from 10 minutes to 5 minutes. In addition, User B decides to request
session-level data at a different rate than the data collection rate.
Step
Action
1
User A resets the global session collection rate to 300 seconds (or 5 minutes) at 9:00,
thus setting the timestamp for any current data to 9:00.
2
At 9:00, User A also sets a local collection rate of 1 minute for his session.
3
User B makes a request for data at 9:05:25.
4
User B receives the cumulative data from 8:00 to 9:05:25 and, in the process, resets
the data time-stamp to 9:05:25.
User A does not know that the data timestamp has been altered by the request made by User B
because User A had sent in a request immediately after the request made by User B.
The request made by User A for data at 9:06:00 is queued behind the request made by User B
of 9:05:25. Because the current data is considered current (9:06:00 - 9:05:25 = 0:00:35, which is
less than the local collection rate of 1 minute), User A receives the same data (from 8:00 to
9:05:25) that User B received.
In this case, the request order affects the data User A receives. If not the earlier request made
by User B, User A could have received data from the 8:00 to 9:06 interval, which User A
probably expected.
Rate Scenario 4: Different Collection and Request Rates
Users A and B are running different application programs and are monitoring the applications
with MONITOR SESSION and/or MONITOR VIRTUAL SUMMARY. User A has the SET
Application Programming Reference
191
Chapter 4: System PMPC APIs
SET SESSION RATE
SESSION RATE privilege. User A is requesting session-level data at a different rate from the
rate at which data is collected.
User A is using the global collection rate of 10 minutes set by the DBA. However, User A wants
to troubleshoot a new program and decides to set the application program to request data
every 6 seconds.
Clearly, User A is requesting data more frequently than the data collection rate. Every 6
seconds, User A sees a data display that will show the same data until the 10-minute interval
has elapsed.
In this case, data returned from monitoring the session for User A would probably be more
meaningful if User A had set the global collection rate to the same rate as the request rate.
Parcels
The response returned from the Teradata Database contains the following sequence of parcel
type:
Parcel
Sequence
Parcel
Flavor
Length
(Bytes)
Comments/Key Parcel Body Fields
Success
8
18 to 273
Activity Count = Previous rate
Activity Type = 83 (PCLSETSESSR)
DataInfo
71
6 to 64100
This parcel is present if request was IndicReq parcel;
depends on the data type.
EndStatement
11
6
StatementNo: 2-byte integer
EndRequest
12
4
None
Sample Input
This example shows how the parcels for a SET SESSION RATE request built by CLIv2 look
when sent to the Teradata Database server with a sample_rate of 6 and a local_change of y. In
the example, the size of the response buffer is set at the maximum (64,000 bytes), although
you can set it to any size. However, a minimum response size is 32,000 bytes.
Flavor
Body
Num
Name
Bytes
Field
Value
0001
Req
20
Request
SET SESSION RATE
0003
Data
9
MonVerID
2
SampleRate
6
LocalChg
Y
BufferSize
64000
0004
192
Length
Resp
6
Application Programming Reference
Chapter 4: System PMPC APIs
SET SESSION RATE
Sample Output
With a sample_rate of 6 and a local_change of y, this example shows the values returned in
character text format for the SET SESSION RATE request. Your application program may
display returned values in a different format.
Success parcel:
StatementNo: 1
ActivityType: 83
DataInfo parcel:
FieldCount: 0
EndStatement.
EndRequest.
ActivityCount: 0
FieldCount: 0
Relationship Between SET SESSION RATE and MONITOR SESSION
You must execute the SET SESSION RATE request to activate session-level data collection
before you execute a MONITOR SESSION request. This means that either the global rate or
local rate must be set to nonzero. If both rates are set to zero, an error message is returned.
For information on this PMPC CLIv2 request relationship, see“Relationship Between
MONITOR SESSION and SET SESSION RATE” on page 126.
Relationship Between SET SESSION RATE and
MONITOR PHYSICAL SUMMARY or MONITOR VIRTUAL SUMMARY
Changes to the session-level rates (global and local) specified by SET SESSION RATE are
reported in the data returned by MONITOR PHYSICAL SUMMARY or MONITOR
VIRTUAL SUMMARY.
Note: The local rate reported is your own local rate. If the local rate is not set, the local rate is
reported as zero.
As more session-level monitoring is done (by setting a faster SET SESSION RATE), the
resulting overhead may increase the level of CPU usage (reported in MONITOR PHYSICAL
SUMMARY or MONITOR VIRTUAL SUMMARY data) by your system. However, this may
depend on the size of the rate change and the type of work done by other sessions.
Application Programming Reference
193
Chapter 4: System PMPC APIs
Open APIs (SQL Interfaces)
Open APIs (SQL Interfaces)
This section describes how to access PMPC data through SQL interfaces consisting of UDFs.
The PMPC UDFs, like the PMPC CLIv2 requests, are used to monitor system and session-level
performance and set collection and logging rates. However, the PMPC UDFs can be invoked
from any application.
The PMPC UDFs provide similar functionality to the PMPC CLIv2 requests.
Note: When issuing PMPC UDFs, you do not need to fully qualify them by the database
name, SYSLIB. They are automatically searched by the DBS in the SYSLIB database.
For examples of PMPC UDFs, see the following topics.
194
Application Programming Reference
Chapter 4: System PMPC APIs
AbortListSessions
AbortListSessions
Purpose
Returns the status information of the aborted sessions.
Definition
REPLACE FUNCTION SYSLIB.AbortListSessions
(HostIdIn
SMALLINT,
UserNameIn VARCHAR(128) CHARACTER SET LATIN,
SessionNoIn INTEGER,
LogoffSessions VARCHAR(1) CHARACTER SET LATIN,
UserOverride VARCHAR(1) CHARACTER SET LATIN
)
RETURNS TABLE
(HostId SMALLINT,
SessionNo INTEGER,
UserName VARCHAR(128),
AbortStatus CHAR CHARACTER SET LATIN
)
.
.
.
;
Input Parameters
Parameter
Description
HostIdIn
Logical ID of a host (or client) with sessions logged on.
A value of -1 indicates all hosts.
UserNameIn
User name of the specified session.
An asterisk (*) or NULL indicates all users.
SessionNoIn
ID of the session to abort.
A value of zero indicates all sessions.
LogoffSessions
Indicator of whether to log off sessions to Teradata Database in addition to
aborting them:
• Y = Log off and abort sessions.
• N or NULL = Do not log sessions off.
UserOverride
Application Programming Reference
Indicator of whether to override an ABORT SESSION failure:
195
Chapter 4: System PMPC APIs
AbortListSessions
Parameter
Description
UserOverride
• Y = Override the ABORT SESSION request to fail in any of the following
cases:
• An identified session is being session-switched.
• An identified session is executing its own ABORT SESSION request.
• An identified session has a PEState of IDLE: IN-DOUBT as a result of a
2PC.
Note: Sessions are marked IN-DOUBT by the 2PC protocol, which
governs how transactions are committed by multiple systems that do not
share memory. The protocol guarantees that either all systems commit or
all roll back.
(continued)
• N or NULL = Do not override.
Usage Notes
This table function is only supported in Constant Mode.
AbortListSessions cannot be used to abort delayed utility sessions because these sessions are
not completely logged on.
This function provides similar functionality to the PMPC ABORT SESSION request with
ListSessions set to ‘N’ or ‘No’.
Result Rows
Column Name
Description
HostId
Logical host ID of (or client) the aborted sessions were logged on to. For a PE,
HostId identifies one of the hosts or LANs associated with the described PE.
For a session, the combination of a host ID and a session number uniquely
identifies a user session on the system.
Note: This value is NULL for AMPs. A value of zero represents the Supervisor
window.
196
SessionNo
Number of the session that was aborted. Together with a given host ID, a
session number uniquely identifies a session on the Teradata Database system.
This value is assigned by the host (or client) at logon time.
UserName
User name of the session that was aborted. This is the name specified when the
user is created; it is used to log on to a session. Within Teradata Database, user
name is almost equivalent to database name.
Application Programming Reference
Chapter 4: System PMPC APIs
AbortListSessions
Column Name
Description
AbortStatus
Status of the sessions aborted:
•
•
•
•
•
•
I = In-Doubt
A = Aborting a transaction
C = Committing a transaction
E = Executing an ABORT SESSION request
S = Switching
An empty string = In some state other than the above. This value returns
when issuing an SQL function.
For an ABORT without LOGOFF, any status except NULL indicates the reason
the request could not impact the associated session.
For an ABORT with LOGOFF, an I, E, or S status value indicates that the
associated session cannot be aborted or logged off.
Example
SELECT * FROM TABLE (AbortListSessions(1, 'User14', 0, 'Y', 'Y')) AS t1;
*** Query completed. 5 rows found. 4 columns returned.
*** Total elapsed time was 4 seconds.
HostId
-----1
1
1
1
1
Application Programming Reference
SessionNo
----------1007
1011
1010
1009
1008
UserName
-----------------------------USER14
USER14
USER14
USER14
USER14
AbortStatus
-----------
197
Chapter 4: System PMPC APIs
AbortSessions
AbortSessions
Purpose
Aborts any outstanding request or transaction of one or more sessions, and optionally logs
those sessions off Teradata Database.
Definition
REPLACE FUNCTION SYSLIB.AbortSessions
(HostIdIn
SMALLINT,
UserNameIn VARCHAR(128)CHARACTER SET LATIN,
SessionNoIn INTEGER,
LogoffSessions VARCHAR(1) CHARACTER SET LATIN,
UserOverride
VARCHAR(1) CHARACTER SET LATIN
)
RETURNS INTEGER
.
.
.
;
Input Parameters
Parameter
Description
HostIdIn
Logical ID of a host (or client) with sessions logged on.
A value of -1 indicates all hosts.
UserNameIn
User name of the session.
An asterisk (*) or NULL indicates all users.
SessionNoIn
ID of the session to abort.
A value of zero indicates all sessions.
LogoffSessions
Indicator of whether to log off sessions to Teradata Database in addition to
aborting them:
• Y = Log off and abort sessions.
• N or NULL = Do not log sessions off.
198
Application Programming Reference
Chapter 4: System PMPC APIs
AbortSessions
Parameter
Description
UserOverride
Indicator of whether to override an ABORT SESSION failure:
• Y = Override the ABORT SESSION request to fail in any of the
following cases:
• An identified session is being session-switched.
• An identified session is executing its own ABORT SESSION request.
• An identified session has a PEState of IDLE: IN-DOUBT as a result
of a 2PC.
Note: Sessions are marked IN-DOUBT by the 2PC protocol, which
governs how transactions are committed by multiple systems that
do not share memory. The protocol guarantees that either all
systems commit or all roll back.
• N or NULL = Do not override.
Usage Notes
The AbortSessions function provides similar functionality to the PMPC ABORT SESSION
request with ListSessions set to ‘Y’ or ‘Yes’. For information about this interface, see
“ABORT SESSION” on page 50.
Return Value
If successful, this function returns the number of sessions that were aborted.
Example 1
SELECT AbortSessions (1, 'User14', 0, 'Y', 'Y');
* * * Query completed. One row found. one column returned.
* * * Total elapsed time was 5 seconds.
AbortSessions (1, 'User14', 0, 'Y', 'Y')
---------------------------------------5
Application Programming Reference
199
Chapter 4: System PMPC APIs
AbortSessions
Example 2
SELECT AbortSessions (HostId, UserName, SessionNo, 'Y', 'Y');
FROM TABLE (MonitorSession(-1, '*', 0)) AS t1
WHERE username= 'user14';
* * * Query completed. 5 rows found. one column returned.
* * * Total elapsed time was 2 seconds.
AbortSessions (HostId, UserName, SessionNo, 'Y', 'Y')
---------------------------------------------------1
1
1
1
200
Application Programming Reference
Chapter 4: System PMPC APIs
IdentifyDatabase
IdentifyDatabase
Purpose
Returns the name of the specified database ID.
Definition
REPLACE FUNCTION SYSLIB.IdentifyDatabase
(DatabaseId INTEGER
)
RETURNS VARCHAR(128)
.
.
.
;
Input Parameter
Parameter
Description
DatabaseId
Database ID.
Usage Notes
The IdentifyDatabase function provides similar functionality to the PMPC IDENTIFY
DATABASE request. For information about this interface, see “IDENTIFY” on page 61.
Return Value
This function returns the name of the database.
Example
SELECT IdentifyUser(blk1userid) as "blocking user",
IdentifyTable(blk1objtid) as "blocking table",
IdentifyDatabase(blk1objdbid) as "blocking db"
FROM TABLE (MonitorSession(-1,'*',0)) AS t1
WHERE Blk1UserId > 0;
*** Query completed. One row found. 3 columns returned.
*** Total elapsed time was 4 seconds.
blocking user
blocking table
blocking db
--------------------------- -------------------------- ------------user1
skewAmp1
DBaaa
Application Programming Reference
201
Chapter 4: System PMPC APIs
IdentifySession
IdentifySession
Purpose
Identifies the name of a user, by session, who is causing a block.
Definition
REPLACE FUNCTION SYSLIB.IdentifySession
(HostId
INTEGER,
SessionNo
INTEGER
)
RETURNS VARCHAR(128)
.
.
.
;
Input Parameters
Parameter
Description
HostId
ID of the blocking host.
SessionNo
Number of the session that is blocked.
Usage Notes
The IdentifySession function provides similar functionality to the PMPC IDENTIFY
SESSION request. For information about this interface, see “IDENTIFY” on page 61.
Return Value
Returns the name of the user, by session, who is causing a block.
Example
SELECT IdentifySession(blk1Hostid,blk1sessno)
FROM TABLE (MonitorSession(-1,'*',0)) AS t1
WHERE Blk1UserId > 0;
*** Query completed. One row found. One column returned.
*** Total elapsed time was 1 second.
IdentifySession(Blk1HostId,Blk1SessNo)
-------------------------------------USER1
202
Application Programming Reference
Chapter 4: System PMPC APIs
IdentifyTable
IdentifyTable
Purpose
Returns the name of the specified table ID.
Definition
REPLACE FUNCTION SYSLIB.IdentifyTable
(TableId INTEGER
)
RETURNS VARCHAR(128)
.
.
.
;
Input Parameter
Parameter
Description
TableID
ID of the locked table.
Usage Notes
The IdentifyTable function provides similar functionality to the PMPC IDENTIFY TABLE
request. For information about this interface, see “IDENTIFY” on page 61.
Return Value
This function returns the name of the table.
Example
SELECT IdentifyUser(blk1userid) as "blocking user",
IdentifyTable(blk1objtid) as "blocking table",
IdentifyDatabase(blk1objdbid) as "blocking db"
FROM TABLE (MonitorSession(-1,'*',0)) AS t1
WHERE Blk1UserId > 0;
*** Query completed. One row found. 3 columns returned.
*** Total elapsed time was 4 seconds.
blocking user
--------------------------user1
Application Programming Reference
blocking table
blocking db
----------------------- ------------skewAmp1
DBaaa
203
Chapter 4: System PMPC APIs
IdentifyUser
IdentifyUser
Purpose
Returns the name of the specified user ID who is causing a block.
Definition
REPLACE FUNCTION SYSLIB.IdentifyUser
(UserId INTEGER
)
RETURNS VARCHAR(128)
.
.
.
;
Input Parameter
Parameter
Description
UserId
ID of the user who is causing the block.
Usage Notes
The IdentifyUser function provides similar functionality to the PMPC IDENTIFY USER
request. For information about this interface, see “IDENTIFY” on page 61.
Return Value
This function returns the name of the user.
Example
SELECT IdentifyUser(blk1userid) as "blocking user",
IdentifyTable(blk1objtid) as "blocking table",
IdentifyDatabase(blk1objdbid) as "blocking db"
FROM TABLE (MonitorSession(-1,'*',0)) AS t1
WHERE Blk1UserId > 0;
*** Query completed. One row found. 3 columns returned.
*** Total elapsed time was 4 seconds.
blocking user
blocking table
blocking db
--------------------------- ----------------------- ------------user1
skewAmp1
DBaaa
204
Application Programming Reference
Chapter 4: System PMPC APIs
MonitorAMPLoad
MonitorAMPLoad
Purpose
Returns the data from the third statement of the MONITOR AWT RESOURCE request
response.
Definition
REPLACE FUNCTION SYSLIB.MonitorAMPLoad()
RETURNS TABLE
(VprocNo SMALLINT,
AvailableAWTs INTEGER,
InUseAWTs INTEGER,
MsgCount INTEGER,
DQMsgCount INTEGER
)
.
.
.
;
Usage Notes
For information on the third statement returned from the MONITOR AWT RESOURCE
request response, see “Statement Type: 3” on page 74.
Result Rows
Column Name
Description
VprocNo
AMP vproc number.
AvailableAWTs
Number of available AMP worker tasks in each AMP.
InUseAWTs
Number of active AMP worker tasks in each AMP.
MsgCount
Number of messages currently queued for delivery to each AMP.
DQMsgCount
Number of messages processed by each AMP.
Example
This example shows the data reported in Statement Type 3 of MONITOR AWT RESOURCE.
SELECT * FROM TABLE (MonitorAMPLoad()) AS t1;
RESULTS SIDETITLES
VprocNo
:
AvailableAWTs :
Application Programming Reference
0
48
205
Chapter 4: System PMPC APIs
MonitorAMPLoad
206
InUseAWTs
MsgCount
DQMsgCount
:
:
:
VprocNo
AvailableAWTs
InUseAWTs
MsgCount
DQMsgCount
:
:
:
:
:
3
0
1026
1
49
1
0
1080
Application Programming Reference
Chapter 4: System PMPC APIs
MonitorAWTResource
MonitorAWTResource
Purpose
Collects statistics on AMPs based on the in-use AMP Worker Tasks (AWTs).
Definition
REPLACE FUNCTION SYSLIB.MonitorAWTResource()
(Threshold1
INTEGER,
Threshold2
INTEGER,
Threshold3
INTEGER,
Threshold4
INTEGER
RETURNS TABLE
(IntervalCount1
INTEGER,
IntervalCount2
INTEGER,
IntervalCount3
INTEGER,
IntervalCount4
INTEGER,
FlowControl
INTEGER,
HighAMP1VprocId
INTEGER,
HighAMP1InUseCount INTEGER,
HighAMP2VprocId
INTEGER,
HighAMP2InUseCount INTEGER,
HighAMP3VprocId
INTEGER,
HighAMP3InUseCount INTEGER,
HighAMP4VprocId
INTEGER,
HighAMP4InUseCount INTEGER,
HighAMP5VprocId
INTEGER,
HighAMP5InUseCount INTEGER,
LowAMP1VprocId
INTEGER,
LowAMP1InUseCount INTEGER,
LowAMP2VprocId
INTEGER,
LowAMP2InUseCount INTEGER,
LowAMP3VprocId
INTEGER,
LowAMP3InUseCount INTEGER,
LowAMP4VprocId
INTEGER,
LowAMP4InUseCount INTEGER,
LowAMP5VprocId
INTEGER,
LowAMP5InUseCount INTEGER,
FCVprocId1
INTEGER,
FCVprocId2
INTEGER,
FCVprocId3
INTEGER,
FCVprocId4
INTEGER,
FCVprocId5
INTEGER
)
.
.
.
;
Application Programming Reference
207
Chapter 4: System PMPC APIs
MonitorAWTResource
Input Parameters
Parameter
Description
Threshold1
Minimum value for in-use AWTs to qualify an AMP for inclusion
into this interval.
Threshold2
Start value for in-use AWTs to qualify an AMP for inclusion into
this interval.
Threshold3
Start value for in-use AWTs to qualify an AMP for inclusion into
this interval.
Threshold4
Start value for in-use AWTs to qualify an AMP for inclusion into
this interval.
Usage Notes
The MonitorAWTResource functions are two overloaded functions. One requires the
threshold values to be passed in; the other sets the threshold values to 45, 55, 62 and 75.
The MonitorAWTResource function provides similar functionality to the PMPC MONITOR
AWT RESOURCE request. For information about this interface, see “MONITOR AWT
RESOURCE” on page 69.
Result Rows
208
Column Name
Description
IntervalCount1
Number of AMPs in the system whose in-use AWT counts fall at, or
above, the Threshold1 value and do not qualify for the higher
thresholds.
IntervalCount2
Number of AMPs in the system whose in-use AWT counts fall at, or
above, the Threshold2 value and do not qualify for the higher
thresholds.
IntervalCount3
Number of AMPs in the system whose in-use AWT counts fall at, or
above, the Threshold3 value and do not qualify for the higher
thresholds.
IntervalCount4
Number of AMPs in the system whose in-use AWT counts fall at, or
above, the Threshold4 value and do not qualify for the higher
thresholds.
FlowControl
Number of AMPs currently in some form of Flow Control.
HighAMP1VprocId
Vproc ID of the AMP with the highest in-use count in the system. A
value of -1 indicates this field is not defined.
HighAMP1InUseCount
In-use count associated with the AMP 1 Vproc ID. This is only
applicable if AMP 1 is defined.
Application Programming Reference
Chapter 4: System PMPC APIs
MonitorAWTResource
Column Name
Description
HighAMP2VprocId
Vproc ID of the AMP with the next highest in-use count in the system.
A value of -1 indicates this field is not defined.
HighAMP2InUseCount
In-use count associated with the AMP 2 Vproc ID. This is only
applicable if AMP 2 is defined.
HighAMP3VprocId
Vproc ID of the AMP with the next highest in-use count in the system.
A value of -1 indicates this field is not defined.
HighAMP3InUseCount
In-use count associated with the AMP 3 Vproc ID. This is only
applicable if AMP 3 is defined.
HighAMP4VprocId
Vproc ID of the AMP with the next highest in-use count in the system.
A value of -1 indicates this field is not defined.
HighAMP4InUseCount
In-use count associated with the AMP 4 Vproc ID. This is only
applicable if AMP 4 is defined.
HighAMP5VprocId
Vproc ID of the AMP with the next highest in-use count in the system.
A value of -1 indicates this field is not defined.
HighAMP5InUseCount
In-use count associated with the AMP 5 Vproc ID. This is only
applicable if AMP 5 is defined.
LowAMP1VprocId
Vproc ID of the AMP with the lowest in-use count in the system. A
value of -1 indicates this field is not defined.
LowAMP1InUseCount
In-use count associated with the AMP 1 Vproc ID. This is only
applicable if AMP 1 is defined.
LowAMP2VprocId
Vproc ID of the AMP with the lowest in-use count in the system. A
value of -1 indicates this field is not defined.
LowAMP2InUseCount
In-use count associated with the AMP 2 Vproc ID. This is only
applicable if AMP 2 is defined.
LowAMP3VprocId
Vproc ID of the AMP with the lowest in-use count in the system. A
value of -1 indicates this field is not defined.
LowAMP3InUseCount
In-use count associated with the AMP 3 Vproc ID. This is only
applicable if AMP 3 is defined.
LowAMP4VprocId
Vproc ID of the AMP with the lowest in-use count in the system. A
value of -1 indicates this field is not defined.
LowAMP4InUseCount
In-use count associated with the AMP 4 Vproc ID. This is only
applicable if AMP 4 is defined.
LowAMP5VprocId
Vproc ID of the AMP with the lowest in-use count in the system. A
value of -1 indicates this field is not defined.
LowAMP5InUseCount
In-use count associated with the AMP 5 Vproc ID. This is only
applicable if AMP 5 is defined.
Application Programming Reference
209
Chapter 4: System PMPC APIs
MonitorAWTResource
Column Name
Description
FCVprocId1,
The vproc ID of the AMP in flow control. A value of -1 indicates this
field is not defined.
FCVprocId2,
FCVprocId3,
FCVprocId4,
FCVprocId5
Example
SELECT * FROM TABLE (MonitorAWTResource(1,2,3,4)) AS t1;
*** Query completed. One row found. 30 columns returned.
*** Total elapsed time was 1 second.
IntervalCount1
IntervalCount2
IntervalCount3
IntervalCount4
FlowControl
HighAMP1VprocId
HighAMP1InUseCount
HighAMP2VprocId
HighAMP2InUseCount
HighAMP3VprocId
HighAMP3InUseCount
HighAMP4VprocId
HighAMP4InUseCount
HighAMP5VprocId
HighAMP5InUseCount
LowAMP1VprocId
LowAMP1InUseCount
LowAMP2VprocId
LowAMP2InUseCount
LowAMP3VprocId
LowAMP3InUseCount
LowAMP4VprocId
LowAMP4InUseCount
LowAMP5VprocId
LowAMP5InUseCount
FCVprocId1
FCVprocId2
FCVprocId3
FCVprocId4
FCVprocId5
210
0
0
2
4
0
2
6
5
4
3
4
1
4
4
3
4
3
0
3
5
4
3
4
1
4
-1
-1
-1
-1
-1
Application Programming Reference
Chapter 4: System PMPC APIs
MonitorMySessions
MonitorMySessions
Purpose
Collects the session information for the current user on the current host.
Definition
REPLACE FUNCTION SYSLIB.MonitorMySessions()
RETURNS TABLE
(HostId SMALLINT,
SessionNo INTEGER,
LogonPENo SMALLINT,
RunVprocNo SMALLINT,
PartName VARCHAR(16)CHARACTER SET LATIN,
PEstate VARCHAR(18)CHARACTER SET LATIN,
LogonTime VARCHAR(22)CHARACTER SET LATIN,
UserId INTEGER,
LSN INTEGER,
UserName VARCHAR(128),
UserAccount VARCHAR(128),
PECPUsec FLOAT,
XActCount FLOAT,
ReqCount FLOAT,
ReqCacheHits FLOAT,
AMPState VARCHAR(18)CHARACTER SET LATIN,
AMPCPUSec FLOAT,
AMPIO FLOAT,
ReqSpool FLOAT,
Blk1HostId SMALLINT,
Blk1SessNo INTEGER,
Blk1UserId INTEGER,
Blk1Lmode CHAR(1) CHARACTER SET LATIN,
Blk1Otype CHAR (1) CHARACTER SET LATIN,
Blk1ObjDBID INTEGER,
Blk1ObjTID INTEGER,
Blk1Status CHAR (1) CHARACTER SET LATIN,
Blk2HostId SMALLINT,
Blk2SessNo INTEGER,
Blk2UserId INTEGER,
Blk2Lmode CHAR(1) CHARACTER SET LATIN,
Blk2Otype CHAR(1) CHARACTER SET LATIN,
Blk2ObjDBID INTEGER,
Blk2ObjTID INTEGER,
Blk2Status CHAR(1) CHARACTER SET LATIN,
Blk3HostId SMALLINT,
Blk3SessNo INTEGER,
Blk3UserId INTEGER,
Blk3Lmode CHAR(1) CHARACTER SET LATIN,
Blk3Otype CHAR(1) CHARACTER SET LATIN,
Blk3ObjDBID INTEGER,
Blk3ObjTID INTEGER,
Blk3Status CHAR(1) CHARACTER SET LATIN,
Application Programming Reference
211
Chapter 4: System PMPC APIs
MonitorMySessions
MoreBlockers CHAR(1) CHARACTER SET LATIN,
LogonSource VARCHAR(128),
HotAmp1CPU FLOAT,
HotAmp2CPU FLOAT,
HotAmp3CPU FLOAT,
HotAmp1CPUId FLOAT,
HotAmp2CPUId FLOAT,
HotAmp3CPUId FLOAT,
HotAmp1IO FLOAT,
HotAmp2IO FLOAT,
HotAmp3IO FLOAT,
HotAmp1IOId INTEGER,
HotAmp2IOId INTEGER,
HotAmp3IOId INTEGER,
LowAmp1CPU FLOAT,
LowAmp2CPU FLOAT,
LowAmp3CPU FLOAT,
LowAmp1CPUId INTEGER,
LowAmp2CPUId INTEGER,
LowAmp3CPUId INTEGER,
LowAmp1IO FLOAT,
LowAmp2IO FLOAT,
LowAmp3IO FLOAT,
LowAmp1IOId INTEGER,
LowAmp2IOId INTEGER,
LowAmp3IOId INTEGER,
AvgAmpCPUSec FLOAT,
AvgAmpIOCnt FLOAT,
AmpCount INTEGER,
TempSpaceUsg FLOAT,
ReqStartTime VARCHAR(22) CHARACTER SET LATIN,
ReqCPU FLOAT,
ReqIO FLOAT,
ReqNo INTEGER,
WlcId INTEGER,
DontReclassifyFlag SMALLINT,
ProxyUser VARCHAR (128),
CPUDecayLevel SMALLINT,
IODecayLevel SMALLINT,
TacticalCPUException INTEGER,
TacticalIOException INTEGER,
ReqIOKB FLOAT,
ReqPhysIO FLOAT,
ReqPhysIOKB FLOAT,
ReqStepsCompletedCnt INTEGER,
RedriveProtection CHAR (2),
CurrentRedriveParticipation CHAR (1),
ReqPersistentSpoolSpace FLOAT,
)
.
.
.
;
Usage Notes
The following CPU fields in the MonitorMySessions response are affected by the
MonSesCPUNormalization field:
212
Application Programming Reference
Chapter 4: System PMPC APIs
MonitorMySessions
•
•
•
•
AMPCPUSec
AvgAmpCPUSec
HotAmp1CPU
HotAmp2CPU
•
•
•
•
HotAmp3CPU
LowAmp1CPU
LowAmp2CPU
LowAmp3CPU
• PECPUSec
• RequestAmpCPU
The MonSesCPUNormalization field, a DBS Control General Record field, controls whether
normalized or non-normalized statistical CPU data is reported by the functions:
MonitorMySessions and MonitorSession, and by the MONITOR SESSION request. For more
information about the MonSesCPUNormalization field and CPU normalization, see the DBS
Control utility in Utilities.
For a complete description of these fields, see the topic that follows.
You can also refer to “MonitorSession” on page 240 or “MONITOR SESSION” on page 101
for a list of these CPU fields.
Result Rows
Column Name
Description
HostId
Logical Host ID associated with a PE or session.
For a PE, HostId identifies one of the hosts or LANs
associated with the described PE.
For a session, the combination of a host ID and a session
number uniquely identifies a user session on the system.
Note: This value is NULL for AMPs. A value of zero
represents the Supervisor window.
SessionNo
Number of the current session. Together with a given host
ID, a session number uniquely identifies a session on the
Teradata Database system. This value is assigned by the host
(or client) at logon time.
LogonPENo
Vproc number of the PE the session is currently logged on
to; it identifies the PE that has control responsibility for the
session. Normally, this is the PE that processed the logon
request; but if that PE goes offline, it will be the PE to which
the session was switched.
Application Programming Reference
213
Chapter 4: System PMPC APIs
MonitorMySessions
Column Name
Description
RunVprocNo
Vproc number of the AMP or PE currently assigned to
process the session requests.
For sessions in Teradata SQL partitions, this value is
identical to the LogonPENo. For sessions in FastLoad or
MultiLoad partitions, this is the AMP that initially processes
the data being loaded. For HUTPARSE or HUTCTL
(archive/recovery) sessions, this value is NULL.
If a RunVprocNo value of -1 in record mode or NULL in
indicator mode is returned by MonitorMySessions for
FastLoad, MultiLoad or FastExport sessions, this indicates
that the session is in the process of starting up.
PartName
Name of the session partition associated with this session.
Following a successful logon request by a session or as part
of a connect request, the session identifies the partition with
which the user wants the session to be associated.
FASTLOAD, Teradata SQL, MONITOR, INTERNAL are
examples of valid partition names.
PEstate
Current state of the session within the PE. See the
MONITOR SESSION PEState field for a list of the PEState
values.
LogonTime
Date and time portion of the information recorded by
Session Control when a session successfully logs on. It is
usually formatted for display as yyyy/mm/dd 99:99:99.99,
which represents the year, month, day, hours: minutes:
seconds.
UserId
User or internal ID of a user for this session. Within the
Teradata Database, UserId is equivalent to Database ID.
Typically, UserId is used when the associated record is
known to be a user name, and Database ID is used when the
associated record is known to be a database. However,
UserId can identify either a given user or database name.
LSN
Logon Sequence Number (LSN) that is associated with a
session when the session logs on. It identifies a collection of
sessions performing a related activity. For example, in a
FastLoad job, a user is logged on as a Teradata SQL session,
as well as n FastLoad sessions with the same user name.
Therefore, n+1 sessions (1 Teradata SQL and n FastLoad)
with the same LSN are all associated with the given FastLoad
job. To see how the FastLoad job is doing, the user can pick
out all sessions reported with the same LSN number.
Note: This information supplies the parent-child
relationship for sessions involved with FastLoad, MultiLoad,
and Archive/Recovery jobs.
UserName
214
User name of the session. This is the name specified when
the user is created; it is used to log on to a session. Within
Teradata Database, user name is almost equivalent to the
database name.
Application Programming Reference
Chapter 4: System PMPC APIs
MonitorMySessions
Column Name
Description
UserAccount
Account currently with which the user is logged in. When a
user is created or altered, that user is allowed to run in
association with one or more accounts. During the logon
process, a particular user session establishes its priority and
charges resource usage to one of the allowed accounts.
PECPUsec
CPU time (in seconds) used in a PE by the associated session
for parsing and dispatching requests. It is accurate to the
second.
This value is valid only when associated with Teradata SQL
and MONITOR partition sessions.
This value is NULL when it is returned for all other sessions.
XActCount
Number of explicit and implicit transactions executed by the
session.
This value is valid only when returned for Teradata SQL
sessions, and is NULL for all other partition sessions. For
this value, you must make a request for data before
completion of the first collection period that follows either a
system outage or a change in the ResMonitor rate.
ReqCount
Number of requests (Tequel Start Request [TSR] messages)
initiated by the session.
This value is NULL when a request for data is made before
completion of the first collection period following either a
system outage or change in the ResMonitor rate.
ReqCacheHits
Number of times that this session processed a request using
information from the Teradata SQL Parser request cache,
specifically, how many times there was a request cache hit.
This value is valid only for Teradata SQL sessions, and is
NULL for all other partition sessions. This value is also
NULL when a request for data is made before completion of
the first collection period following either a system outage
or a change in the ResMonitor rate.
Application Programming Reference
215
Chapter 4: System PMPC APIs
MonitorMySessions
Column Name
Description
AMPState
Current state of the associated session in AMP vprocs in
decreasing priority:
• ABORTING: The transaction is being rolled back;
session is aborting.
• BLOCKED: Some background activity is in progress and
the last request is on hold until this background activity
is completed.
• ACTIVE: Normal, on-going activity is being done by this
session.
• IDLE: No work in progress for this session on any AMP.
• UNKNOWN: No recorded activity by this session since
monitoring began.
This value is NULL when a request for data is made before
completion of the first collection period following either a
system outage or a change in the SesMonitorLoc or
SesMonitorSys rate.
AMPCPUSec
Current elapsed CPU time, in seconds, used on all AMPs by
the associated session for executing requests. For example,
for Teradata SQL requests, this is the time spent by the
Teradata Database actively working or rolling back an
aborted transaction. This does not include any PDE CPU
time spent handling Teradata Database requests.
This value is NULL when a request for data is made before
completion of the first collection period following either a
system outage or a change in the ResMonitor rate.
AMPIO
Current number of logical Reads and Writes issued across all
AMPs by the associated session.
This value is NULL when a request for data is made before
completion of the first collection period following either a
system outage or a change in the ResMonitor rate.
ReqSpool
Current spool used by current request across all AMPs,
expressed as a number of bytes.
This value is NULL when a request for data is made before
completion of the first collection period following either a
system outage or a change in the ResMonitor rate.
216
Application Programming Reference
Chapter 4: System PMPC APIs
MonitorMySessions
Column Name
Description
Blk1HostId,
Logical host ID of a session causing a block. This value is
derived from equating the transactions causing a Teradata
Database lock conflict to the sessions that issued those
transactions. The Blk_x_HostId in combination with
Blk_x_SessNo uniquely identifies the session that is causing
a block.
Blk2HostId,
Blk3HostId
A valid value is not returned if an inactive Archive/Recovery
job is causing the lock conflict, because no session is logged
in.
This value is NULL if:
• The host ID is not available.
• The session does not have an AMPState of BLOCKED.
If the Blk_x_HostId, Blk_x_SessNo, and Blk_x_UserID
values all return as NULLs and AMPState is BLOCKED, a
Host Utility (HUT) lock left over after the session holding
the lock was aborted or logged off. The lock was never
released, and no blocking information is available because
the session no longer exists.
Use the Show Locks utility to obtain the user name that
placed the HUT lock. For more information, see Utilities.
Blk1SessNo,
Blk2SessNo,
Blk3SessNo
Number of the session causing a block. This value is derived
from associating the transactions causing a lock conflict to
the sessions that issued those transactions. The
Blk_x_SessNo in combination with Blk_x_HostId uniquely
identifies the session causing a block.
This information is unavailable if an inactive Archive/
Recovery job is causing the lock conflict.
This value is NULL if:
• SessNo is not available.
• Session does not have an AMPState of BLOCKED.
• A request for data is made before completion of the first
collection period following either a system outage or a
change in the SesMonitorLoc or SesMonitorSys rate.
If the Blk_x_HostId, Blk_x_SessNo, and Blk_x_UserID
values all return as NULLs and AMPState is BLOCKED, a
host utility lock left over after the session holding the lock
was aborted or logged off. The lock was never released, and
no blocking information is available because the session no
longer exists.
Use the Show Locks utility to obtain the user name that
placed the HUT lock. For more information, see Utilities.
Application Programming Reference
217
Chapter 4: System PMPC APIs
MonitorMySessions
Column Name
Description
Blk1UserId,
ID of the user or host utility job preventing the session from
being granted a lock. This information is especially
important when an Archive/Recovery job is holding the
lock, because the user ID is the only information available
about who placed the lock.
Blk2UserId,
Blk3UserId
This value is NULL if:
• Session does not have an AMPState of BLOCKED.
• A request for data is made before completion of the first
collection period following either a system outage or a
change in the SesMonitorLoc or SesMonitorSys rate.
If the Blk_x_HostId, Blk_x_SessNo, and Blk_x_UserID
values all return as NULLs and AMPState is BLOCKED, a
host utility lock left over after the session holding the lock
was aborted or logged off. The lock was never released, and
no blocking information is available because the session no
longer exists.
Use the Show Locks utility to obtain the user name that
placed the HUT lock. For more information, see Utilities.
Blk1Lmode,
Mode (severity) of the lock involved in causing a block:
Blk2Lmode,
• E = Exclusive
• W = Write
• R = Read
• A = Access
Locks are reported in decreasing order of severity because
removing the most severe lock conflict may eliminate the
source of the lock conflict.
Blk3Lmode
This value is NULL if:
• The session does not have an AMPState of BLOCKED.
• A request for data is made before completion of the first
collection period following either a system outage or a
change in the SesMonitorLoc or SesMonitorSys rate.
Note: A session may be blocked by either a granted lock or
an ungranted lock that precedes the blocked lock in the
queue and is in conflict with the lock requested by this
blocked session. For information on whether the lock is
granted, see the MONITOR SESSSION fields: Blk1Status,
Blk2Status, and Blk3Status.
218
Application Programming Reference
Chapter 4: System PMPC APIs
MonitorMySessions
Column Name
Description
Blk1Otype,
Type of object whose lock is causing the session described by
the associated row to be blocked:
Blk2Otype,
Blk3Otype
• D = Database
• T= Table
• R = Row hash
However, this object is not necessarily the type of object the
blocked session is trying to access. For example, if the
session is requesting a row hash lock, the blocking object
could be a database, table, or row hash.
This value is NULL if:
• Session does not have an AMPState of BLOCKED.
• A request for data is made before completion of the first
collection period following either a system outage or a
change in the SesMonitorLoc or SesMonitorSys rate.
For a Table T, it is possible for User A to block User B with a
table level lock on Table T on AMP_1 and with a Row Hash
Level lock on that same Table T on AMP_2. When that
occurs, the only lock conflict reported is that User B is
blocked by User A on a table.
Blk1ObjDBID,
Blk2ObjDBID,
Blk3ObjDBID
Unique ID of the database object over which a lock conflict
is preventing the session from being granted a lock.
Within the Teradata Database system, Database ID is
equivalent to User ID. Typically, User ID is used when the
associated record is known to be a user name, and Database
ID is used when the associated record is known to be a
database. However, Database ID can identify either a user or
database name.
This value is NULL if:
• The session does not have an AMPState of BLOCKED.
• A request for data is made before completion of the first
collection period following either a system outage or a
change in the SesMonitorLoc or SesMonitorSys rate.
Blk1ObjTID,
Blk2ObjTID,
Unique ID of the table object over which a lock conflict is
preventing the session from being granted a lock.
Blk3ObjTID
This value is NULL if:
• The session does not have an AMPState of BLOCKED.
• The Blk_x_OType is D.
• A request for data is made before completion of the first
collection period following either a system outage or a
change in the SesMonitorLoc or SesMonitorSys rate.
Application Programming Reference
219
Chapter 4: System PMPC APIs
MonitorMySessions
Column Name
Description
Blk1Status,
Status of lock causing a block:
Blk2Status,
• W= Waiting
• G = Granted
This value is NULL if:
Blk3Status
• Session does not have an AMPState of BLOCKED.
• A request for data is made before completion of the first
collection period following either a system outage or a
change in the SesMonitorLoc or SesMonitorSys rate.
Note: A lock request may be blocked by either a granted
lock or an ungranted lock that precedes the blocked lock
request in the queue and is in conflict with it.
A status of Waiting has a higher priority than that of
Granted when there is more than one lock involved. For
example, for a given object and a given session, a session that
is blocked by a Waiting lock on one AMP and a Granted lock
on another AMP has Waiting reported as its status.
MoreBlockers
Indicator of more lock conflicts:
• Blank = Blkx information is a complete list of sessions
blocking the session described.
• Asterisk (*) = additional sessions are blocking the session
described. The Blkx information shows only three
blocking sessions.
This value is NULL if:
• The state of the session is not BLOCKED.
• A request for data is made before completion of the first
collection period following either a system outage or a
change in the SesMonitorLoc or SesMonitorSys rate.
LogonSource
Logon source information. At logon time, this information
is optionally supplied by the Teradata Director Program or
the LAN Gateway to further identify the physical or logical
location of the session, the logon user name, and the
interface under which the session was initiated. (For
example, the data string may include DBC as the user ID
and BTEQ as the interface.)
Note: A two-byte value precedes the LogonSource data to
indicate the length of the string. The length value is zero if
LogonSource is NULL.
For a list of the commonly seen LogonSource string
application names, see SQL Data Definition Language.
HotAmp1CPU
CPU time of the highest CPU utilized AMP during the
collection interval.
This value is NULL if the request is made before the
collection period expires.
220
Application Programming Reference
Chapter 4: System PMPC APIs
MonitorMySessions
Column Name
Description
HotAmp2CPU
CPU time of the second highest CPU utilized AMP during
the collection interval.
This value is NULL if the request is made before the
collection period expires.
HotAmp3CPU
CPU time of the third highest CPU utilized AMP during the
collection interval.
This value is NULL if the request is made before the
collection period expires, and if there are only two AMPs on
the system.
HotAmp1CPUId
Vproc ID of the highest CPU utilized AMP for the last
session collection interval.
This value is NULL if the request is made before the
collection period expires.
HotAmp2CPUId
Vproc ID of the second highest CPU utilized AMP for the
last session collection interval.
This value is NULL if the request is made before the
collection period expires.
HotAmp3CPUId
Vproc ID of the third highest CPU utilized AMP for the last
session collection interval.
This value is NULL if the request is made before the
collection period expires, and if there are only two AMPs in
the system.
HotAmp1IO
IO count of the highest IO utilized AMP during the
collection interval.
This value is NULL if the request is made before the
collection period expires.
HotAmp2IO
IO count of the second highest IO utilized AMP during the
collection interval.
This value is NULL if the request is made before the
collection period expires.
HotAmp3IO
IO count of the third highest IO utilized AMP for the last
collection interval.
This value is NULL if the request is made before the
collection period expires, and if there are only two AMPs in
the system.
HotAmp1IOId
Vproc ID of the highest IO utilized AMP for the last session
collection interval.
This value is NULL if the request is made before the
collection period expires.
Application Programming Reference
221
Chapter 4: System PMPC APIs
MonitorMySessions
Column Name
Description
HotAmp2IOId
Vproc ID of the second highest IO utilized AMP for the last
session collection interval.
This value is NULL if the request is made before the
collection period expires.
HotAmp3IOId
Vproc ID of the third highest IO utilized AMP for the last
session collection interval.
This value is NULL if the request is made before the
collection period expires, and if there are only two AMPs in
the system.
LowAmp1CPU
CPU time of the lowest CPU utilized AMP during the
collection interval.
This value is NULL if the request is made before the
collection period expires.
LowAmp2CPU
CPU time of the second lowest CPU utilized AMP during
the collection interval.
This value is NULL if the request is made before the
collection period expires.
LowAmp3CPU
CPU time of the third lowest CPU utilized AMP during the
collection interval.
This value is NULL if the request is made before the
collection period expires, and if there are only two AMPs on
the system.
LowAmp1CPUId
Vproc ID of the lowest CPU utilized AMP for the last
session collection interval.
This value is NULL if the request is made before the
collection period expires.
LowAmp2CPUId
Vproc ID of the second lowest CPU utilized AMP for the last
session collection interval.
This value is NULL if the request is made before the
collection period expires.
LowAmp3CPUId
Vproc ID of the third lowest CPU utilized AMP for the last
session collection interval.
This value is NULL if the request is made before the
collection period expires, and if there are only two AMPs on
the system.
LowAmp1IO
IO count of the lowest IO utilized AMP during the
collection interval.
This value is NULL if the request is made before the
collection period expires.
222
Application Programming Reference
Chapter 4: System PMPC APIs
MonitorMySessions
Column Name
Description
LowAmp2IO
IO count of the second lowest IO utilized AMP during the
collection interval.
This value is NULL if the request is made before the
collection period expires.
LowAmp3IO
IO count of the third lowest IO utilized AMP during the
collection interval.
This value is NULL if the request is made before the
collection period expires, and if there are only two AMPs on
the system.
LowAmp1IOId
Vproc ID of the lowest IO utilized AMP for the last session
collection interval.
This value is NULL if the request is made before the
collection period expires.
LowAmp2IOId
Vproc ID of the second lowest IO utilized AMP for the last
session collection interval.
This value is NULL if the request is made before the
collection period expires.
LowAmp3IOId
Vproc ID of the third lowest IO utilized AMP for the last
session collection interval.
This value is NULL if the request is made before the
collection period expires, and if there are only two AMPs on
the system.
AvgAmpCPUSec
Average AMP CPU utilization for the last session collection
interval. The average is calculated as the sum of CPU
utilization for all amps participating divided by the number
of online AMPs.
This value is NULL if the request is made before the
collection period expires.
AvgAmpIOCnt
Average AMP IO utilization for the last session collection
interval. The average is calculated as the sum of IO
utilization for all AMPs participating divided by the number
of online AMPs.
This value is NULL if the request is made before the
collection period expires.
AmpCount
Current number of AMPs currently executing on the
associated node.
TempSpaceUsg
Total amount, in bytes, of temporary space used by the
session.
This value is NULL if the session did not materialize any
temporary tables.
Application Programming Reference
223
Chapter 4: System PMPC APIs
MonitorMySessions
Column Name
Description
ReqStartTime
Date and time of the current request on the session started.
It is usually formatted for display as yyyy/mm/dd
99:99:99.99, which represents the year, month, day hours:
minutes: seconds.
ReqCPU
Total CPU usage by the current SQL request on the session
on all AMPs. This value contains proper request-level
statistics for DBC/SQL sessions running SQL requests only.
Ignore the value returned in this field for other types of
sessions, such as DBC/SQL sessions linked to a utility job.
This field is equivalent to the MONITOR SESSION
RequestAmpCPU field.
ReqIO
Total number of accesses by the current SQL request for the
session on all AMPs. This value contains proper requestlevel statistics for DBC/SQL sessions running SQL requests
only. Ignore the value returned in this field for other types of
sessions, such as DBC/SQL sessions linked to a utility job.
This field is equivalent to the MONITOR SESSION
RequestAmpI/O field.
ReqNo
Active request number.
If no request is running, then a value of zero or NULL is
displayed in indicator mode.
WlcId
Workload ID associated with the specified request.
DontReclassifyFlag
Flag indicating that the next request on the session will not
be classified but will use the workload ID (WlcId) already
assigned to the session. This will occur if this is a utility
session or a WlcId was assigned to the session using the
TDWMAssignWD function or the TDWM WD
ASSIGNMENT request. For more information on these
APIs, see Chapter 5: “Teradata Dynamic Workload
Management APIs.”
ProxyUser
Name of the proxy user if this session has a proxy
connection.
CPUDecayLevel
Current most severe decay level as reached due to CPU
usage.
Note: Nodes can be at different levels of decay (for example,
0, 1, or 2).
IODecayLevel
Current most severe decay level as reached due to I/O usage.
Note: Nodes can be at different levels of decay (for example,
0, 1, or 2).
224
TacticalCPUException
Number of nodes that encountered a CPU exception.
TacticalIOException
Number of nodes that encountered an I/O exception.
ReqIOKB
Total logical I/O usage in KB.
Application Programming Reference
Chapter 4: System PMPC APIs
MonitorMySessions
Column Name
Description
ReqIOPhysIO
Number of physical I/Os.
ReqIOPhysIOKB
Physical I/O usage in KB.
ReqStepsCompletedCnt
Count of completed steps for the current request. No change
in ReqStepsCompletedCnt from the previous Monitor
Session collection indicates no new steps completed.
RedriveProtection
Note: This field is reserved for future use.
CurrentRedriveParticipation
Note: This field is reserved for future use.
ReqPersistentSpoolSpace
Note: This field is reserved for future use.
Example
SELECT * FROM TABLE (MonitorSession(1,'*',1008)) AS t2;
*** Query completed. One row found. 91 columns returned.
*** Total elapsed time was 2 seconds.
HostId
SessionNo
LogonPENo
RunVprocNo
PartName
PEstate
LogonTime
UserId
LSN
UserName
UserAccount
PECPUsec
XActCount
ReqCount
ReqCacheHits
AMPState
AMPCPUSec
AMPIO
ReqSpool
Blk1HostId
Blk1SessNo
Blk1UserId
Blk1Lmode
Blk1Otype
Blk1ObjDBID
Blk1ObjTID
Blk1Status
Blk2HostId
Blk2SessNo
Blk2UserId
Blk2Lmode
Blk2Otype
Blk2ObjDBID
Blk2ObjTID
Blk2Status
Application Programming Reference
1
1008
16383
16383
DBC/SQL
DISPATCHING
2011/10/07 18:13:35.00
1017
0
JCK
DBC
2.40000000000000E-002
1.00000000000000E 000
2.00000000000000E 000
0.00000000000000E 000
ACTIVE
3.13344000000000E 002
9.65310000000000E 004
1.20341288960000E 010
0
0
0
0
0
0
0
0
0
0
225
Chapter 4: System PMPC APIs
MonitorMySessions
Blk3HostId
Blk3SessNo
Blk3UserId
Blk3Lmode
Blk3Otype
Blk3ObjDBID
Blk3ObjTID
Blk3Status
MoreBlockers
LogonSource
HotAmp1CPU
HotAmp2CPU
HotAmp3CPU
HotAmp1CPUId
HotAmp2CPUId
HotAmp3CPUId
HotAmp1IO
HotAmp2IO
HotAmp3IO
HotAmp1IOId
HotAmp2IOId
HotAmp3IOId
LowAmp1CPU
LowAmp2CPU
LowAmp3CPU
LowAmp1CPUId
LowAmp2CPUId
LowAmp3CPUId
LowAmp1IO
LowAmp2IO
LowAmp3IO
LowAmp1IOId
LowAmp2IOId
LowAmp3IOId
AvgAmpCPUSec
AvgAmpIOCnt
AmpCount
TempSpaceUsg
ReqStartTime
ReqCPU
ReqIO
ReqNo
WlcId
DontReclassifyFlag
ProxyUser
CPUDecayLevel
IODecayLevel
TacticalCPUException
TacticalIOException
ReqIOKB
ReqPhysIO
ReqPhysIOKB
ReqStepsCompletedCnt
RedriveProtection
CurrentRedriveParticipation
ReqRedriveSpoolSpace
226
0
0
0
0
0
(TCP/IP) 10ea 141.206.34.113 MYSYSTEM
2.79200000000000E 000
2.76400000000000E 000
2.76400000000000E 000
3
2
1
8.44000000000000E 002
8.44000000000000E 002
8.43000000000000E 002
2
0
1
2.70400000000000E 000
2.76400000000000E 000
2.76400000000000E 000
0
1
2
8.43000000000000E 002
8.43000000000000E 002
8.44000000000000E 002
3
1
2
2.75600000000000E 000
8.43500000000000E 002
4
0.00000000000000E 000
2011/10/07 18:13:35.00
3.13344000000000E 002
9.65310000000000E 004
3
0
255
11768
0
0
0
0
1.19556590000000E
1.18900000000000E
8.32590000000000E
9
DF
F
0.00000000000000E
007
003
004
000
Application Programming Reference
Chapter 4: System PMPC APIs
MonitorPhysicalConfig
MonitorPhysicalConfig
Purpose
Collects overall information on node availability. Node status information is returned for all
nodes in the system.
Definition
REPLACE FUNCTION SYSLIB.MonitorPhysicalConfig()
RETURNS TABLE
(ProcId
SMALLINT,
Status
CHAR,
CPUType VARCHAR(7),
CPUCount SMALLINT,
SystemType VARCHAR(7),
CliqueNo SMALLINT,
NetAUp CHAR(1),
NetBUp CHAR(1)
)
.
.
.
;
Usage Notes
The MonitorPhysicalConfig function provides similar functionality to the PMPC MONITOR
PHYSICAL CONFIG request. For information about this interface, see “MONITOR
PHYSICAL CONFIG” on page 77.
Result Rows
Column Name
Description
ProcId
ID associated with a node. This value is computed as the module number
within a cabinet plus 100 times the cabinet number. Usually formatted for
display as zz9-99. However, this display format can be changed by the user.
Application Programming Reference
227
Chapter 4: System PMPC APIs
MonitorPhysicalConfig
Column Name
Description
Status
Status of the node associated with this record:
• U = Up/online
• D = Down/offline
• S = Standby
A node is up (U) when it is:
• Configured into the system
• Online
• Capable of actively performing tasks associated with normal Teradata
Database activity
Down (D) represents all other potential states.
Standby (S) indicates the node is ready to join the configuration in place if
another node goes down. When the node status is Standby, the SystemType,
NetAUp, and NetBUp fields are not available and NULL or spaces will be
returned.
CPUType
Type of CPU installed in this node, for example: 'Pentium', 'PentPro', or
'Unknown'.
CPUCount
Number of CPUs in this node.
SystemType
Type of system running the Teradata Database software, such as 3400, 3500,
5100, or ‘Other’.
If all the nodes in the system are the same type, this field returns the type of the
system.
If any of the nodes are of a different type, this field returns ‘Mixed’.
CliqueNo
Clique number of the node.
NetAUp
Status of the BYNETs (if there are more than two, the first two) on a systemwide basis:
• U = All node BYNETs are up/online.
• D = One or more node BYNETs is down/offline.
• “” = A temporary condition where the BYNET data is not available.
NetBUp
Status of the BYNETs (if there are more than two, the first two) on a systemwide basis:
• U = All node BYNETs are up/online.
• D = One or more node BYNETs is down/offline.
• “” = A temporary condition where the BYNET data is not available.
Example
SELECT t2.* FROM TABLE (MonitorPhysicalConfig()) AS t2;
*** Query completed. One row found. 8 columns returned.
*** Total elapsed time was 1 second.
ProcId
Status
228
33
U
Application Programming Reference
Chapter 4: System PMPC APIs
MonitorPhysicalConfig
CPUType
CPUCount
SystemType
CliqueNo
NetAUp
NetBUp
Application Programming Reference
Pentium
1
5400
0
U
U
229
Chapter 4: System PMPC APIs
MonitorPhysicalResource
MonitorPhysicalResource
Purpose
Collects RSS data and returns node-specific data.
Definition
REPLACE FUNCTION SYSLIB.MonitorPhysicalResource()
RETURNS TABLE
(ProcId SMALLINT,
Status CHAR,
AmpCount SMALLINT,
PECount SMALLINT,
CPUUse FLOAT,
PrcntKernel FLOAT,
PrcntService FLOAT,
PrcntUser FLOAT,
DiskUse FLOAT,
DiskReads FLOAT,
DiskWrites FLOAT,
DiskOutReqAvg FLOAT,
NetAUse FLOAT,
NetReads FLOAT,
NetWrites FLOAT,
HstBlkRd FLOAT,
HstBlkWrts FLOAT,
MemAllocates FLOAT,
MemAllocateKB FLOAT,
MemFailures FLOAT,
MemAgings FLOAT,
NetAUp CHAR(1),
NetBUp CHAR(1)
)
.
.
.
;
Usage Notes
The MonitorPhysicalResource function returns the detailed resource usage information for
each node. Because the function reports on each node, you can isolate performance concerns
by node.
The MonitorPhysicalResource function provides similar functionality to the PMPC
MONITOR PHYSICAL RESOURCE request. For information about this interface, see
“MONITOR PHYSICAL RESOURCE” on page 83.
230
Application Programming Reference
Chapter 4: System PMPC APIs
MonitorPhysicalResource
Result Rows
Column Name
Description
ProcId
ID associated with a node. This value is computed as the module number
within a cabinet plus 100 times the cabinet number. Usually formatted for
display as zz9-99. However, this display format can be changed by the user.
Status
Status of the node associated with this record:
• U = Up/online.
• D = Down/offline.
A node is up (U) when it is:
• Configured into the system
• Online
• Capable of actively performing tasks associated with normal Teradata
Database activity
Down (D) represents all other potential states.
AmpCount
Current number of AMPs currently executing on the associated node.
PECount
Current number of active PEs on the associated node.
CPUUse
% of CPU usage not spent being idle. The node-level display is computed
from ResUsageSpma table data as:
PercntUser + PercntService
This value is NULL if certain conditions apply, see “Usage Notes” on page 83
for details.
PrcntKernel
% of CPU resources in idle and waiting for I/O completion. This value is
computed from ResUsageSpma data as follows, where NCPUs is the number
of CPUs:
((CPUIOWAIT/100) / (NCPUs * SampleSec)) * 100
This value is NULL if certain conditions apply, see “Usage Notes” on page 83
for details.
PrcntService
% of CPU resources spent in PDE user service processing. The value is
computed from the ResUsageSpma table data, where x represents the
number of CPUs:
CPUUServ / (x * SampleSec)
Note: This value is NULL if certain conditions apply, see “Usage Notes” on
page 83 for details.
PrcntUser
% of CPU resources spent in non-service user code processing. This value is
computed from the ResUsageSpma table data, where x represents the
number of CPUs:
CPUUExec / (x * SampleSec)
This value is NULL if certain conditions apply, see “Usage Notes” on page 83
for details.
Application Programming Reference
231
Chapter 4: System PMPC APIs
MonitorPhysicalResource
Column Name
Description
DiskUse
% of disk usage per node.
This value is computed from ResUsageSldv table data as follows, assuming n
is the number of vdisks used by this AMP:
(LdvOutReqTime 1 + ... + LdvOutReqTime n) / (n*SampleSec)
The DiskUse field does not take into account overlapping of operations
among multiple storage devices, but it allows for the possibility of multiple
requests for the same device.
This value is NULL if certain conditions apply, see “Usage Notes” on page 83
for details.
DiskReads
Total number of physical disk reads per node during the collection period.
This value is computed from ResUsageSldv table data as follows, assuming n
is the number of ldv devices used by this node:
LdvReads 1 + ... + LdvReads n
This value is NULL if certain conditions apply, see “Usage Notes” on page 83
for details.
DiskWrites
Total number of physical disk writes per node during the collection period.
This value is computed from ResUsageSldv table data as:
LdvWrites 1 + ... + LdvWrites n
This value is NULL if certain conditions apply, see “Usage Notes” on page 83
for details.
DiskOutReqAvg
Average number of outstanding disk requests.
The value is computed from ResUsageSldv table data as follows, assuming n
is the number of ldv controllers used by this node:
( (LdvOutReqSum 1 / NULLIFZERO(LdvOutReqDiv 1)) + … +
(LdvOutReqSum n / NULLIFZERO(LdvOutReqDiv n)) ) / n
The range of the value is typically 0 to 25.
This value is NULL if certain conditions apply, see “Usage Notes” on page 83
for details.
NetAUse
% of BYNET A usage. This is the actual BYNET receiver usage. (The BYNET
transmitter usage is maintained in resource usage separately and is typically
lower than the receiver usage. This is caused by multicasts, where one
transmitter sends a message to many receivers.) This value is computed from
the ResUsageSpma table data as:
((NetSamples - NetTxIdle) / NetSamples) * 100
This value is NULL if certain conditions apply, see “Usage Notes” on page 83
for details.
NetReads
Number of Reads from the BYNET to the node. This value is computed
from the ResUsageSpma table data as:
NetRxCircBrd + NetRxCircPtP
This value is NULL if certain conditions apply, see “Usage Notes” on page 83
for details.
232
Application Programming Reference
Chapter 4: System PMPC APIs
MonitorPhysicalResource
Column Name
Description
NetWrites
Number of messages written from the node to the BYNET during the
collection period.
The value is computed from the ResUsageSpma table data as:
NetTxCircBrd + NetTxCircPtP
Note: This value is NULL if certain conditions apply, see “Usage Notes” on
page 83 for details.
HstBlkRds
Number of message blocks (one or more messages sent in one physical
group) received from all clients.
This value is computed from ResUsageShst data, assuming n is the number
of host channel and network connections on this node:
HostBlockReads1 + ... + HostBlockReadsn
This value is NULL if certain conditions apply, see “Usage Notes” on page 83
for details.
HstBlkWrts
Number of message blocks (that is, one or more messages sent in one
physical group) sent to all hosts.
This value is computed from ResUsageShst data, assuming n is the number
of host channel and network connections on this node:
HostBlockWrites1 + ... + HostBlockWritesn
This value is NULL if certain conditions apply, see “Usage Notes” on page 83
for details.
MemAllocates
Note: This field is obsolete and returns zero or NULL.
MemAllocateKB
Value represents the change in node-level memory. MemAllocateKB
represents a delta from the previous reporting period. It reports negative
values as less memory is used.
This value is calculated from the following ResUsageSpma column:
MemVprAllocKB
This value is NULL if certain conditions apply, see “Usage Notes” on page 83
for details.
MemFailures
Note: This field is obsolete and returns zero or NULL.
MemAgings
Note: This field is obsolete and returns zero or NULL.
NetAUp
Status of the BYNETs (if there are more than two, the first two) on a systemwide basis:
• U = All node BYNETs are up/online.
• D = One or more node BYNETs is down/offline.
• “” = A temporary condition where the BYNET data is not available.
NetBUp
Status of the BYNETs (if there are more than two, the first two) on a systemwide basis:
• U = All node BYNETs are up/online.
• D = One or more node BYNETs is down/offline.
• “” = A temporary condition where the BYNET data is not available.
Application Programming Reference
233
Chapter 4: System PMPC APIs
MonitorPhysicalResource
Example
SELECT t2.* from table (MonitorPhysicalResource()) as t2;
*** Query completed. One row found. 28 columns returned.
*** Total elapsed time was 1 second.
ProcId
Status
AmpCount
PECount
CPUUse
PrcntKernel
PrcntService
PrcntUser
DiskUse
DiskReads
DiskWrites
DiskOutReqAvg
NetAUse
NetBUse
NetReads
NetWrites
HstBlkRds
HstBlkWrts
MemAllocates
MemAllocateKB
MemFailures
MemAgings
NetAUp
NetBUp
234
33
U
2
1
1.33288903698767E 000
9.49683438853716E-001
4.66511162945685E-001
8.66377874041986E-001
2.16594468510497E-001
9.10000000000000E 001
2.19000000000000E 002
7.27535266022437E-003
0.00000000000000E 000
0.00000000000000E 000
0.00000000000000E 000
0.00000000000000E 000
1.00000000000000E 000
1.00000000000000E 000
0.00000000000000E 000
1.64000000000000E 002
0.00000000000000E 000
0.00000000000000E 000
U
U
Application Programming Reference
Chapter 4: System PMPC APIs
MonitorPhysicalSummary
MonitorPhysicalSummary
Purpose
Collects global summary information that includes the following types of information:
•
CPU usage (average, high, and low)
•
Disk usage (average, high, and low)
•
BYNET usage (total, up/down)
•
Rate information (resource logging rate and resource monitoring rate)
•
Current software release and version numbers
Definition
REPLACE FUNCTION SYSLIB.MonitorPhysicalSummary()
RETURNS TABLE
(AvgCPU FLOAT,
AvgDisk FLOAT,
AvgDiskIO FLOAT,
HighCPUUse FLOAT,
HighDisk FLOAT,
HighDiskIO FLOAT,
HighCPUProcId SMALLINT,
HighDiskProcId SMALLINT,
HighDiskIOProcId SMALLINT,
LowCPUUse FLOAT,
LowDisk FLOAT,
LowDiskIO FLOAT,
LowCPUProcId SMALLINT,
LowDiskProcId SMALLINT,
LowDiskIOProocId SMALLINT,
NetUse FLOAT,
NetAUp CHAR(1),
NetBUp CHAR(1),
ResLogging SMALLINT,
ResMonitor SMALLINT,
ReleaseNum VARCHAR(30),
Version VARCHAR(32)
)
.
.
.
;
Usage Notes
The MonitorPhysicalSummary function provides similar functionality to the PMPC
MONITOR PHYSICAL SUMMARY request. For information about this interface, see
“MONITOR PHYSICAL SUMMARY” on page 93.
Application Programming Reference
235
Chapter 4: System PMPC APIs
MonitorPhysicalSummary
Result Rows
Column Name
Description
AvgCPU
Average % CPU usage (CPUUse) time of all online nodes currently in the
Teradata Database configuration.
This value is NULL if certain conditions apply, see “Usage Notes” on page 94
for details.
AvgDisk
Average % disk usage (from DiskUse) of all online nodes currently in the
Teradata Database configuration.
Assuming n is the number of online AMPs in the configuration,
AMPAvgDisk is computed from DiskUse data as:
(DiskUse1 + ... + DiskUsen) / n
This value is NULL if certain conditions apply, see “Usage Notes” on page 94
for details.
AvgDiskIO
Average physical disk DiskReads and DiskWrites of all online AMPs in the
configuration.
Assuming n is the number of online AMPs in the configuration,
AMPAvgDiskIO is computed from DiskReads and DiskWrites data as:
(DiskReads1 + DiskWrites1 + ... + DiskReads1 + DiskWritesn) / n
This value is NULL if certain conditions apply, see “Usage Notes” on page 94
for details.
HighCPUUse
Highest CPUUse number associated with any online node that is currently
part of the Teradata Database configuration.
This value is NULL if certain conditions apply, see “Usage Notes” on page 94
for details.
HighDisk
Highest % disk usage (from DiskUse) associated with any online node that
is currently part of the Teradata Database configuration.
This value is NULL if certain conditions apply, see “Usage Notes” on page 94
for details.
HighDiskIO
ID of a node with DiskReads and DiskWrites equal to the value reported as
HighDiskIO.
This value is NULL if certain conditions apply, see “Usage Notes” on page 94
for details.
HighCPUProcId
ID of a node with CPPUse equal to the value reported as HighCPUUse.
This value is NULL if certain conditions apply, see “Usage Notes” on page 94
for details.
HighDiskProcId
ID of a node with DiskUse equal to the value reported as HighDisk.
This value is NULL if certain conditions apply, see “Usage Notes” on page 94
for details.
236
Application Programming Reference
Chapter 4: System PMPC APIs
MonitorPhysicalSummary
Column Name
Description
HighDiskIOProcId
ID of a node with DiskReads and DiskWrites equal to the value reported as
HighDiskIO.
This value is NULL if certain conditions apply, see “Usage Notes” on page 94
for details.
LowCPUUse
Lowest CPUUse number associated with any online node that is currently
part of the Teradata Database configuration.
This value is NULL if certain conditions apply, see “Usage Notes” on page 94
for details.
LowDisk
Lowest % disk usage (from DiskUse) associated with any online node that is
currently part of the Teradata Database configuration.
This value is NULL if certain conditions apply, see “Usage Notes” on page 94
for details.
LowDiskIO
Lowest DiskReads and DiskWrites number associated with any online node
that is currently part of the Teradata Database configuration.
This value is NULL if certain conditions apply, see “Usage Notes” on page 94
for details.
LowCPUProcId
ID of a node with CPPUse equal to the value reported as LowCPUUse.
This value is NULL if certain conditions apply, see “Usage Notes” on page 94
for details.
LowDiskProcId
ID of a node with DiskUse equal to the value reported as LowDisk.
This value is NULL when LowDisk is NULL.
LowDiskIOProocId
ID of a node with DiskReads and DiskWrites equal to the value reported as
LowDiskIO.
This value is NULL when LowDiskIO is NULL.
NetUse
% of total BYNET use (that is, average of the online BYNETs).
If both BYNETs are up, the value is computed from ResUsageSpma table
data as:
NetUse = Average NetAUse per node / NetCount
where:
• NetCount is 2 if both NetA and NetB are up or 1 if only one of the
BYNET is up.
• Average NetAUse is the sum of all NetAUse of each node divided by the
number of online nodes.
This value is NULL if certain conditions apply, see “Usage Notes” on page 94
for details.
Note: NetUse returns a value of zero because resource usage data is not
currently available.
Application Programming Reference
237
Chapter 4: System PMPC APIs
MonitorPhysicalSummary
Column Name
Description
NetAUp
Status of the BYNETs (if there are more than two, the first two) on a systemwide basis:
• U = All node BYNETs are up/online.
• D = One or more node BYNETs is down/offline.
• “” = A temporary condition where the BYNET data is not available.
NetBUp
Status of the BYNETs (if there are more than two, the first two) on a systemwide basis:
• U = All node BYNETs are up/online.
• D = One or more node BYNETs is down/offline.
• “” = A temporary condition where the BYNET data is not available.
ResLogging
Interval in seconds at which resource usage data is written to one or more
active resource usage database tables.
ResMonitor
Interval in seconds at which all resource usage data is collected in memory
for reporting via the PM/API.
ReleaseNum
Release number of the currently running Teradata Database software (for
example, 14.00.00.00).
This value is supplied by Teradata Database.
Version
Version number of the currently running Teradata Database software (for
example, 14.00.00.00).
This value is supplied by Teradata Database.
Example
SELECT * FROM TABLE (MonitorPhysicalSummary()) AS t1;
*** Query completed. One row found. 22 columns returned.
*** Total elapsed time was 1 second.
AvgCPU
AvgDisk
AvgDiskIO
HighCPUUse
HighDisk
HighDiskIO
HighCPUProcId
HighDiskProcId
HighDiskIOProcId
LowCPUUse
LowDisk
LowDiskIO
LowCPUProcId
LowDiskProcId
LowDiskIOProocId
NetUse
NetAUp
NetBUp
ResLogging
238
0.00000000000000E
3.66666666666667E
2.47300000000000E
0.00000000000000E
3.66666666666667E
2.47300000000000E
33
33
33
0.00000000000000E
3.66666666666667E
2.47300000000000E
33
33
33
0.00000000000000E
000
000
003
000
000
003
000
000
003
000
600
Application Programming Reference
Chapter 4: System PMPC APIs
MonitorPhysicalSummary
ResMonitor
ReleaseNum
Version
Application Programming Reference
600
14.00.00.00
14.00.00.00
239
Chapter 4: System PMPC APIs
MonitorSession
MonitorSession
Purpose
Returns session or request resource usage statistics.
Definition
REPLACE FUNCTION SYSLIB.MonitorSession
(HostIdIn SMALLINT,
UserNameIn VARCHAR(128) CHARACTER SET LATIN,
SessionNoIn INTEGER
)
RETURNS TABLE
(HostId SMALLINT,
SessionNo INTEGER,
LogonPENo SMALLINT,
RunVprocNo SMALLINT,
PartName VARCHAR(16) CHARACTER SET LATIN,
PEstate VARCHAR(18) CHARACTER SET LATIN,
LogonTime VARCHAR(22) CHARACTER SET LATIN,
UserId INTEGER,
LSN INTEGER,
UserName VARCHAR(128),
UserAccount VARCHAR(128),
PECPUsec FLOAT,
XActCount FLOAT,
ReqCount FLOAT,
ReqCacheHits FLOAT,
AMPState VARCHAR(18) CHARACTER SET LATIN,
AMPCPUSec FLOAT,
AMPIO FLOAT,
ReqSpool FLOAT,
Blk1HostId SMALLINT,
Blk1SessNo INTEGER,
Blk1UserId INTEGER,
Blk1Lmode CHAR(1) CHARACTER SET LATIN,
Blk1Otype CHAR(1) CHARACTER SET LATIN,
Blk1ObjDBID INTEGER,
Blk1ObjTID INTEGER,
Blk1Status CHAR(1) CHARACTER SET LATIN,
Blk2HostId SMALLINT,
Blk2SessNo INTEGER,
Blk2UserId INTEGER,
Blk2Lmode CHAR(1) CHARACTER SET LATIN,
Blk2Otype CHAR(1) CHARACTER SET LATIN,
Blk2ObjDBID INTEGER,
Blk2ObjTID INTEGER,
Blk2Status CHAR(1) CHARACTER SET LATIN,
Blk3HostId SMALLINT,
Blk3SessNo INTEGER,
Blk3UserId INTEGER,
Blk3Lmode CHAR(1) CHARACTER SET LATIN,
240
Application Programming Reference
Chapter 4: System PMPC APIs
MonitorSession
Blk3Otype CHAR(1) CHARACTER SET LATIN,
Blk3ObjDBID INTEGER,
Blk3ObjTID INTEGER,
Blk3Status CHAR(1) CHARACTER SET LATIN,
MoreBlockers CHAR(1) CHARACTER SET LATIN,
LogonSource VARCHAR(128),
HotAmp1CPU FLOAT,
HotAmp2CPU FLOAT,
HotAmp3CPU FLOAT,
HotAmp1CPUId FLOAT,
HotAmp2CPUId FLOAT,
HotAmp3CPUId FLOAT,
HotAmp1IO FLOAT,
HotAmp2IO FLOAT,
HotAmp3IO FLOAT,
HotAmp1IOId INTEGER,
HotAmp2IOId INTEGER,
HotAmp3IOId INTEGER,
LowAmp1CPU FLOAT,
LowAmp2CPU FLOAT,
LowAmp3CPU FLOAT,
LowAmp1CPUId INTEGER,
LowAmp2CPUId INTEGER,
LowAmp3CPUId INTEGER,
LowAmp1IO FLOAT,
LowAmp2IO FLOAT,
LowAmp3IO FLOAT,
LowAmp1IOId INTEGER,
LowAmp2IOId INTEGER,
LowAmp3IOId INTEGER,
AvgAmpCPUSec FLOAT,
AvgAmpIOCnt FLOAT,
AmpCount INTEGER,
TempSpaceUsg FLOAT,
ReqStartTime VARCHAR(22) CHARACTER SET LATIN,
ReqCPU FLOAT,
ReqIO FLOAT,
ReqNo INTEGER,
WlcId INTEGER,
DontReclassifyFlag SMALLINT,
ProxyUser VARCHAR (128),
CPUDecayLevel SMALLINT,
IODecayLevel SMALLINT,
TacticalCPUException INTEGER,
TacticalIOException INTEGER,
ReqIOKB FLOAT,
ReqIOPhysIO FLOAT
ReqIOPhysIOKB FLOAT
ReqStepsCompletedCnt INTEGER,
RedriveProtection CHAR (2),
CurrentRedriveParticipation CHAR (1),
ReqPersistentSpoolSpace FLOAT,
)
.
.
.
;
Application Programming Reference
241
Chapter 4: System PMPC APIs
MonitorSession
Input Parameters
Parameter
Description
HostIdIn
Logical ID of a host (or client) with sessions logged on.
A value of -1 indicates all hosts.
UserNameIn
User name of the session.
An asterisk (*) indicates all users.
SessionNoIn
Number of the session.
A value of zero indicates all sessions.
Usage Notes
This table function is only supported in Constant Mode.
The following CPU fields in the MonitorSession response are affected by the
MonSesCPUNormalization field:
•
•
•
•
AMPCPUSec
AvgAmpCPUSec
HotAmp1CPU
HotAmp2CPU
•
•
•
•
HotAmp3CPU
LowAmp1CPU
LowAmp2CPU
LowAmp3CPU
• PECPUSec
• RequestAmpCPU
The MonSesCPUNormalization field, a DBS Control General Record field, controls whether
normalized or non-normalized statistical CPU data is reported by the functions:
MonitorSession and MonitorMySessions, and by the MONITOR SESSION request. For more
information about the MonSesCPUNormalization field and CPU normalization, see the DBS
Control utility in Utilities.
For a complete description of these fields, see the topic that follows.
You can also refer to “MonitorMySessions” on page 211 or “MONITOR SESSION” on
page 101 for a list of these CPU fields.
The MonitorSession function provides similar functionality to the PMPC MONITOR
SESSION request. For information about this interface, see “MONITOR SESSION” on
page 101.
242
Application Programming Reference
Chapter 4: System PMPC APIs
MonitorSession
Result Rows
Column Name
Description
HostId
Logical host ID associated with a PE or session. For a PE,
HostId identifies one of the hosts or LANs associated with the
described PE. For a session, the combination of a host ID and
a session number uniquely identifies a user session on the
system.
Note: This value is NULL for AMPs. A value of zero represents
the Supervisor window.
SessionNo
Number of the current session. Together with a given host ID,
a session number uniquely identifies a session on the Teradata
Database system. This value is assigned by the host (or client)
at logon time.
LogonPENo
Vproc number of the PE the session is currently logged on to;
it identifies the PE that has control responsibility for the
session. Normally, this is the PE that processed the logon
request; but if that PE goes offline, it will be the PE to which
the session was switched.
RunVprocNo
Vproc number of the AMP or PE currently assigned to process
the session requests.
For sessions in Teradata SQL partitions, this value is identical
to the LogonPENo. For sessions in FastLoad or MultiLoad
partitions, this is the AMP that initially processes the data
being loaded. For HUTPARSE or HUTCTL (archive/recovery)
sessions, this value is NULL.
If a RunVprocNo value of -1 in record mode or NULL in
indicator mode is returned by MonitorSession for FastLoad,
MultiLoad or FastExport sessions, this indicates that the
session is in the process of starting up.
PartName
Name of the session partition associated with this session.
Following a successful logon request by a session or as part of a
connect request, the session identifies the partition with which
the user wants the session to be associated. FASTLOAD,
Teradata SQL, MONITOR, INTERNAL are examples of valid
partition names.
PEstate
Current state of the session within the PE. See the MONITOR
SESSION PEState field for a list of the PEState values.
LogonTime
Date and time portion of the information recorded by Session
Control when a session successfully logs on. It is usually
formatted for display as yyyy/mm/dd 99:99:99.99, which
represents the year, month, day, hours: minutes: seconds.
Application Programming Reference
243
Chapter 4: System PMPC APIs
MonitorSession
Column Name
Description
UserId
User or internal ID of a user for this session. Within the
Teradata Database, UserId is equivalent to Database ID.
Typically, UserId is used when the associated record is known
to be a user name, and Database ID is used when the
associated record is known to be a database. However, UserId
can identify either a given user or database name.
LSN
Logon Sequence Number (LSN) that is associated with a
session when the session logs on. It identifies a collection of
sessions performing a related activity. For example, in a
FastLoad job, a user is logged on as a Teradata SQL session, as
well as n FastLoad sessions with the same user name.
Therefore, n+1 sessions (1 Teradata SQL and n FastLoad) with
the same LSN are all associated with the given FastLoad job. To
see how the FastLoad job is doing, the user can pick out all
sessions reported with the same LSN number.
Note: This information supplies the parent-child relationship
for sessions involved with FastLoad, MultiLoad, and Archive/
Recovery jobs.
UserName
User name of the session. This is the name specified when the
user is created; it is used to log on to a session. Within Teradata
Database, user name is almost equivalent to database name.
UserAccount
Account currently with which the user is logged in. When a
user is created or altered, that user is allowed to run in
association with one or more accounts. During the logon
process, a particular user session establishes its priority and
charges resource usage to one of the allowed accounts.
PECPUsec
CPU time, in seconds, used in a PE by the associated session
for parsing and dispatching requests. It is accurate to the
second.
This value is valid only when associated with Teradata SQL
and MONITOR partition sessions.
This value is NULL when it is returned for all other sessions.
XActCount
Number of explicit and implicit transactions executed by the
session.
Note: This value is valid only when returned for Teradata SQL
sessions, and is NULL for all other partition sessions. For this
value, you must make a request for data before completion of
the first collection period that follows either a system outage
or a change in the ResMonitor rate
ReqCount
Number of requests (Tequel Start Request (TSR) messages)
initiated by the session.
Note: This value is NULL when a request for data is made
before completion of the first collection period following
either a system outage or change in the ResMonitor rate.
244
Application Programming Reference
Chapter 4: System PMPC APIs
MonitorSession
Column Name
Description
ReqCacheHits
Number of times that this session processed a request using
information from the Teradata SQL Parser request cache,
specifically, how many times there was a request cache hit.
This value is valid only for Teradata SQL sessions, and is
NULL for all other partition sessions. This value is also NULL
when a request for data is made before completion of the first
collection period following either a system outage or a change
in the ResMonitor rate.
AMPState
Current state of the associated session in AMP vprocs in
decreasing priority:
• ABORTING: The transaction is being rolled back; session
is aborting.
• BLOCKED: Some background activity is in progress and
the last request is on hold until this background activity is
completed.
• ACTIVE: Normal, on-going activity is being done by this
session.
• IDLE: No work in progress for this session on any AMP.
• UNKNOWN: No recorded activity by this session since
monitoring began.
This value is NULL when a request for data is made before
completion of the first collection period following either a
system outage or a change in the SesMonitorLoc or
SesMonitorSys rate.
AMPCPUSec
Current elapsed CPU time, in seconds, used on all AMPs by
the associated session for executing requests. For example, for
Teradata SQL requests, this is the time spent by the Teradata
Database actively working or rolling back an aborted
transaction. This does not include any PDE CPU time spent
handling Teradata Database requests.
This value is NULL when a request for data is made before
completion of the first collection period following either a
system outage or a change in the ResMonitor rate.
AMPIO
Current number of logical Reads and Writes issued across all
AMPs by the associated session.
This value is NULL when a request for data is made before
completion of the first collection period following either a
system outage or a change in the ResMonitor rate.
ReqSpool
Current spool used by current request across all AMPs,
expressed as a number of bytes.
This value is NULL when a request for data is made before
completion of the first collection period following either a
system outage or a change in the ResMonitor rate.
Application Programming Reference
245
Chapter 4: System PMPC APIs
MonitorSession
Column Name
Description
Blk1HostId,
Logical host ID of a session causing a block. This value is
derived from equating the transactions causing a Teradata
Database lock conflict to the sessions that issued those
transactions. The Blk_x_HostId in combination with
Blk_x_SessNo uniquely identifies the session that is causing a
block.
Blk2HostId,
Blk3HostId
A valid value is not returned if an inactive Archive/Recovery
job is causing the lock conflict, because no session is logged in.
This value is NULL if:
• The host ID is not available.
• The session does not have an AMPState of BLOCKED.
If the Blk_x_HostId, Blk_x_SessNo, and Blk_x_UserID values
all return as NULLs and AMPState is BLOCKED, a Host
Utility (HUT) lock left over after the session holding the lock
was aborted or logged off. The lock was never released, and no
blocking information is available because the session no
longer exists.
Use the Show Locks utility to obtain the user name that placed
the HUT lock. For more information, see Utilities.
Blk1SessNo,
Blk2SessNo,
Blk3SessNo
Number of the session causing a block. This value is derived
from associating the transactions causing a lock conflict to the
sessions that issued those transactions. The Blk_x_SessNo in
combination with Blk_x_HostId uniquely identifies the
session causing a block.
This information is unavailable if an inactive Archive/
Recovery job is causing the lock conflict.
This value is NULL if:
• SessNo is not available.
• Session does not have an AMPState of BLOCKED.
• A request for data is made before completion of the first
collection period following either a system outage or a
change in the SesMonitorLoc or SesMonitorSys rate.
If the Blk_x_HostId, Blk_x_SessNo, and Blk_x_UserID values
all return as NULLs and AMPState is BLOCKED, a host utility
lock left over after the session holding the lock was aborted or
logged off. The lock was never released, and no blocking
information is available because the session no longer exists.
Use the Show Locks utility to obtain the user name that placed
the HUT lock. For more information, see Utilities.
246
Application Programming Reference
Chapter 4: System PMPC APIs
MonitorSession
Column Name
Description
Blk1UserId,
ID of the user or host utility job preventing the session from
being granted a lock. This information is especially important
when an Archive/Recovery job is holding the lock, because the
user ID is the only information available about who placed the
lock.
Blk2UserId,
Blk3UserId
This value is NULL if:
• Session does not have an AMPState of BLOCKED.
• A request for data is made before completion of the first
collection period following either a system outage or a
change in the SesMonitorLoc or SesMonitorSys rate.
If the Blk_x_HostId, Blk_x_SessNo, and Blk_x_UserID values
all return as NULLs and AMPState is BLOCKED, a host utility
lock left over after the session holding the lock was aborted or
logged off. The lock was never released, and no blocking
information is available because the session no longer exists.
Use the Show Locks utility to obtain the user name that placed
the HUT lock. For more information, see Utilities.
Blk1Lmode,
Mode (severity) of the lock involved in causing a block:
Blk2Lmode,
• E = Exclusive
• W = Write
• R = Read
• A = Access
Locks are reported in decreasing order of severity because
removing the most severe lock conflict may eliminate the
source of the lock conflict.
Blk3Lmode
This value is NULL if:
• The session does not have an AMPState of BLOCKED.
• A request for data is made before completion of the first
collection period following either a system outage or a
change in the SesMonitorLoc or SesMonitorSys rate.
A session may be blocked by either a granted lock or an
ungranted lock that precedes the blocked lock in the queue
and is in conflict with the lock requested by this blocked
session. For information on whether the lock is granted, see
the MONITOR SESSSION fields: Blk_1_Status, Blk_2_Status,
and Blk_3_Status.
Application Programming Reference
247
Chapter 4: System PMPC APIs
MonitorSession
Column Name
Description
Blk1Otype,
Type of object whose lock is causing the session described by
the associated row to be blocked:
Blk2Otype,
Blk3Otype
• D = Database
• T= Table
• R = Row hash
However, this object is not necessarily the type of object the
blocked session is trying to access. For example, if the session
is requesting a row hash lock, the blocking object could be a
database, table, or row hash.
This value is NULL if:
• Session does not have an AMPState of BLOCKED.
• A request for data is made before completion of the first
collection period following either a system outage or a
change in the SesMonitorLoc or SesMonitorSys rate.
For a Table T, it is possible for User A to block User B with a
table level lock on Table T on AMP_1 and with a Row Hash
Level lock on that same Table T on AMP_2. When that occurs,
the only lock conflict reported is that User B is blocked by User
A on a table.
Blk1ObjDBID,
Blk2ObjDBID,
Blk3ObjDBID
Unique ID of the database object over which a lock conflict is
preventing the session from being granted a lock.
Within the Teradata Database system, Database ID is
equivalent to User ID. Typically, User ID is used when the
associated record is known to be a user name, and Database ID
is used when the associated record is known to be a database.
However, Database ID can identify either a user or database
name.
This value is NULL if:
• The session does not have an AMPState of BLOCKED.
• A request for data is made before completion of the first
collection period following either a system outage or a
change in the SesMonitorLoc or SesMonitorSys rate.
Blk1ObjTID,
Blk2ObjTID,
Unique ID of the table object over which a lock conflict is
preventing the session from being granted a lock.
Blk3ObjTID
This value is NULL if:
• The session does not have an AMPState of BLOCKED.
• The BlkxOType is D.
• A request for data is made before completion of the first
collection period following either a system outage or a
change in the SesMonitorLoc or SesMonitorSys rate.
248
Application Programming Reference
Chapter 4: System PMPC APIs
MonitorSession
Column Name
Description
Blk1Status,
Status of lock causing a block:
Blk2Status,
• W= Waiting
• G = Granted
This value is NULL if:
Blk3Status
• Session does not have an AMPState of BLOCKED.
• A request for data is made before completion of the first
collection period following either a system outage or a
change in the SesMonitorLoc or SesMonitorSys rate.
Note: A lock request may be blocked by either a granted lock
or an ungranted lock that precedes the blocked lock request in
the queue and is in conflict with it.
A status of Waiting has a higher priority than that of Granted
when there is more than one lock involved. For example, for a
given object and a given session, a session that is blocked by a
Waiting lock on one AMP and a Granted lock on another
AMP has Waiting reported as its status.
MoreBlockers
Indicator of more lock conflict:
• Blank = Blkx information is a complete list of sessions
blocking the session described.
• Asterisk (*) = additional sessions are blocking the session
described. The Blkx information shows only three blocking
sessions.
This value is NULL if:
• The state of the session is not BLOCKED.
• A request for data is made before completion of the first
collection period following either a system outage or a
change in the SesMonitorLoc or SesMonitorSys rate.
LogonSource
Logon source information. At logon time, this information is
optionally supplied by the Teradata Director Program or the
LAN Gateway to further identify the physical or logical
location of the session, the logon user name, and the interface
under which the session was initiated. (For example, the data
string may include DBC as the user ID and BTEQ as the
interface.)
Note: A two-byte value precedes the LogonSource data to
indicate the length of the string. The length value is zero if
LogonSource is NULL.
For a list of the commonly seen LogonSource string
application names, see SQL Data Definition Language.
HotAmp1CPU
CPU time of the highest CPU utilized AMP during the
collection interval.
This value is NULL if the request is made before the collection
period expires.
Application Programming Reference
249
Chapter 4: System PMPC APIs
MonitorSession
Column Name
Description
HotAmp2CPU
CPU time of the second highest CPU utilized AMP during the
collection interval.
This value is NULL if the request is made before the collection
period expires.
HotAmp3CPU
CPU time of the third highest CPU utilized AMP during the
collection interval.
This value is NULL if the request is made before the collection
period expires, and if there are only two AMPs on the system.
HotAmp1CPUId
Vproc ID of the highest CPU utilized AMP for the last session
collection interval.
This value is NULL if the request is made before the collection
period expires.
HotAmp2CPUId
Vproc ID of the second highest CPU utilized AMP for the last
session collection interval.
This value is NULL if the request is made before the collection
period expires.
HotAmp3CPUId
Vproc ID of the third highest CPU utilized AMP for the last
session collection interval.
This value is NULL if the request is made before the collection
period expires, and if there are only two AMPs in the system.
HotAmp1IO
IO count of the highest IO utilized AMP during the collection
interval.
This value is NULL if the request is made before the collection
period expires.
HotAmp2IO
IO count of the second highest IO utilized AMP during the
collection interval.
This value is NULL if the request is made before the collection
period expires.
HotAmp3IO
IO count of the third highest IO utilized AMP for the last
collection interval.
This value is NULL if the request is made before the collection
period expires, and if there are only two AMPs in the system.
HotAmp1IOId
Vproc ID of the highest IO utilized AMP for the last session
collection interval.
This value is NULL if the request is made before the collection
period expires.
HotAmp2IOId
Vproc ID of the second highest IO utilized AMP for the last
session collection interval.
This value is NULL if the request is made before the collection
period expires.
250
Application Programming Reference
Chapter 4: System PMPC APIs
MonitorSession
Column Name
Description
HotAmp3IOId
Vproc ID of the third highest IO utilized AMP for the last
session collection interval.
This value is NULL if the request is made before the collection
period expires, and if there are only two AMPs in the system.
LowAmp1CPU
CPU time of the lowest CPU utilized AMP during the
collection interval.
This value is NULL if the request is made before the collection
period expires.
LowAmp2CPU
CPU time of the second lowest CPU utilized AMP during the
collection interval.
This value is NULL if the request is made before the collection
period expires.
LowAmp3CPU
CPU time of the third lowest CPU utilized AMP during the
collection interval.
This value is NULL if the request is made before the collection
period expires, and if there are only two AMPs on the system.
LowAmp1CPUId
Vproc ID of the lowest CPU utilized AMP for the last session
collection interval.
This value is NULL if the request is made before the collection
period expires.
LowAmp2CPUId
Vproc ID of the second lowest CPU utilized AMP for the last
session collection interval.
This value is NULL if the request is made before the collection
period expires.
LowAmp3CPUId
Vproc ID of the third lowest CPU utilized AMP for the last
session collection interval.
This value is NULL if the request is made before the collection
period expires, and if there are only two AMPs on the system.
LowAmp1IO
IO count of the lowest IO utilized AMP during the collection
interval.
This value is NULL if the request is made before the collection
period expires.
LowAmp2IO
IO count of the second lowest IO utilized AMP during the
collection interval.
This value is NULL if the request is made before the collection
period expires.
LowAmp3IO
IO count of the third lowest IO utilized AMP during the
collection interval.
This value is NULL if the request is made before the collection
period expires, and if there are only two AMPs on the system.
Application Programming Reference
251
Chapter 4: System PMPC APIs
MonitorSession
Column Name
Description
LowAmp1IOId
Vproc ID of the lowest IO utilized AMP for the last session
collection interval.
This value is NULL if the request is made before the collection
period expires.
LowAmp2IOId
Vproc ID of the second lowest IO utilized AMP for the last
session collection interval.
This value is NULL if the request is made before the collection
period expires.
LowAmp3IOId
Vproc ID of the third lowest IO utilized AMP for the last
session collection interval.
This value is NULL if the request is made before the collection
period expires, and if there are only two AMPs on the system.
AvgAmpCPUSec
Average AMP CPU utilization for the last session collection
interval. The average is calculated as the sum of CPU
utilization for all amps participating divided by the number of
online AMPs.
This value is NULL if the request is made before the collection
period expires.
AvgAmpIOCnt
Average AMP IO utilization for the last session collection
interval. The average is calculated as the sum of IO utilization
for all AMPs participating divided by the number of online
AMPs.
This value is NULL if the request is made before the collection
period expires.
AmpCount
Current number of AMPs currently executing on the
associated node.
TempSpaceUsg
Total amount, in bytes, of temporary space used by the
session.
This value is NULL if the session did not materialize any
temporary tables.
ReqStartTime
Date and time of the current request on the session started. It
is usually formatted for display as yyyy/mm/dd 99:99:99.99,
which represents the year, month, day hours: minutes:
seconds.
ReqCPU
Total CPU usage by the current SQL request on the session on
all AMPs. This value contains proper request-level statistics for
DBC/SQL sessions running SQL requests only. Ignore the
value returned in this field for other types of sessions, such as
DBC/SQL sessions linked to a utility job.
This field is equivalent to the MONITOR SESSION field
RequestAmpCPU.
252
Application Programming Reference
Chapter 4: System PMPC APIs
MonitorSession
Column Name
Description
ReqIO
Total number of accesses by the current SQL request for the
session on all AMPs. This value contains proper request-level
statistics for DBC/SQL sessions running SQL requests only.
Ignore the value returned in this field for other types of
sessions, such as DBC/SQL sessions linked to a utility job.
This field is equivalent to the MONITOR SESSION field
RequestAmpI/O.
ReqNo
Active request number.
If no request is running, then a value of zero or NULL is
displayed in indicator mode.
WDId
Workload ID associated with the specified request.
DontReclassifyFlag
Flag indicating that the next request on the session will not be
classified but will use the WD ID already assigned to the
session. This will occur if this is a utility session or a WlcId was
assigned to the session using the TDWMAssignWD function
or the TDWM WD ASSIGNMENT request. For more
information on these APIs, see Chapter 5: “Teradata Dynamic
Workload Management APIs.”
ProxyUser
Name of the proxy user if this session has a proxy connection.
CPUDecayLevel
Current most severe decay level as reached due to CPU usage.
Note: Nodes can be at different levels of decay (for example, 0,
1, or 2).
IODecayLevel
Current most severe decay level as reached due to I/O usage.
Note: Nodes can be at different levels of decay (for example, 0,
1, or 2).
TacticalCPUException
Number of nodes that encountered a CPU exception.
TacticalIOException
Number of nodes that encountered an I/O exception.
ReqIOKB
Total logical I/O usage in KB.
ReqIOPhysIO
Number of physical I/Os.
ReqIOPhysIOKB
Physical I/O usage in KB.
ReqStepsCompletedCnt
Count of completed steps for the current request. No change
in ReqStepsCompletedCnt from the previous Monitor Session
collection indicates no new steps completed.
RedriveProtection
Note: This field is reserved for future use.
CurrentRedriveParticipation
Note: This field is reserved for future use.
ReqPersistentSpoolSpace
Note: This field is reserved for future use.
Example
SELECT * FROM TABLE (MonitorSession(1,'*',1008)) AS t2;
Application Programming Reference
253
Chapter 4: System PMPC APIs
MonitorSession
*** Query completed. One row found. 91 columns returned.
*** Total elapsed time was 2 seconds.
HostId
SessionNo
LogonPENo
RunVprocNo
PartName
PEstate
LogonTime
UserId
LSN
UserName
UserAccount
PECPUsec
XActCount
ReqCount
ReqCacheHits
AMPState
AMPCPUSec
AMPIO
ReqSpool
Blk1HostId
Blk1SessNo
Blk1UserId
Blk1Lmode
Blk1Otype
Blk1ObjDBID
Blk1ObjTID
Blk1Status
Blk2HostId
Blk2SessNo
Blk2UserId
Blk2Lmode
Blk2Otype
Blk2ObjDBID
Blk2ObjTID
Blk2Status
Blk3HostId
Blk3SessNo
Blk3UserId
Blk3Lmode
Blk3Otype
Blk3ObjDBID
Blk3ObjTID
Blk3Status
MoreBlockers
LogonSource
HotAmp1CPU
HotAmp2CPU
HotAmp3CPU
HotAmp1CPUId
HotAmp2CPUId
HotAmp3CPUId
HotAmp1IO
HotAmp2IO
HotAmp3IO
HotAmp1IOId
254
1
1008
16383
16383
DBC/SQL
DISPATCHING
2011/10/07 18:13:35.00
1017
0
JCK
DBC
2.40000000000000E-002
1.00000000000000E 000
2.00000000000000E 000
0.00000000000000E 000
ACTIVE
3.13344000000000E 002
9.65310000000000E 004
1.20341288960000E 010
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
(TCP/IP) 10ea 141.206.34.113 MYSYSTEM
2.79200000000000E 000
2.76400000000000E 000
2.76400000000000E 000
3
2
1
8.44000000000000E 002
8.44000000000000E 002
8.43000000000000E 002
2
11768
Application Programming Reference
Chapter 4: System PMPC APIs
MonitorSession
HotAmp2IOId
0
HotAmp3IOId
1
LowAmp1CPU 2.70400000000000E 000
LowAmp2CPU 2.76400000000000E 000
LowAmp3CPU 2.76400000000000E 000
LowAmp1CPUId
0
LowAmp2CPUId
1
LowAmp3CPUId
2
LowAmp1IO 8.43000000000000E 002
LowAmp2IO 8.43000000000000E 002
LowAmp3IO 8.44000000000000E 002
LowAmp1IOId
3
LowAmp2IOId
1
LowAmp3IOId
2
AvgAmpCPUSec 2.75600000000000E 000
AvgAmpIOCnt 8.43500000000000E 002
AmpCount
4
TempSpaceUsg 0.00000000000000E 000
ReqStartTime 2011/10/07 18:13:35.00
ReqCPU 3.13344000000000E 002
ReqIO 9.65310000000000E 004
ReqNo
3
WlcId
0
DontReclassifyFlag
255
ProxyUser
CPUDecayLevel
0
IODecayLevel
0
TacticalCPUException
0
TacticalIOException
0
ReqIOKB 1.19556590000000E 007
ReqPhysIO 1.18900000000000E 003
ReqPhysIOKB 8.32590000000000E 004
ReqStepsCompletedCnt
9
RedriveProtection DF
CurrentRedriveParticipation F
ReqRedriveSpoolSpace 0.00000000000000E 00
Application Programming Reference
255
Chapter 4: System PMPC APIs
MonitorSessionRate
MonitorSessionRate
Purpose
Returns session rate.
Definition
REPLACE FUNCTION SYSLIB.MonitorSessionRate
(HostIdIn SMALLINT,
UserNameIn VARCHAR(128) CHARACTER SET LATIN,,
SessioNoIn INTEGER
)
RETURNS SMALLINT
.
.
.
;
Input Parameters
Parameter
Description
HostIdIn
Logical ID of a host (or client) with sessions logged on.
A value of -1 indicates all hosts.
UserNameIn
User name of the specified sessions.
An asterisk (*) indicates all users.
SessionNoIn
Number of the specified session.
A value of zero indicates all sessions.
Usage Notes
Before you monitor the collection rate, you use the SetSessionRate function to set the
collection rate for updating session-level statistics in memory.
The MonitorSessionRate function provides similar functionality to the PMPC Monitor
Session request. For information about this interface, see “MONITOR SESSION” on
page 101.
Return Value
This function returns the collection rate (that is, the duration of the collection period in
seconds).
256
Application Programming Reference
Chapter 4: System PMPC APIs
MonitorSessionRate
Example
SELECT MonitorSessionRate(1,'*',0);
*** Query completed. One row found. One column returned.
*** Total elapsed time was 7 seconds.
MonitorSessionRate(1, '*', 0)
----------------------------60
Application Programming Reference
257
Chapter 4: System PMPC APIs
MonitorSQLCurrentStep
MonitorSQLCurrentStep
Purpose
Returns data about the step being executed of the currently running request for the specified
host, session, and vproc.
Definition
REPLACE FUNCTION SYSLIB.MonitorSQLCurrentStep
(HostIdIn
SMALLINT,
SessionNoIn
INTEGER,
RunVProcNo
SMALLINT)
RETURNS TABLE
(HostId
SMALLINT,
SessionNo
INTEGER,
NumOfSteps
SMALLINT,
CurLvl1StepNo SMALLINT,
CurLvl2StepNo SMALLINT
)
.
.
.
;
Input Parameters
Parameter
Description
HostIdIn
Logical ID of a host (or client) with sessions logged on.
SessionNoIn
Session number of the SQL to monitor.
RunVprocNo
PE vproc number where the session runs.
Usage Notes
This table function is only supported in Constant Mode.
If MONITOR SQL processing is not completed within the timeout interval, then an error is
returned to the client application. When a MONITOR SQL request is timed out, the
processing continues internally to its completion. If the client application submits a new
MONITOR SQL request for the same timed out target session while the previous timed out
one is still being processed, then an error is returned.
The timeout interval can be set in the DBS Control field, PMPC_TimeoutSecs. The default
timeout interval is 60 seconds. If the PMPC_TimeoutSecs field is set to zero, the MONITOR
SQL timeout request will be disabled and no timeout will occur. For more information on the
PMPC_TimeoutSecs field, see Utilities.
258
Application Programming Reference
Chapter 4: System PMPC APIs
MonitorSQLCurrentStep
The MonitorSQLCurrentStep function provides similar functionality to the PMPC
MONITOR SQL request. For information about this interface, see “MONITOR SQL” on
page 128.
Result Rows
Column Name
Description
HostId
Logical host ID associated with a PE or session. For a PE, HostId identifies one
of the hosts or LANs associated with the described PE. For a session, the
combination of a host ID and a session number uniquely identifies a user
session on the system.
Note: This value is NULL for AMPs. A value of zero represents the Supervisor
window.
SessionNo
Number of the current session. Together with a given host ID, a session
number uniquely identifies a session on the Teradata Database system. This
value is assigned by the host (or client) at logon time.
NumOfSteps
Number of steps contained in the description text.
CurLvl1StepNo
Number of the currently executing step. If parallel steps are executing, it is the
number of the lowest executing step.
CurLvl2StepNo
Number of the currently executing step. If parallel steps are executing, it is the
number of the highest executing step. If only one step is executing,
CurLvl1StepNo and CurLvl2StepNo are identical.
Example
SELECT * FROM TABLE(MonitorSQLCurrentStep(1, 1083, 16383)) AS t1;
*** Query completed. One row found. 5 columns returned.
*** Total elapsed time was 1 second.
HostId
SessionNo
NumOfSteps
CurLvl1StepNo
CurLvl2StepNo
1
1083
4
1
1
BTEQ -- Enter your DBC/SQL request or BTEQ command:
Application Programming Reference
259
Chapter 4: System PMPC APIs
MonitorSQLSteps
MonitorSQLSteps
Purpose
Returns the step information (that is, a scaled-down version of the output of the EXPLAIN
request modifier) of the current or running request for the specified host, session, and vproc.
Definition
REPLACE FUNCTION SYSLIB.MonitorSQLSteps
(HostIdIn
SMALLINT,
SessionNoIn INTEGER,
RunVProcNo
SMALLINT)
RETURNS TABLE
(HostId
SMALLINT,
SessionNo INTEGER,
StepNum
INTEGER,
Confidence SMALLINT,
EstRowCount FLOAT,
ActRowCount FLOAT,
EstElapsedTime FLOAT,
ActElapsedTime FLOAT,
SQLStep VARCHAR(1024)
)
.
.
.
;
Input Parameters
Parameter
Description
HostIdIn
Logical ID of a host (or client) with sessions logged on.
SessionNoIn
Session number of the SQL to monitor.
RunVprocNo
PE vproc number where the session runs.
Usage Notes
This table function is only supported in Constant Mode.
If MONITOR SQL processing is not completed within the timeout interval, then an error is
returned to the client application. When a MONITOR SQL request is timed out, the
processing continues internally to its completion. If the client application submits a new
MONITOR SQL request for the same timed out target session while the previous timed out
one is still being processed, then an error is returned.
260
Application Programming Reference
Chapter 4: System PMPC APIs
MonitorSQLSteps
The timeout interval can be set in the DBS Control field, PMPC_TimeoutSecs. The default
timeout interval is 60 seconds. If the PMPC_TimeoutSecs field is set to zero, the MONITOR
SQL timeout request will be disabled and no timeout will occur. For more information on the
PMPC_TimeoutSecs field, see Utilities.
The MonitorSQLSteps function provides similar functionality to the PMPC MONITOR SQL
request. For information about this interface, see “MONITOR SQL” on page 128.
Result Rows
Column Name
Description
HostId
Logical host ID associated with a PE or session. For a PE, HostId identifies one
of the hosts or LANs associated with the described PE. For a session, the
combination of a host ID and a session number uniquely identifies a user
session on the system.
Note: This value is NULL for AMPs. A value of zero represents the Supervisor
window.
SessionNo
Number of the current session. Together with a given host ID, a session
number uniquely identifies a session on the Teradata Database system. This
value is assigned by the host (or client) at logon time.
StepNum
Unique number identifying the EXPLAIN step.
Confidence
Confidence level as determined by the optimizer:
•
•
•
•
0 = None
1= Foreign Key
2 = Low
3 = High
EstRowCount
Row count generated from the Optimizer plan.
ActRowCount
Row count that is returned from the AMP for this step.
EstElapsedTime
Estimated time for the query as generated from the Optimizer plan.
ActElapsedTime
Actual elapsed time calculated by the dispatcher.
SQLStep
Generated text for the step.
Example
SELECT t2.StepNum, t2.EstRowCount, t2.SQLStep FROM
TABLE (MonitorSQLSteps(1, 1001, 16382)) AS t2;
*** Query completed. 12 rows found. 3 columns returned.
*** Total elapsed time was 38 seconds.
StepNum
EstRowCount SQLStep
------- ---------------------- ------------------------------------------1 0.00000000000000E 000 First, lock DBAAA."pseudo table" for read on a row hash.
2 0.00000000000000E 000 Next, we lock DBAAA.SKEWAMP1 for read.
3 1.25440000000000E 004 We do an All-AMPs RETRIEVE step from DBAAA.SKEWAMP1 by
way of an all-rows scan into Spool 6, which is duplicated on all AMPs. This step begins
a parallel block of steps.
Application Programming Reference
261
Chapter 4: System PMPC APIs
MonitorSQLSteps
3 1.25440000000000E 004 We do an All-AMPs RETRIEVE step from DBAAA.SKEWAMP1 by
way of an all-rows scan into Spool 7, which is duplicated on all AMPs. This step is
performed in parallel.
3 1.25440000000000E 004 We do an All-AMPs RETRIEVE step from DBAAA.SKEWAMP1 by
way of an all-rows scan into Spool 8, which is duplicated on all AMPs. This step ends
a parallel block of steps.
4 2.45862400000000E 006 We do an All-AMPs JOIN step from Spool 6 (Last Use) by
way of an all-rows scan, which is joined to table SKEWAMP1. Spool 6 and table SKEWAMP1
are joined using a product join. The result goes into Spool 9, which is built
4 1.25440000000000E 004 We do an All-AMPs RETRIEVE step from DBAAA. SKEWAMP1 by
way of an all-rows scan into Spool 10, which is duplicated on all AMPs. This step is
performed in parallel.
4 2.45862400000000E 006 We do an All-AMPs JOIN step from Spool 7 (Last Use) by
way of an all-rows scan, which is joined to table SKEWAMP1. Spool 7 and table SKEWAMP1
are joined using aproduct join The result goes into Spool 11, which is built
5 3.85512243200000E 009 We do an All-AMPs JOIN step from Spool 8 (Last Use) by
way of an all-rows scan, which is joined to Spool 9. Spool 8 and Spool
9 are joined using a product join. The result goes into Spool 12, which is built
locally on the AMPs. This step begins a parallel block of
5 3.08409794560000E 010 We do an All-AMPs JOIN step from Spool 10 (Last Use) by
way of an all-rows scan, which is joined to Spool 11. Spool 10 and Spool 11 are joined
using a product join. The result goes into Spool 13, which is duplicated on all AMPs.
This step ends a parallel block of
6 1.48619689657096E 019 We do an All-AMPs JOIN step from Spool 12 (Last Use) by
way of an all-rows scan, which is joined to Spool 13. Spool 12 and Spool 13 are joined
using a product join. The result goes into Spool 5, which is built locally on the AMPs.
7 0.00000000000000E 000 We send out an END TRANSACTION step to all AMPs involved
in processing the request.
262
Application Programming Reference
Chapter 4: System PMPC APIs
MonitorSQLText
MonitorSQLText
Purpose
Returns the SQL text of the request currently being executed for the specified host, session,
and vproc.
Definition
REPLACE FUNCTION SYSLIB.MonitorSQLText
(HostIdIn
SMALLINT,
SessionNoIn INTEGER,
RunVProcNo
SMALLINT
)
RETURNS TABLE
(HostId
SMALLINT,
SessionNo
INTEGER,
SeqNum
SMALLINT,
SQLTxt
VARCHAR(31000)
)
.
.
.
;
Input Parameters
Parameter
Description
HostIdIn
Logical ID of a host (or client) with sessions logged on.
SessionNoIn
Session number of the SQL to monitor.
RunVprocNo
PE vproc number where the session runs.
Usage Notes
This table function is only supported in Constant Mode.
If MONITOR SQL processing is not completed within the timeout interval, then an error is
returned to the client application. When a MONITOR SQL request is timed out, the
processing continues internally to its completion. If the client application submits a new
MONITOR SQL request for the same timed out target session while the previous timed out
one is still being processed, then an error is returned.
The timeout interval can be set in the DBS Control field, PMPC_TimeoutSecs. The default
timeout interval is 60 seconds. If the PMPC_TimeoutSecs field is set to zero, the MONITOR
SQL timeout request will be disabled and no timeout will occur. For more information on the
PMPC_TimeoutSecs field, see Utilities.
Application Programming Reference
263
Chapter 4: System PMPC APIs
MonitorSQLText
The MonitorSQLText function provides similar functionality to the PMPC MONITOR SQL
request. For information about this interface, see “MONITOR SQL” on page 128.
Result Rows
Column Name
Description
HostId
Host ID of the SQLtext.
SessionNo
Session number of the SQLtext.
SeqNum
Sequence number of the row. For example, if the SQL text exceeds 31,000
bytes, then the system will return multiple rows.
SQLTxt
SQL text of the running request.
Example
SELECT SQLTxt FROM TABLE (MonitorSQLText(1, 1001, 16383)) AS t2;
*** Query completed. One row found. One column returned.
*** Total elapsed time was 58 seconds.
SQLTxt
-----------------------------------------------------------------------select a11.c1, a12.c1, a13.c1, a21.c1, a22.c1, a23.c1 from
dbaaa.skewAmp1
a11, dbaaa.skewAmp1 a12, dbaaa.skewAmp1 a13, dbaaa.skewAmp1 a21,
dbaaa.sk
ewAmp1 a22, dbaaa.skewAmp1 a23;
264
Application Programming Reference
Chapter 4: System PMPC APIs
MonitorSystemPhysicalConfig
MonitorSystemPhysicalConfig
Purpose
Returns BYNET status and system type values that are generated once for the whole system.
Definition
REPLACE FUNCTION SYSLIB.MonitorSystemPhysicalConfig()
RETURNS TABLE
(NetAUp
CHAR,
NetBUp
CHAR,
SystemType VARCHAR(7)
)
.
.
.
;
Usage Notes
The MonitorSystemPhysicalConfig function provides similar functionality to Statement Type
1 of the MONITOR PHYSICAL CONFIG request. For more information, see “MONITOR
PHYSICAL CONFIG” on page 77.
Result Rows
Column Name
Description
NetAUp
Status of the BYNETs (if there are more than two, the first two) on a
system-wide basis:
• U = All node BYNETs are up/online.
• D = One or more node BYNETs is down/offline.
• “” = A temporary condition where the BYNET data is not
available.
NetBUp
Status of the BYNETs (if there are more than two, the first two) on a
system-wide basis:
• U = All node BYNETs are up/online.
• D = One or more node BYNETs is down/offline.
• “” = A temporary condition where the BYNET data is not
available.
Application Programming Reference
265
Chapter 4: System PMPC APIs
MonitorSystemPhysicalConfig
Column Name
Description
SystemType
Type of system running the Teradata Database software, such as 3400,
3500, 5100, or ‘Other’.
If all the nodes in the system are the same type, this field returns the
type of the system.
If any of the nodes are of a different type, this field returns ‘Mixed’.
Example
SELECT * FROM TABLE (MonitorSystemPhysicalConfig()) AS t1;
*** Query completed. One row found. 3 columns returned.
*** Total elapsed time was 2 seconds.
NetAUp
-----U
266
NetBUp
-----U
SystemType
---------4475
Application Programming Reference
Chapter 4: System PMPC APIs
MonitorVirtualConfig
MonitorVirtualConfig
Purpose
Collects information on virtual processor (vproc) availability.
Definition
REPLACE FUNCTION SYSLIB.MonitorVirtualConfig()
RETURNS TABLE
(ProcId SMALLINT,
VprocNo SMALLINT,
Vproctype VARCHAR(3),
HostId SMALLINT,
Status CHAR,
DiskSlice SMALLINT
)
.
.
.
;
Usage Notes
The MonitorVirtualConfig function provides similar functionality to the PMPC MONITOR
VIRTUAL CONFIG request. For more information, see “MONITOR VIRTUAL CONFIG” on
page 139.
Result Rows
Column Name
Description
ProcId
ID associated with a node. This value is computed as the module number
within a cabinet plus 100 times the cabinet number. Usually formatted for
display as zz9-99. However, this display format can be changed by the user.
VprocNo
ID of an AMP (that is, a set of disks and the associated tasks or processes that,
in combination, make up the AMP), PE, or TVS vproc.
Vproctype
Type of vproc:
• AMP
• PE
• MISC
Application Programming Reference
267
Chapter 4: System PMPC APIs
MonitorVirtualConfig
Column Name
Description
HostId
Logical host ID associated with a PE or session. For a PE, HostId identifies one
of the hosts or LANs associated with the described PE. For a session, the
combination of a host ID and a session number uniquely identifies a user
session on the system.
Note: This value is NULL for AMP and TVS vprocs. A value of zero represents
the Supervisor window.
Status
Status of the vproc associated with this record. A vproc is considered up or
down from the standpoint of whether the vproc is helping a query process SQL
statements. For example, an AMP doing offline recovery is considered to be
down because the AMP is not helping to process SQL statements. On the other
hand, an up vproc is one that is online and fully up or is in online recovery.
The status of the vproc:
• U = The vproc is up/online.
• D = The vproc is down/offline.
DiskSlice
Virtual disk ID defining the portion of a physical disk assigned to an AMP.
This value is NULL for TVS vprocs.
Example
SELECT t2.* FROM TABLE (MonitorVirtualConfig()) AS t2;
*** Query completed. 9 rows found. 6 columns returned.
*** Total elapsed time was 4 seconds.
ProcId
----------134
134
134
134
135
134
135
135
134
268
VprocNo
----------0
1
2
3
10237
10238
16380
16381
16382
Vproctype
--------AMP
AMP
AMP
AMP
TVS
TVS
PE
PE
PE
HostId
-----0
0
0
0
0
0
0
0
0
Status
-----U
U
U
U
U
U
U
U
U
DiskSlice
---------1
-1
-1
-1
0
0
0
0
0
Application Programming Reference
Chapter 4: System PMPC APIs
MonitorVirtualResource
MonitorVirtualResource
Purpose
Collects performance information for each AMP, PE, or TVS vproc.
Definition
REPLACE FUNCTION SYSLIB.MonitorVirtualResource()
RETURNS TABLE
(VprocNo SMALLINT,
VprocType VARCHAR(3),
Status CHAR,
ProcId SMALLINT,
ClusterNo SMALLINT,
SessLogCount SMALLINT,
SessRunCount SMALLINT,
CPUUse FLOAT,
PctService FLOAT,
PctAMPWT FLOAT,
DiskUse FLOAT,
DiskReads FLOAT,
DiskWrites FLOAT,
DiskOutReqAvg FLOAT,
PctParser FLOAT,
PctDispatcher FLOAT,
HstBlkRds FLOAT,
HstBlkWrts FLOAT,
NetReads FLOAT,
NetWrites FLOAT,
NVMemAllocSegs FLOAT
)
.
.
.
;
Usage Notes
The MonitorVirtualResource function provides similar functionality to the PMPC
MONITOR VIRTUAL RESOURCE request. For information about this interface, see
“MONITOR VIRTUAL RESOURCE” on page 146.
For information on the resource usage tables and columns described in the field descriptions
below, see Resource Usage Macros and Tables.
Application Programming Reference
269
Chapter 4: System PMPC APIs
MonitorVirtualResource
Result Rows
Column Name
Description
VprocNo
ID of an AMP (that is, a set of disks and the associated tasks or processes that,
in combination, make up the AMP), PE or TVS vproc.
VprocType
Type of vproc:
• AMP
• PE
• MISC
Status
Status of the node, AMP, PE, or TVS vproc associated with this record:
• U = Up/online.
• D = Down/offline.
A node is up (U) when it is:
• Configured into the system
• Online
• Capable of actively performing tasks associated with normal Teradata
Database activity
Down (D) represents all other potential states.
ProcId
ID associated with a node. This value is computed as the module number
within a cabinet plus 100 times the cabinet number. Usually formatted for
display as zz9-99. However, this display format can be changed by the user.
ClusterNo
Number that identifies the cluster to which this AMP has been assigned.
Note: ClusterNo is not applicable to TVS vproc and returns NULL.
SessLogCount
Number of current sessions logged to this PE. A logged on session is either a
session whose logon request was delivered to this PE, or a session that was
switched to this PE following its logon.
Note: The SessLogCount field contains the SubPoolId if the vproc type is TVS.
SubpoolId identifies the subpool associated with the allocator vproc. A
subpool defines a set of storage and allocator vprocs assigned to that storage.
This value is NULL if certain conditions apply, see “Usage Notes” on page 146
for more information.
270
Application Programming Reference
Chapter 4: System PMPC APIs
MonitorVirtualResource
Column Name
Description
SessRunCount
Number of current sessions whose Initiate Requests (TSR messages) are
addressed to this vproc. For example:
• PEs have a SessRunCount that includes all the Teradata SQL and
MONITOR sessions logged on to that PE.
• AMPs may have a nonzero SessRunCount, since AMPs receive TSR
messages from FastLoad or MultiLoad logons.
Note: Sessions involving Archive/Recovery jobs are not included in this
SessRunCount because HUT sessions do not deliver TSR messages to a fixed
AMP or PE.
This value is NULL if certain conditions apply, see “Usage Notes” on page 146
for more information.
Note: This field is not applicable to TVS vprocs.
CPUUse
% of CPU usage not spent being idle.
This value is computed from ResUsageSvpr table data, where NCPUs is the
number of CPUs in the node:
100.00 * (CPUUExecPart00 + CPUUExecPart01 + ... + CPUUExecPart47 +
CPUUServPart00 + CPUUServPart01 + ... + CPUUServPart47) / (NCPUs *
SampleSec * 100)
This value is NULL if certain conditions apply, see “Usage Notes” on page 146
for more information.
PctService
% of CPU resources spent in PDE user service processing.
This value is computed from the ResUsageSvpr table data, where x represents
the number of CPUs:
(CPUUServPart00 + CPUUServPart01 + ... + CPUUServPart47) /(x *
SampleSec)
This value is NULL if certain conditions apply, see “Usage Notes” on page 146
for more information.
PctAMPWT
% of CPU resources used by either the AMP Worker Task (Partition 11) or by
the TVS Task (Partition 31) depending on the type of vproc this record
represents.
This value depends on the number of CPUs in the node but does not exceed
100%. It is computed from the ResUsageSvpr table data, where x represents the
number of CPUs on a node:
For AMP vprocs:
(CPUUExecPart11) / (x * SampleSec)
For TVS vprocs:
(CPUUExecPart31) / (x * SampleSec)
This value is NULL if certain conditions apply, see “Usage Notes” on page 146
for more information.
Application Programming Reference
271
Chapter 4: System PMPC APIs
MonitorVirtualResource
Column Name
Description
DiskUse
% of disk usage per AMP. This value is computed from the ResUsageSvdsk
table data, assuming n is the number of vdisks used by this AMP:
(OutReqTime 1 + ... + OutReqTime n) / SampleSec
Note: DiskUse does not take into account overlapping of operations among
multiple storage controllers, but it allows for the possibility of multiple
requests for the same controller.
This value is NULL if certain conditions apply, see “Usage Notes” on page 146
for more information.
DiskReads
Total number of physical disk reads per AMP during the collection period.
This value is computed from the ResUsageSvpr table data as:
FilePCiAcqReads + FilePDbAcqReads + FileSciAcqReads + FileSDbAcqReads
+ FileTjtAcqReads + FileAPtAcqReads
This value is NULL if certain conditions apply, see “Usage Notes” on page 146
for more information.
Note: This field is not applicable to TVS and PE vprocs.
DiskWrites
Total number of physical disk writes per AMP during the collection period.
For PE and AMP-level displays, this value is computed from ResUsageSvpr
table data as:
FilePCiFWrites + FilePDbFWrites + FileSCiFWrites + FilesDbFWrites +
FileTjtFWrites + FileAPtFWrites + FilePCiDyaWrites + FilePDbDyaWrites +
FileSciDyaWrites + FilesDbDyaWrites + FileTjtDyaWrites + FileAptDyaWrites
For TVS vproc displays, this value is computed from ResUsageSvpr table data
as:
AllocatorMapIOsDone
This value is NULL if certain conditions apply, see “Usage Notes” on page 146
for more information.
DiskOutReqAvg
Average number of outstanding disk requests.
For AMP-level displays, this value is computed from ResUsageSvdsk table data,
assuming n is the number of storage devices used by this vproc:
(ReadRespTot 1 + WriteRespTot 1 + ... + ReadRespTot n + WriteRespTot n) /
CentiSecs
Note: This field is not applicable to PE vprocs.
For TVS vproc-level displays, this value is computed from ResUsageSvpr table
data as:
AllocatorMapIOsStarted - AllocatorMapIOsDone
This value is NULL if certain conditions apply, see “Usage Notes” on page 146
for more information.
PctParser
272
Note: This field is obsolete and returns zero or NULL.
Application Programming Reference
Chapter 4: System PMPC APIs
MonitorVirtualResource
Column Name
Description
PctDispatcher
% of CPU resources spent in PE Dispatcher processing.
This value depends on the number of CPUs in the node but does not exceed
100%. This value is computed from the ResUsageSvpr table data, where x
represents the number of CPUs on a node:
(CPUUExecPart13 + CPUUServPart13) / (x * SampleSec)
Note: The PercntParser CPU time is included in the PercntDispatcher value.
This value is NULL if certain conditions apply, see “Usage Notes” on page 146
for more information.
Note: This field is not applicable to AMP and TVS vprocs.
HstBlkRds
Number of message blocks (one or more messages sent in one physical group)
received from all clients.
This value corresponds to the column totals in the ResUsageShst table
supplying HostBlockReads for this vproc.
This value is NULL if certain conditions apply, see “Usage Notes” on page 146
for more information.
Note: This field is not applicable to AMP or TVS vprocs.
HstBlkWrts
Number of message blocks (that is, one or more messages sent in one physical
group) sent to all hosts.
This value corresponds to the column totals in the HstBlkWrts column of the
ResUsageShst table.
This value is NULL if certain conditions apply, see “Usage Notes” on page 146
for more information.
Note: This field is not applicable to AMP or TVS vprocs.
NetReads
Number of Reads from the BYNET to the vproc.
The value is computed from the ResUsageSvpr table data as:
NetBrdReads + NetPtPReads
This value is NULL if certain conditions apply, see “Usage Notes” on page 146
for more information.
NetWrites
Number of messages written from the AMP, PE, or vproc to the BYNET
during the collection period.
The value is computed from the ResUsageSvpr table data as:
NetBrdWrites + NetPtPWrites
This value is NULL if certain conditions apply, see “Usage Notes” on page 146
for more information.
Application Programming Reference
273
Chapter 4: System PMPC APIs
MonitorVirtualResource
Column Name
Description
NVMemAllocSegs
Value is computed from ResUsageSvpr table data using the IoRespMax field.
The IoRespMax is the maximum I/O response time in milliseconds. That is,
the number of operations for each AMP vproc on that node.
Note: This field is not applicable to PE and TVS vprocs.
This value is NULL if certain conditions apply, see “Usage Notes” on page 146
for more information.
Note: The NVMemAllocSegs field of the MonitorVirtualResource function
corresponds to the MaxIOResp field of the MONITOR VIRTUAL RESOURCE
request.
Example
SELECT VprocNo, VprocType, Status, PRocId, ClusterNo
TABLE (MonitorVirtualResource()) AS t2;
FROM
*** Query completed. 9 rows found. 5 columns returned.
*** Total elapsed time was 1 second.
VprocNo
----------0
1
2
3
4
5
6
7
10237
10238
1638
274
VprocType
--------AMP
AMP
AMP
AMP
AMP
AMP
AMP
AMP
TVS
TVS
PE
Status
-----U
U
U
U
U
U
U
U
U
U
U
ProcId
----------16384
16384
16384
16384
16384
16384
16384
16384
16384
16384
16384
ClusterNo
----------0
1
2
3
0
1
2
3
0
0
1025
Application Programming Reference
Chapter 4: System PMPC APIs
MonitorVirtualSummary
MonitorVirtualSummary
Purpose
Collects global summary information on system utilization.
Definition
REPLACE FUNCTION SYSLIB.MonitorVirtualSummary()
RETURNS TABLE
(AMPAvgCPU FLOAT,
AMPAvgDisk FLOAT,
AMPAvgDiskIO FLOAT,
HiCPUAMPUse FLOAT,
HiDiskAMP FLOAT,
HiDiskAMPIO FLOAT,
HiCPUAMPNo SMALLINT,
HiDiskAMPNo SMALLINT,
HiDiskAMPIONo SMALLINT,
HiCPUAMPProc SMALLINT,
HiDiskAMPProc SMALLINT,
HiDiskAMPIOProc SMALLINT,
LoCPUAMPUse FLOAT,
LoDiskAMP FLOAT,
LoDiskAMPIO FLOAT,
LoCPUAMPNo SMALLINT,
LoDiskAMPNo SMALLINT,
LoDiskAMPIONo SMALLINT,
LoCPUAMPProc SMALLINT,
LoDiskAMPProc SMALLINT,
LoDiskAMPIOProc SMALLINT,
PEAvgCPU FLOAT,
HiCPUPEUse FLOAT,
LoCPUPEUse FLOAT,
HiCPUPENo SMALLINT,
LoCPUPENo SMALLINT,
HiCPUPEProc SMALLINT,
LoCPUPEProc SMALLINT,
SessionCnt FLOAT,
SesMonitorSys SMALLINT,
SesMonitorLoc SMALLINT,
ResLogging SMALLINT,
ResMonitor SMALLINT,
ReleaseNum CHAR(30),
Version CHAR(32)
)
.
.
.
;
Application Programming Reference
275
Chapter 4: System PMPC APIs
MonitorVirtualSummary
Usage Notes
The MonitorVirtualSummary function provides similar functionality to the PMPC
MONITOR VIRTUAL SUMMARY request. For information about this interface, see
“MONITOR VIRTUAL SUMMARY” on page 159.
Result Rows
Column Name
Description
AMPAvgCPU
Average % CPU usage (CPUUse) of all online AMPs in the
configuration.
Assuming n is the number of online AMPs in the configuration,
AMPAvgCPU is computed from CPUUse data as:
(CPUUse1 + ... + CPUUsen) / n
This value is NULL if certain conditions apply, see “Usage Notes” on
page 159 for more information.
AMPAvgDisk
Average physical disk usage (DiskUse) of all online AMPs in the
configuration.
Assuming n is the number of online AMPs in the configuration,
AMPAvgDisk is computed from DiskUse data as:
(DiskUse1 + ... + DiskUsen) / n
This value is NULL if certain conditions apply, see “Usage Notes” on
page 159 for more information.
AMPAvgDiskIO
Average physical disk DiskReads and DiskWrites of all online AMPs
in the configuration.
Assuming n is the number of online AMPs in the configuration,
AMPAvgDiskIO is computed from DiskReads and DiskWrites data as:
(DiskReads1 + DiskWrites1 + ... + DiskReads1 + DiskWritesn) / n
This value is NULL if certain conditions apply, see “Usage Notes” on
page 159 for more information.
HiCPUAMPUse
Highest CPUUse percentage currently associated with any online
AMP.
This value is NULL if certain conditions apply, see “Usage Notes” on
page 159 for more information.
HiDiskAMP
Highest DiskUse percentage currently associated with any online
AMP.
This value is NULL if certain conditions apply, see “Usage Notes” on
page 159 for more information.
HiDiskAMPIO
Highest DiskReads and DiskWrites value currently associated with
any online AMP.
This value is NULL if certain conditions apply, see “Usage Notes” on
page 159 for more information.
276
Application Programming Reference
Chapter 4: System PMPC APIs
MonitorVirtualSummary
Column Name
Description
HiCPUAMPNo
Vproc number (VprocNo) of an AMP with CPUUse equal to the
value reported as HiCPUAMPUse.
This value is NULL if certain conditions apply, see “Usage Notes” on
page 159 for more information.
HiDiskAMPNo
Number of an AMP with DiskUse equal to the value reported as
HiDiskAMP.
This value is NULL if certain conditions apply, see “Usage Notes” on
page 159 for more information.
HiDiskAMPIONo
Number of an AMP with the highest DiskReads and DiskWrites equal
to the value reported as HiDiskAMPIO.
This value is NULL if certain conditions apply, see “Usage Notes” on
page 159 for more information.
HiCPUAMPProc
ID of the node currently responsible for managing the AMP reported
as HiCPUAMPNo.
This value is NULL if certain conditions apply, see “Usage Notes” on
page 159 for more information.
HiDiskAMPProc
ID of the node currently responsible for managing the AMP reported
in HiDiskAMPNo.
This value is NULL when HiDiskAMPNo is NULL.
HiDiskAMPIOProc
ID of the node currently responsible for managing the AMP reported
in HiDiskAMPIONo.
This value is NULL when HiDiskAMPIONo is NULL.
LoCPUAMPUse
Lowest CPUUse percentage currently associated with any online
AMP.
This value is NULL if certain conditions apply, see “Usage Notes” on
page 159 for more information.
LoDiskAMP
Lowest DiskUse percentage currently associated with any online
AMP.
This value is NULL if certain conditions apply, see “Usage Notes” on
page 159 for more information.
LoDiskAMPIO
Lowest DiskReads and DiskWrites number currently associated with
any online AMP.
This value is NULL if certain conditions apply, see “Usage Notes” on
page 159 for more information.
LoCPUAMPNo
Vproc number (VprocNo) of an AMP with CPUUse equal to the
value reported as LoCPUAMPUse.
This value is NULL if certain conditions apply, see “Usage Notes” on
page 159 for more information.
Application Programming Reference
277
Chapter 4: System PMPC APIs
MonitorVirtualSummary
Column Name
Description
LoDiskAMPNo
Number of an AMP with DiskUse equal to the value reported as
LoDiskAMP.
This value is NULL if certain conditions apply, see “Usage Notes” on
page 159 for more information.
LoDiskAMPIONo
ID of an AMP with lowest DiskReads and DiskWrites equal to the
value reported as LoDiskAMPIO.
This value is NULL if certain conditions apply, see “Usage Notes” on
page 159 for more information.
LoCPUAMPProc
ID of the node currently responsible for managing the AMP reported
as LoCPUAMPNo.
This value is NULL if certain conditions apply, see “Usage Notes” on
page 159 for more information.
LoDiskAMPProc
ID of the node currently responsible for managing the AMP reported
as LoDiskAMPNo.
This value is NULL when LoDiskAMPNo is NULL.
LoDiskAMPIOProc
ID of the node currently responsible for managing the AMP reported
as LoDiskAMPIONo.
This value is NULL when LoDiskAMPIONo is NULL.
PEAvgCPU
Average CPUUse for all online PEs in the configuration.
This value is NULL if certain conditions apply, see “Usage Notes” on
page 159 for more information.
HiCPUPEUse
Highest CPUUse percentage currently associated with any online PE.
This value is NULL if certain conditions apply, see “Usage Notes” on
page 159 for more information.
LoCPUPEUse
Lowest CPUUse percentage currently associated with any online PE.
This value is NULL when LoCPUPEUse is NULL.
HiCPUPENo
Vproc number (VProcNo) of a PE with CPUUse equal to the value
reported as HiCPUPEUse.
This value is NULL if certain conditions apply, see “Usage Notes” on
page 159 for more information.
LoCPUPENo
Vproc number (VProcNo) of a PE with CPUUse equal to the value
reported as LoCPUPEUse.
This value is NULL if certain conditions apply, see “Usage Notes” on
page 159 for more information.
HiCPUPEProc
ID of the node currently responsible for managing the PE reported in
HiCPUPENo.
This value is NULL when HiCPUPENo is NULL.
278
Application Programming Reference
Chapter 4: System PMPC APIs
MonitorVirtualSummary
Column Name
Description
LoCPUPEProc
ID of the node currently responsible for managing the PE reported as
LoCPUPENo.
This value is NULL if certain conditions apply, see “Usage Notes” on
page 159 for more information.
SessionCnt
Total number of sessions currently logged onto the system. This value
is usually equal to the sum of the SessLogCount values for all PEs.
This value is NULL if certain conditions apply, see “Usage Notes” on
page 159 for more information.
SesMonitorSys
Sets the maximum acceptable age of collected session-level data in
memory to the PM/API application or end user.
The global rate is the default collection rate for all MONITOR
sessions. If the value is set to zero, the collection capability is disabled.
SesMonitorLoc
Sets the maximum acceptable age of collected session-level data in
memory for an individual Monitor partition session that submits a
MONITOR SESSION request.
This rate is initiated within a MONITOR session and may update
session-level data within the system. If the value is zero, this allows
SesMonitorSys to override the current local rate for that session.
ResLogging
Interval in seconds at which resource usage data is written to one or
more active resource usage database tables.
ResMonitor
Interval in seconds at which all resource usage data is collected in
memory for reporting via the PM/API.
ReleaseNum
Release number of the currently running Teradata Database software
(for example, 14.00.00.00).
This value is supplied by Teradata Database.
Version
Version number of the currently running Teradata Database software
(for example, 14.00.00.00).
This value is supplied by Teradata Database.
Example
SELECT * FROM TABLE (MonitorVirtualSummary()) AS t1;
*** Query completed. One row found. 35 columns returned.
*** Total elapsed time was 1 second.
AMPAvgCPU
AMPAvgDisk
AMPAvgDiskIO
HiCPUAMPUse
HiDiskAMP
HiDiskAMPIO
HiCPUAMPNo
HiDiskAMPNo
HiDiskAMPIONo
HiCPUAMPProc
Application Programming Reference
6.14583333333333E-003
4.25000000000000E-002
8.41250000000000E 001
1.00000000000000E-002
6.91666666666667E-002
1.12000000000000E 002
3
0
0
33
279
Chapter 4: System PMPC APIs
MonitorVirtualSummary
HiDiskAMPProc
HiDiskAMPIOProc
LoCPUAMPUse
LoDiskAMP
LoDiskAMPIO
LoCPUAMPNo
LoDiskAMPNo
LoDiskAMPIONo
LoCPUAMPProc
LoDiskAMPProc
LoDiskAMPIOProc
PEAvgCPU
HiCPUPEUse
LoCPUPEUse
HiCPUPENo
LoCPUPENo
HiCPUPEProc
LoCPUPEProc
SessionCnt
SesMonitorSys
SesMonitorLoc
ResLogging
ResMonitor
ReleaseNum
Version
280
33
33
3.75000000000000E-003
1.16666666666667E-002
3.90000000000000E 001
6
5
5
33
33
33
4.79166666666667E-002
4.79166666666667E-002
4.79166666666667E-002
16383
16383
33
33
7.00000000000000E 000
60
0
600
600
14.00.00.00
14.00.00.00
Application Programming Reference
Chapter 4: System PMPC APIs
MonitorWD
MonitorWD
Purpose
Returns the data in the second statement (Statement Type 2) of the MONITOR WD response
through an SQL interface consisting of UDFs.
Definition
REPLACE FUNCTION SYSLIB.MonitorWD()
RETURNS TABLE
(WDId
INTEGER,
PPId
SMALLINT,
PGId
SMALLINT,
AGId
SMALLINT,
RelWgt
SMALLINT,
NumProcs
INTEGER,
VprType
VARCHAR(4) CHARACTER SET LATIN,
QWaitTime
FLOAT,
QWaitTimeMax
FLOAT,
CpuUserPct
FLOAT,
WorkMsgMaxDelay
FLOAT,
WorkTypeInuseMax
INTEGER,
WorkTimeInuseAvg
FLOAT,
IODelay
FLOAT,
IODelayTime
FLOAT,
PhysicalRead
FLOAT,
PhysicalReadKB
FLOAT,
PhysicalWrite
FLOAT,
PhysicalWriteKB
FLOAT,
LogicalRead
FLOAT,
LogicalReadKB
FLOAT,
LogicalWrite
FLOAT,
LogicalWriteKB
FLOAT,
ExtraField1
FLOAT,
ExtraField2
FLOAT,
ExtraField3
FLOAT,
ExtraField4
FLOAT
VPId
SMALLINT,
VPId
SMALLINT,
WaitIO
FLOAT,
WaitOther
FLOAT,
CPURunDelay
FLOAT,
IOCntSubmitted
FLOAT,
IOKBSubmitted
FLOAT,
IOCntCompleted
FLOAT,
IOKBCompleted
FLOAT,
IOCntCriticalSubmitted FLOAT,
IOKBCriticalSubmitted FLOAT,
DecayLevel1IO
FLOAT,
DecayLevel2IO
FLOAT,
DecayLevel1CPU
FLOAT,
DecayLevel2CPU
FLOAT,
Application Programming Reference
281
Chapter 4: System PMPC APIs
MonitorWD
TacticalExceptionIO
TacticalExceptionCPU
FLOAT,
FLOAT
)
.
.
.
;
Usage Notes
The MonitorWD function provides similar functionality to the PMPC MONITOR WD
request. For information about this interface, see “MONITOR WD” on page 168.
For information on the resource usage tables and columns described in the field calculations
below, see Resource Usage Macros and Tables.
Result Rows
Field Name
Description
PPId
• On SLES 10 or earlier systems, this field returns the Performance
Period ID.
• On SLES 11 or later systems, this field is obsolete and returns a
value of zero.
PGId
• On SLES 10 or earlier systems, this field returns the Performance
Group ID.
• On SLES 11 or later systems, this field returns the pWDid value.
VprType
Type of vproc:
• AMP
• PE
• MISC
WDId
WD ID.
Note:
• On SLES 10 or earlier systems, if Teradata ASM Workloads rule is
not enabled, the WDId fields in all rows return zeros.
• On SLES 11 or later systems, Teradata ASM Workloads rule is
always enabled. On SUSE Linux Enterprise Server 11 or later
systems, Teradata ASM Workloads rule is always enabled. For
information on Teradata ASM rules, see Teradata Viewpoint User
Guide.
AGId
282
• On SLES 10 or earlier systems, this field returns the Allocation
Group ID.
• On SLES 11 or later systems, this field is obsolete and returns a
value of zero.
Application Programming Reference
Chapter 4: System PMPC APIs
MonitorWD
Field Name
Description
RelWgt
• On SLES 10 or earlier systems, this field returns the Active Relative
Weight. That is, the dynamically assigned relative weight that
considers, in its calculation, the activity of all other Allocation
Groups present on the system. The RelWgt field constantly changes,
unlike the relative weight assignment the Database Administrator
assigns in the Teradata Viewpoint Workload Designer portlet.
RelWgt is the average relative weight of active online nodes (that is,
divide the sum of the non-zero RelWgt by the count of online nodes
with the non-zero RelWgt).
• On SLES 11 or later systems, this field is obsolete and returns a
value of zero.
NumProcs
Average number of tasks of online nodes.
The field is the result of:
NumProcs = SUM of (NumTasks-i) / N
where:
• NumTasks-i is the number of tasks:
• On SLES 10 or earlier systems, assigned to the PG at the end of
the reporting period.
• On SLES 11 or later systems, assigned to the WD at the end of
the reporting period.
• i varies from 1 to N, where N is the number of online nodes.
Note: The NumProcs field is the NumTasks field in the PM/API
MONITOR WD request.
QWaitTime
Total wait time in milliseconds that work requests waited on an input
queue before being serviced
QWaitTimeMax
Maximum time in milliseconds that work requests waited on an input
queue before being serviced.
The field is the result of:
QWaitTimeMax = MAX (QWaitTimeMax-i)
where:
• QWaitTimeMax-i is QWaitTimeMax in each online node.
• i varies from 1 to N, where N is the number of online nodes.
Application Programming Reference
283
Chapter 4: System PMPC APIs
MonitorWD
Field Name
Description
CPUUserPct
Weighted average of CpuUserPct of each node.
This field is the result of:
CpuUserPct = Sum of (CpuUserPct-i * ScalingFactor-i) / Sum of
(ScalingFactor-i)
where:
• CpuUserPct-i is calculated as:
CPUUServAwt + CPUUServDisp + CPUUServMisc +
CPUUExecAwt + CPUUExecDisp + CPUUExecMisc) * 100 /
(NCPUs*Centisecs*10)
Note: NCPUs is the number of CPUs in the node.
• i varies from 1 to N, where N is the number of online nodes.
• ScalingFactor-i is the node CPU normalization factor in each node.
Note: The CPU times are in milliseconds.
The Parser CPU times are included in the Dispatcher CPU times.
WorkMsgMaxDelay
General indicator only. This field is result of the following calculation:
WorkMsgMaxDelay = MAX (WorkMsgMaxDelay-i)
where:
• WorkMsgMaxDelay-i is calculated in each online node as:
WorkMsgsendDelayMax + WorkMsgReceiveDelayMax
• i varies from 1 to N, where N is the number of online nodes.
Note: WorkMsgMaxDelay does not represent the subtotal of the same
message on the send and receive side.
WorkTypeInuseMax
Total of the AMP Worker Task (AWT) columns:
WorkTypeInuseMax = MAX (WorkTypeInuseMax-i)
where:
• WorkTypeInuseMax-i is the sum of WorkTypeMax00 through
WorkTypeMax15 in each node.
• i varies from 1 to N, where N is the number of online nodes.
WorkTimeInuseAvg
Average number of AWTs used. This field is result of:
WorkTimeInuseAvg = SUM of (WorkTimeInuse-i) / N
where:
• WorkTimeInuse-i is calculated in each online node as:
WorkTimeInuse/(Centisecs * 10 * NCPUs)
Note: NCPUs is the number of CPUs in the node.
• i varies from 1 to N, where N is the number of online nodes.
This value is available in the ResSpsView view as AwtUsedAvg.
IODelay
Number of I/Os that are delayed. This field is result of:
ProcBlksFsgRead + ProcBlksFsgWrite + ProcBlksFsgNIOs
284
Application Programming Reference
Chapter 4: System PMPC APIs
MonitorWD
Field Name
Description
IODelayTime
Total time the I/O is delayed for. This field is the result of:
ProcWaitFsgRead + ProcWaitFsgWrite + ProcWaitFsgNIOs
PhysicalRead
Number of physical reads performed for this period. This field is the
result of:
FilePDbAcqReads + FilePDbPreReads + FilePCiAcqReads +
FileSDbAcqReads + FileSCiAcqReads + FileTJtAcqReads +
FileAPtAcqReads + FilePCiPreReads + FileSDbPreReads +
FileSCiPreReads + FileTJtPreReads + FileAPtPreReads
PhysicalReadKB
Number of physical reads in KB performed for this period. This field is
result of:
FilePDbAcqReadKB + FilePDbPreReadKB + FilePCiAcqReadKB +
FileSDbAcqReadKB + FileSCiAcqReadKB + FileTJtAcqReadKB +
FileAPtAcqReadKB + FilePCiPreReadKB + FileSDbPreReadKB +
FileSCiPreReadKB + FileTJtPreReadKB + FileAPtPreReadKB
PhysicalWrite
Number of physical writes performed for this period. This field is result
of:
FilePDbFWrites + FilePCiFWrites + FileSDbFWrites + FileSCiFWrites
+ FileTJtFWrites + FileAPtFWrites
PhysicalWriteKB
Number of physical writers in KB performed for this period. This field
is result of:
FilePDbFWriteKB + FilePCiFWriteKB + FileSDbFWriteKB +
FileSCiFWriteKB + FileTJtFWriteKB + FileAPtFWriteKB
LogicalRead
Number of logical reads performed for this period. This field is result
of:
FilePDbAcqs + FilePDbPres + FilePCiAcqs + FileSDbAcqs +
FileSCiAcqs + FileTJtAcqs + FileAPtAcqs + FilePCiPres + FileSDbPres
+ FileSCiPres + FileTJtPres + FileAPtPres
LogicalReadKB
Number of logical reads in KB performed for this period. This field is
result of:
FilePDbAcqKB + FilePDbPresKB + FilePCiAcqKB + FileSDbAcqKB +
FileSCiAcqKB + FileTJtAcqKB + FileAPtAcqKB + FilePCiPresKB +
FileSDbPresKB + FileSCiPresKB + FileTJtPresKB + FileAPtPresKB
LogicalWrite
Number of logical writes performed for this period. This field is result
of:
FilePDbDyRRels + FilePCiDyRRels + FileSDbDyRRels +
FileSCiDyRRels + FileTJtDyRRels + FileAPtDyRRels
LogicalWriteKB
Number of logical writes in KB performed for this period. This field is
result of:
FilePDbDyRRelKB + FilePCiDyRRelKB + FileSDbDyRRelKB +
FileSCiDyRRelKB + FileTJtDyRRelKB + FileAPtDyRRelKB
ExtraField1
Note: This field is not currently used.
ExtraField2
Note: This field is not currently used.
Application Programming Reference
285
Chapter 4: System PMPC APIs
MonitorWD
Field Name
Description
ExtraField3
Note: This field is not currently used.
ExtraField4
Note: This field is not currently used.
VPId
Virtual partition ID.
WaitIO
Number of milliseconds tasks in WD waited for I/O over the reporting
period.
WaitIO is updated when the wait for I/O is completed.
WaitOther
Number of milliseconds tasks in WD waited for reasons other than I/O
over the reporting period (for example, a task waiting for a message).
WaitOther is updated when wait is completed.
CPURunDelay
Number of milliseconds tasks in the WD sat in the CPU runqueue
waiting to run over the reporting period.
This data can be used in determining demand for the virtual partition
and WD Share workload management method (see “Glossary” for a
description of this method). If the CPU and I/O percentages for a
virtual partition or WD are below their relative share values and the
CPURunDelay values are low, there was insufficient demand to meet
the share percentage. If the CPURunDelay values are high, higher tier
SQL requests were allocated more resources so that there were
insufficient resources remaining to allocate to SQL requests in this WD
to meet its relative share.
Note: A virtual partition divides a system so that a percentage of
resources are allocated to a collection of workloads. A virtual partition
can consist of WDs from all management methods.
IOSubmitted
Number of I/Os submitted on behalf of this WD.
IOSubmittedKB
KB of I/O submitted on behalf of this WD.
IOCompleted
Number of I/Os completed on behalf of this WD.
IOCompletedKB
KB of I/O completed on behalf of this WD.
IOCriticalSubmitted
Number of I/Os submitted with critical status. These
I/Os execute at top priority instead of being based on the I/O priority
of the SQL request.
IOCriticalSubmittedKB
KB of I/O submitted with critical status. These I/Os execute at top
priority instead of being based on the I/O priority of the SQL request.
DecayLevel1IO
Number of times SQL requests in the WD hit decay level 1 due to
I/O.
Note: DecayLevel1IO is used for Timeshare WDs only (see “Glossary”
for a description of this workload management method).
DecayLevel2IO
Number of times SQL requests in the WD decay level 2 due to I/O.
Note: DecayLevel2IO is used for Timeshare WDs only (see “Glossary”
for a description of this workload management method).
286
Application Programming Reference
Chapter 4: System PMPC APIs
MonitorWD
Field Name
Description
DecayLevel1CPU
Number of times SQL requests in the WD hit decay level 1 due to CPU.
Note: DecayLevel1CPU is used for Timeshare WDs only (see
“Glossary” for a description of this workload management method).
DecayLevel2CPU
Number of times SQL requests in the WD hit decay level 2 due to CPU.
Note: DecayLevel2CPU is used for Timeshare WDs only (see
“Glossary” for a description of this workload management method).
TacticalExceptionIO
Number of times SQL requests in the WD hit a tactical per-node
exception due to I/O.
An exception, used only for Tactical WDs, is created for each Tactical
WD (see “Glossary” for a description of this workload management
method).
TacticalExceptionCPU
Number of times SQL requests in the WD hit a tactical per-node
exception due to CPU.
Note: TacticalExceptionCPU is used for Tactical WDs only. For a
description of this workload management method, see “Glossary”.
Example
SELECT * FROM TABLE (MonitorWd()) AS t2 where vpid=102 and vprtype='amp';
*** Query completed. One row found. 43 columns returned.
*** Total elapsed time was 1 second.
WDId
PPId
PGId
AGId
RelWgt
NumProcs
VprType
QWaitTime
QWaitTimeMax
CpuUserPct
WorkMsgMaxDelay
WorkTypeInUseMax
WorkTimeInUseAvg
IODelay
IODelayTime
PhysicalRead
PhysicalReadKB
PhysicalWrite
PhysicalWriteKB
LogicalRead
LogicalReadKB
LogicalWrite
LogicalWriteKB
ExtraField1
ExtraField2
ExtraField3
Application Programming Reference
0
0
254
0
0
454
AMP
0.00000000000000E
0.00000000000000E
0.00000000000000E
0.00000000000000E
0
0.00000000000000E
1.60000000000000E
1.19968000000000E
0.00000000000000E
0.00000000000000E
1.60000000000000E
6.56000000000000E
8.00000000000000E
2.56000000000000E
8.00000000000000E
2.56000000000000E
0.00000000000000E
0.00000000000000E
0.00000000000000E
000
000
000
000
000
001
005
000
000
001
002
000
002
000
002
000
000
000
287
Chapter 4: System PMPC APIs
MonitorWD
ExtraField4
VPId
WaitIO
WaitOther
CPURunDelay
IOSubmitted
IOSubmittedKB
IOCompleted
IOCompletedKB
IOCriticalSubmitted
IOCriticalSubmittedKB
DecayLevel1IO
DecayLevel2IO
DecayLevel1CPU
DecayLevel2CPU
TacticalExceptionIO
TacticalExceptionCPU
288
0.00000000000000E
102
5.80000000000000E
7.78500000000000E
2.98000000000000E
1.60000000000000E
1.48000000000000E
1.60000000000000E
1.48000000000000E
0.00000000000000E
0.00000000000000E
0.00000000000000E
0.00000000000000E
0.00000000000000E
0.00000000000000E
0.00000000000000E
0.00000000000000E
000
001
005
002
001
002
001
002
000
000
000
000
000
000
000
000
Application Programming Reference
Chapter 4: System PMPC APIs
MonitorWDRate
MonitorWDRate
Purpose
Returns the collection rate, number of nodes with at least one online AMP, and number of
nodes with at least one online PE.
Definition
REPLACE FUNCTION SYSLIB.MonitorWDRate()
RETURNS TABLE
(SampleRate SMALLINT,
AMPNodes SMALLINT,
PENodes SMALLINT
)
.
.
.
;
Result Rows
Column Name
Description
SampleRate
Number of seconds of the collection period.
AMPNodes
Number of nodes with at least one online AMP.
PENodes
Number of nodes with at least one online PE.
Example
SELECT * FROM TABLE (MonitorWDRate()) AS t2;
*** Query completed. One row found. 3 columns returned.
*** Total elapsed time was 1 second.
SampleRate
Application Programming Reference
600
AMPNodes
1
PENodes
1
289
Chapter 4: System PMPC APIs
SetResourceRate
SetResourceRate
Purpose
Sets either the ResMonitor or ResLogging rate.
Definition
REPLACE FUNCTION SYSLIB.SetResourceRate
(SampleRate INTEGER,
LogChange
VARCHAR(1),
VProcChange VARCHAR(1)
)
RETURNS INTEGER
.
.
.
;
Input Parameters
Parameter
Description
SampleRate
Value of the collection rate. This field is used either to collect resource data
or to log resource data to the resource usage tables.
You can specify one of the following:
• The ResMonitor rate value if you want to change the resource
monitoring rate.
• The ResLogging rate value if you want to change the resource logging
rate.
Note: The value should be an integral divisor of 3600.
• Zero to turn off the resource collection or logging.
LogChange
Indicator of whether this rate applies to the ResLogging or ResMonitor rate:
• Y or y = ResLogging rate
• N, n, NULL, or blank = ResMonitor rate
VprocChange
Note: This field is obsolete.
Usage Notes
The SetResourceRate function provides similar functionality to the PMPC SET RESOURCE
RATE request. For information about this interface and the ResMonitor and ResLogging rates,
see “SET RESOURCE RATE” on page 179.
290
Application Programming Reference
Chapter 4: System PMPC APIs
SetResourceRate
Return Value
This function returns the previous collection rate value in seconds.
Example
This example uses SetResourceRate to set the ResMonitor rate.
SELECT SetResourceRate(60, 'N', 'N');
*** Query completed. One row found. One column returned.
*** Total elapsed time was 5 seconds.
SetResourceRate(60,'N','N')
--------------------------600
Application Programming Reference
291
Chapter 4: System PMPC APIs
SetSessionAccount
SetSessionAccount
Purpose
Changes the account string for the session or for the request.
Definition
REPLACE FUNCTION SYSLIB.SetSessionAccount
(HostIdIn
SMALLINT,
SessionNoIn INTEGER,
NewAcctString VARCHAR(128) CHARACTER SET LATIN,
EntireSession VARCHAR(1) CHARACTER SET LATIN
)
RETURNS VARCHAR(128)
.
.
.
;
Input Parameters
Parameter
Description
HostIdIn
Logical ID of a host (or client) with sessions logged on.
SessionNoIn
Number of the specified session.
NewAcctString
Account string for the session or request.
EntireSession
Indicator of how the new account or priority affects requests for a specified
session.
If you specify Y or y, then the change applies to all current and future requests
for a specified session. If no requests or steps are executing, the new account or
priority takes effect at the next request, and the DBC.SessionTbl table reflects
the new account or priority for the current session.
If you specify NULL, blank, N, or n, then the change applies only to the current
request for the specified session. If no request is executing, the next request for
the specified session has the old account/priority.
Usage Notes
The SetSessionAccount function provides similar functionality to the PMPC SET SESSION
ACCOUNT request. For information about this interface, see “SET SESSION ACCOUNT” on
page 183.
Return Value
This function returns the old account string.
292
Application Programming Reference
Chapter 4: System PMPC APIs
SetSessionAccount
Example 1
BTEQ -- Enter your DBC/SQL request or BTEQ command:
SELECT SetSessionAccount(Hostid, sessionno, 'Accountx','Y')
FROM TABLE (MonitorSession(1,'twmuser3',0)) AS t1;
SELECT SetSessionAccount(Hostid, sessionno, 'Accountx','Y')
FROM TABLE (MonitorSession(1,'twmuser3',0)) AS t1;
*** Query completed. One row found. One column returned.
*** Total elapsed time was 1 second.
SetSessionAccount(HostId,SessionNo,'Accountx','Y')
-------------------------------------------------ACCOUNT3
Example 2
BTEQ -- Enter your DBC/SQL request or BTEQ command:
SELECT SetSessionAccount(1, 4461, 'Account3','y');
SELECT SetSessionAccount(1, 4461, 'Account3','y');
*** Query completed. One row found. One column returned.
*** Total elapsed time was 1 second.
SetSessionAccount(1,4461,'Account3','y')
---------------------------------------ACCOUNTX
Application Programming Reference
293
Chapter 4: System PMPC APIs
SetSessionRate
SetSessionRate
Purpose
Sets the global rates for updating session-level statistics in memory.
Definition
REPLACE FUNCTION SYSLIB.SetSessionRate
(SampleRate INTEGER
)
RETURNS INTEGER
.
.
.
;
Input Parameter
Parameter
Description
SampleRate
Sets the global rate. The value ranges from 0 to 3600 seconds.
Note: The collection rate applies to global queries.
Usage Notes
There is no option equivalent to the PMPC SET SESSION RATE request
Local_Change = Y option because when using the SetSessionRate function, there is no local
MONITOR PARTITION in which to apply the rate to.
You can set the SetSessionRate function to a global (SesMonitorSys) rate. That is, a collection
rate at which session-level statistics are collected in memory. This rate is returned in the
SesMonitorSys data value by the MonitorVirtualSummary function.
The SetSessionRate function provides similar functionality to the PMPC SET SESSION RATE
request. For information about this interface, see “SET SESSION RATE” on page 187.
Return Value
This function returns the previous collection rate value in seconds.
294
Application Programming Reference
Chapter 4: System PMPC APIs
SetSessionRate
Example
SELECT SetSessionRate(600);
*** Query completed. One row found. One column returned.
*** Total elapsed time was 1 second.
SetSessionRate(600)
----------------------60
Application Programming Reference
295
Chapter 4: System PMPC APIs
SetSessionRate
296
Application Programming Reference
CHAPTER 5
Teradata Dynamic Workload
Management APIs
This chapter discusses how to manage Teradata ASM rules through two types of interfaces:
•
“PM/APIs (CLIv2 Requests)”
•
“Open APIs (SQL Interfaces)”
Some of the SQL interfaces, such as TDWMRuleControl and TDWMSetLimits, allow you to
update the TDWM database in addition to managing the workload rules.
Before using the Teradata Dynamic Workload Management APIs, you may want to familiarize
yourself with the following topics:
•
“PM/APIs” on page 16
•
“Open APIs” on page 17
•
“Teradata Dynamic Workload Management API Features” on page 28
•
“Examples Using Open APIs” on page 29
Application Programming Reference
297
Chapter 5: Teradata Dynamic Workload Management APIs
PM/APIs (CLIv2 Requests)
PM/APIs (CLIv2 Requests)
This section describes the Teradata Dynamic Workload Management interfaces that use
CLIv2. These interfaces are referred to as PM/API requests.
Note: The PM/API requests described in this section are shown in uppercase, although mixed
case interfaces are also supported.
298
Application Programming Reference
Chapter 5: Teradata Dynamic Workload Management APIs
EVENT STATUS
EVENT STATUS
Purpose
Returns information about the current status of all event-related constructs, such as events
through states, and information related to the current state.
Input Data
Element
Data Type
Description
IndByte
BYTE
Indicator bits that specify which fields to treat as NULL if you
are using indicator mode.
Each bit in the byte corresponds to one field in the input data.
If data is supplied for that field, then set the bit to zero.
If the data for that field is NULL (that is, there is no data
supplied for that field), then set the bit to 1.
Note: The IndByte field is only required if the PM/API request
is submitted in indicator mode.
mon_ver_id
Request Type
SMALLINT,
NOT NULL
MONITOR software version ID. This can be version 6 or later.
SMALLINT,
NOT NULL
1 = ALL. This option returns the status of all events,
expressions, SysCons, and OpEnvs defined in the Teradata
Viewpoint Workload Designer portlet.
For a general explanation of monitor version choices, see
“MONITOR VERSION” on page 136.
2 = CURRENT. This option includes the status of those events
and expressions that are related to the currently enforced health
condition (SysCon) and planned environment (OpEnv).
ID Mapping
SMALLINT
Mapping information returned in the output, such as the
names and IDs defined within the current rule set.
If a value of 1 is returned, mapping record types are included.
Otherwise, no mapping information is returned.
Monitor Privileges
To use this request, you must have the ABORTSESSION and MONSESSION privileges as part
of your default role or both privileges must be granted directly to you.
For more information on roles and privileges, see Database Administration and Security
Administration.
Application Programming Reference
299
Chapter 5: Teradata Dynamic Workload Management APIs
EVENT STATUS
Parcels
The following table lists information about the parcels.
Parcel
Sequence
Flavor
Field Length
Comments and Key Parcel Body Fields
Success
8
18 to 273
StatementNo =1
ActivityCount = Not applicable
ActivityType = 170
(PCLEVENTSTATUSSTMT)
DataInfo
71
6 to 64100
Optional: this parcel is present if
request was IndicData parcel.
Record
10
• 5 to 64100
(record mode)
• 6 to
64100(indicat
or mode)
Depending on the request (Data or
IndicData) data is returned in record
or indicator mode. This is the only
record returned.
This record contains an indicator for
each category indicating its status after
processing this request (0=active,
1=inactive)
EndStatement
11
6
StatementNo = 2-byte integer
EndRequest
12
4
None
Response
The EVENT STATUS request returns the status of all items that make up either the CURRENT
or ALL states defined in the current rule set.
The output is divided into three statement types:
•
The first statement type provides configuration overview information.
•
The second statement type provides a series of records that represent the status of events,
expressions and states in the system. Only events that are referenced in Expressions that
have an action are included in this statement type. To optimize the interface, this
information is provided using the internal ID of the various events, expressions and states.
•
The third statement type, which is optional, provides the mapping of internal IDs to
names.
Statement Type: 1
The first statement type returns information about the current configuration.
300
Field Name
Data Type
Description
Config ID
INTEGER,
NOT NULL
Configuration ID of the current rule set.
Application Programming Reference
Chapter 5: Teradata Dynamic Workload Management APIs
EVENT STATUS
Field Name
Data Type
Description
Config Name
VARCHAR (30)
Name of the current rule set, blank filled.
Date
DATE
Date when this configuration was first activated.
Time
FLOAT
Time when this configuration was first activated.
Use this first statement to determine if a new configuration has been placed into effect. When
a new configuration is placed into effect, the mapping record type should be requested to
provide the mapping of object IDs to object names.
Statement Type: 2
The second statement type returns a series of records that provide the status of events,
expressions, SysCons and OpEnvs in the system. The information returned shows the
relationship between an Event, the Expression that references that Event, and the SysCon or
OpEnv that is affected by that Expression.
There is one record returned for every Event that is referenced in the associated Expression.
When CURRENT is requested only a single Expression associated with the CURRENT
SysCon and OpEnv that caused that SysCon or OpEnv to be defined as enforced is returned.
When ALL is requested, ALL expressions associated with each SysCon or OpEnv are returned.
In addition, the ALL interface returns those expressions which do not have an action related to
a SysCon or OpEnv. These are referred to as Notify Only Expressions.
The expression and owning SysCon or OpEnv ID fields are repeated until all events have been
included. If events are repeated within multiple expressions, then those events will be reported
within each of those expressions. For the case of the ALWAYS OpEnv and the NORMAL
SysCon, there is no expression associated. Statements for these two items will have a value of
zero for the Event and Expression ID fields.
Field Name
Data Type
Description
EventId
INTEGER,
NOT NULL
Internal ID of the Event. A value of zero indicates
there is no event associated with this record entry.
There are no expressions associated with the
Normal SysCon, Always OpEnv, and a State.
Events are reported in the order they appear
within the associated expression. Only events
included in the associated expression are included.
EventStatus
SMALLINT
Status of the event:
• 0 = Inactive
• 1 = Active
EventActiveDate
Application Programming Reference
DATE
Date when EventStatus was last changed. This is
the date when EventStatus was set to Inactive or
Active.
301
Chapter 5: Teradata Dynamic Workload Management APIs
EVENT STATUS
Field Name
Data Type
Description
Event Active Time
FLOAT
Time when EventStatus was last changed. This is
the time when EventStatus was set to Inactive or
Active.
ExpressionId
INTEGER,
NOT NULL
Internal ID of the Expression.
A value of zero indicates there is no expression
associated with this record entry. There are no
expressions associated with the Normal SysCon,
Always OpEnv, and a State.
For the CURRENT state request, the first TRUE
expression associated with the associated State is
included. When there are multiple true
expressions for a state only the first one processed
is reported. The order of processing is consistent
within a rule set and, therefore, the same True
expression is reported on every request.
Expression Status
SMALLINT
Current status of the Expression:
• 0 = Inactive
• 1 = Active
Expression Active Date
DATE
Date when Expression Status was last changed.
This is the date when Expression Status was set
Active or Inactive.
Expression Active Time
FLOAT
Time Expression Status was last changed. This is
the time when Expression Status was set Active or
Inactive.
Record Type
SMALLINT
Type of information contained in this record:
• 0 = SysCon
• 1 = OpEnv
• 2 = Notify Only Expression. This option
indicates the remaining fields are not applicable
as only the Event or Expression relationship is
reported in this statement.
• 3 = State. This option indicates the current
active State. This is the result of the current
SysCon and OpEnv. For this Record Type, the
Event and Expression fields above are not valid.
For both the CURRENT and ALL requests, the
order in which State information is returned is as
follows:
• SysCon
• OpEnv
• State (Returns only the Enforced State)
Note: Notify Only Expression is returned only for
the ALL request.
302
Application Programming Reference
Chapter 5: Teradata Dynamic Workload Management APIs
EVENT STATUS
Field Name
Data Type
Description
Id
INTEGER,
NOT NULL
Internal ID of either a SysCon or an OpEnv
depending on the Record Type specified.
The value is zero for Notify Only Expression
record types. Notify Only Expression records
represent Expressions that do not have an action to
activate a Syscon or OpEnv. These Expressions are
not associated with a State.
Status
SMALLINT
Current status of the Syscon or OpEnv:
• 0 = Inactive
• 1 = Active
• 2 = Active and Enforced
Due To Duration
INTEGER
Indicator of whether the corresponding SysCon is
being considered as TRUE or is TRUE:
• 1 = SysCon is Active if the corresponding
SysCon is being considered as TRUE due to
minimum duration (MinDuration) value being
in affect.
• 0 = SysCon is Inactive if the Syscon is TRUE
based on the defined expressions.
Note: This field is valid only when SysCon is the
Record Type specified.
Active Date
DATE
Date when the status of the Record Type was last
changed. This is the date when the SysCon or
OpEnv Status was set Active or Inactive.
Active Time
FLOAT
Time representing when the status of the Record
Type was last changed. This is the time when the
SysCon or OpEnv Status was set Active or Inactive.
The date/time associated with each item (Event, Expression, State) shows when the status that
is represented occurred.
Note: The “State” column in the examples below refers to the “Expression Status” field.
EvtID Status Date/Time
ExpID State
110
1 8:00AM 1/2/06 220
1
120
0 8:15AM 1/2/06 220
1
130
1 8:00AM 1/2/06 320
1
140
1 8:15AM 1/2/06 320
1
Date/Time
8:00AM 1/2/06
8:15AM 1/2/06
8:00AM 1/2/06
8:15AM 1/2/06
RecType
0 300
0 300
1 400
1 400
Id
Status
1
1
1
1
This statement shows two records representing a Single expression (220) that is defined with
two Events (110 and 120). In this example, 110 is true and 120 is false. The original expression
must be referenced by the user to determine why these event values resulted in the Expression
being true. That is, these events are part of a logical expression whose structure is not being
reported here. Another expression (320) is shown that is made up of two events (130 and
140). This expression is responsible for the OpEnv of 400 being in enforced.
EvtID
0
0
Application Programming Reference
Status
0
0
Date/Time
ExpID
8:00AM 1/2/06 0
8:15AM 1/2/06 0
State
0
0
Date/Time
8:00AM 1/2/06
8:15AM 1/2/06
RecType Id
Status
0
100
1
1
200
1
303
Chapter 5: Teradata Dynamic Workload Management APIs
EVENT STATUS
This record has both event and expression IDs of zero. This is the case for both the NORMAL
SysCon and the ALWAYS OpEnv which have no expressions associated with them. The
Date/Time fields are not valid since they are not associated with an Event or Expression but
are only shown as placeholders.
For the CURRENT request, the first Active expression for a SysCon/OpEnv is returned.
Within this Active (true) expression, all events, both Active and Inactive, are reported. The
interface reports the events in a consistent order for a given expression.
For the ALL request, the order of reporting is that all SysCons are returned, followed by all
OpEnvs, then all Expressions not associated with a SysCon or OpEnv State. These are referred
to as Notify Only Expressions. Within a SysCon or OpEnv, all expressions for that State are
reported before reporting the next SysCon or OpEnv. There is no order defined for the
expressions reported under a SysCon/OpEnv but the interface ensures that expressions are
returned in a consistent order.
The following example shows the reporting of three SysCons (300, 310 and 400), three
OpEnvs (500, 530, and 540), and one Notify Only Expression (329) made up of one event
(199). This Notify Only Expression does not have an ID associated with the Record Type (2).
Although not shown in the example, only one SysCon and one OpEnv reported will have the
enforced value returned (a Status of 2). You must independently use the TDWM database
State table to make the association to a State using the returned SysCon and OpEnv.
Note: The “State” column in the example below refers to the “Expression Status” field.
EvtID Status
Date/Time ExpID
110
1 8:00AM 1/2/06 220
120
0 8:15AM 1/2/06 220
130
1 8:00AM 1/2/06 223
140
1 8:15AM 1/2/06 223
150
1 8:00AM 1/2/06 244
160
0 8:15AM 1/2/06 220
170
1 8:00AM 1/2/06 320
180
1 8:15AM 1/2/06 320
199
1 8:15AM 1/2/06 329
State
0
1
1
1
0
1
1
1
1
Date/Time
8:00AM 1/2/06
8:15AM 1/2/06
8:00AM 1/2/06
8:15AM 1/2/06
8:00AM 1/2/06
8:15AM 1/2/06
8:00AM 1/2/06
8:15AM 1/2/06
8:15AM 1/2/06
RecType
0
0
0
0
1
1
1
1
2
Id
300
310
400
400
500
500
540
530
0
Status
0
1
1
1
1
1
1
1
0
Statement Type: 3
The third statement type, if requested, provides a fully enumerated list of all objects that make
up the system state. Some of these objects may not be represented in any expressions in the
state definition. There are no duplications of objects in this statement type and there is no
correlation made between objects.
Since this information does not change frequently this mapping information only needs to be
requested when a new configuration is made active by the administrator.
304
Application Programming Reference
Chapter 5: Teradata Dynamic Workload Management APIs
EVENT STATUS
Field Name
Data Type
Description
Object Type
SMALLINT
Type of object:
•
•
•
•
•
0 = Event
1 = Expression
2 = SysCon
3 = OpEnv
4 = State
Object Id
INTEGER, NOT
NULL
Internal object ID for the object type.
Object Name
VARCHAR (30)
Name of the object.
Object Status
SMALLINT
Current status of the object:
• 0 = Inactive
• 1 = Active
Precedence/Severity
INTEGER
Indicator of the Precedence or Severity of the SysCon
or OpEnv object types only:
• SysCon = Indicates the Severity of the associated
SysCon.
• OpEnv = Indicates the Precedence of the
associated OpEnv.
Note: This field does not apply if this is an Event.
Date
DATE
Date of the current object status (see Object Status).
Time
FLOAT
Time of the current object status (see Object Status).
Application Programming Reference
305
Chapter 5: Teradata Dynamic Workload Management APIs
EVENT STATUS
Field Name
Data Type
Description
EventKind
INTEGER
Indicator of the specific event:
• 1 = User Defined SysCon. The user-defined
system condition.
• 2 = User Defined OpEnv. The user-defined
operating environment.
• 3 = Time Period. The time range.
• 4= Fatal AMPs. The number of AMPs with the
status of FATAL.
• 5 = Fatal PEs. The number of PEs with the status
of FATAL.
• 6 = Fatal GTWs. The number of Gateways with
the status of FATAL.
• 7 = Nodes Down. The % of nodes down within a
clique.
• 8 = Minimum available AWTs. The number of inuse AMP AWTs.
• 9 = AMPs In Flow Control. The number of AMPs
in flow control.
• 10 = Average System CPU. This value is calculated
by the CPU usage columns in the ResUsageSpma
and ResUsageSps tables. See Resource Usage
Macros and Tables for information.
• 11 = System CPU Skew. This value is calculated
by the CPU usage columns in the ResUsageSpma
and ResUsageSps tables. See Resource Usage
Macros and Tables for information.
• 12 = WD CPU %. This value is calculated by the
CPU usage columns in the ResUsageSpma and
ResUsageSps tables. See Resource Usage Macros
and Tables for information.
• 13 = WD SLG Response Time. The % of request
in this WD that have met the defined Response
Time SLG.
• 14 = WD SLG Throughput. The % of request in
this WD that have met the defined Throughput
SLG.
• 15 = WD Arrivals. The number of new requests
for this WD.
• 16 = WD Active Request. The number of
currently active requests in this WD.
• 17 = WD Delay Queue Depth. The number of
requests on the Delay Queue for this WD.
• 18 = WD Delay Query Time. The max time a
request has been delayed in this WD.
• 19 = WD AWT Wait Time. The max time a
request from this WD was on an AMP mailbox
waiting for an AWT.
306
Application Programming Reference
Chapter 5: Teradata Dynamic Workload Management APIs
EVENT STATUS
The following example shows the relationship between the Event Id (110) in Statement Type 2
and the Object Name (AMPDownEvent) in Statement Type 3.
The data returned looks similar to this:
Object type = 0
Object Id
= 110
Object name = AMPDownEvent
Object status = 0
Precedence/Severity=
Date = 04/04/07
Time = 02:30:06
EventKind = 9
The following is the order of objects returned for Statement Type 3:
1
All the rows for the Events
2
A row for a SysCon and all Expressions that are part of that Syscon
3
A row for the next SysCon and its subordinate Expressions until all SysCons are reported
4
A row for a OpEnv and all Expressions that are part of that OpEnv
5
A row for the next OpEnv and its subordinate Expressions until all OpEnvs are reported
6
All the rows for the States
7
All the rows for the Notify Only Expressions
Application Programming Reference
307
Chapter 5: Teradata Dynamic Workload Management APIs
PERFGROUPS
PERFGROUPS
Purpose
Returns information about the Resource Partitions (RPs) and Performance Groups (PGs)
active in the system GDO file.
Note: On Teradata Database systems running SLES 11 or later systems, this function is
obsolete and returns an error.
Input Data
Element
Data Type
Description
IndByte
BYTE
Indicator bits that specify which fields to treat as NULL if you
are using indicator mode.
Each bit in the byte corresponds to one field in the input data.
If data is supplied for that field, then set the bit to zero.
If the data for that field is NULL (that is, there is no data
supplied for that field), then set the bit to 1.
Note: The IndByte field is only required if the PM/API
request is submitted in indicator mode.
mon_ver_id
SMALLINT,
NOT NULL
MONITOR software version ID. This can be version 6 or
later.
For a general explanation of monitor version choices, see
“MONITOR VERSION” on page 136.
Monitor Privileges
To use this request, you must have the ABORTSESSION and MONSESSION privileges as part
of your default role or both privileges must be granted directly to you.
For more information on roles and privileges, see Database Administration and Security
Administration.
Usage Notes
A Resource Partition is a subset of database request-processing resources. The default
Resource Partition represents 100% of the system resources. Each Resource Partition contains
a number of Performance Groups that have access to the resources available to the Resource
Partition. You can define additional Resource Partitions and populate them with Performance
Groups.
A Performance Group is a collection users that have access to the resources of the Resource
Partition to which they belong. You can assign users to Performance Groups using a MODIFY
308
Application Programming Reference
Chapter 5: Teradata Dynamic Workload Management APIs
PERFGROUPS
USER statement. When users log on they can enter the Performance Group as part of the
account string. If a user is not assigned to a Performance Group or does not enter one as part
of the account string at logon, the system uses the default Performance Group for the session.
There are two types of Resource Partitions and Performance Groups:
•
Those that are set up using the Priority Scheduler function in the schmon utility
Note: On SLES 11 systems, Priority Scheduler is managed by Teradata ASM, and is
configured using the Teradata Viewpoint workload management portlets. For more
information on those portlets, see Teradata Viewpoint User Guide.
•
Those that are part of a Teradata dynamic workload management software WD
Only one of these types can be active at any time.
To learn more about Resource Partitions and Performance Groups, see Utilities and Database
Administration.
The PERFGROUPS request returns the set of Resource Partitions and Performance Groups
that are currently active.
•
When Teradata ASM Workloads rule is not enabled, the returned set of Resource
Partitions or Performance Groups are those defined by the schmon utility.
•
When Teradata ASM Workloads rule is enabled, the returned set of Resource Partitions or
Performance Groups are those defined by the Teradata Viewpoint Workload Designer
portlet.
Parcels
Parcel
Sequence
Parcel
Flavor
Length (Bytes)
Comments/Key Parcel Body Fields
Success
8
18 to 273
StatementNo = 1
ActivityCount = 5
ActivityType = 133
(PCLTWMPERFGROUPSSTMT)
DataInfo
71
6 to 64100
Optional; this parcel is present if request was
IndicData parcel.
Record
10
• 5 to 64100
(record
mode)
• 6 to 64100
(indicator
mode)
Depending on the request (Data or IndicData),
data is returned in record or indicator mode. One
record is returned for each RP slot in the system
GDO. The unused slots are padded with blanks.
The format of this Resource Partition Record
parcel is described below.
EndStatement
11
6
StatementNo = 1
Application Programming Reference
309
Chapter 5: Teradata Dynamic Workload Management APIs
PERFGROUPS
Parcel
Sequence
Parcel
Flavor
Length (Bytes)
Comments/Key Parcel Body Fields
Success
8
18 to 273
StatementNo = 2
ActivityCount = 40
ActivityType = 133
(PCLTWMPERFGROUPSSTMT)
DataInfo
71
6 to 64100
Optional; this parcel is present if request was
IndicData parcel.
Record
10
• 5 to 64100
(record
mode)
• 6 to 64100
(indicator
mode)
Depending on the request (Data or IndicData),
data is returned in record or indicator mode. One
record is returned for each Performance Group
slot in the system GDO. The unused slots are
padded with blanks. The format of this
Performance Group Record parcel is described
below.
EndStatement
11
6
StatementNo = 2
EndRequest
12
4
None
The Resource Partition Record parcel contains the Resource Partition Name field. This field
returns the name of the Resource Partition. The names are padded with blanks to fill the
entire field.
Resource Partition Name is a VARCHAR data type with a maximum variable length of 16
characters.
The following table describes the format of the Performance Group Record parcel.
Field Name
Data Type
Description
Performance
Group Name
VARCHAR (16)
Name of the Performance Groups. The names are
padded with blanks to fill the entire field.
Note: The unused Performance Groups have names
which are all blanks.
Resource Partition
Index
SMALLINT
Index that associates this Performance Group back to
one of the Resource Partitions named in a previous
Resource Partition record.
Sample Input
The following example illustrates how the parcels for a PERFGROUPS request built by look
when sent to the Teradata Database server when the mon_ver_id value is not checked. In this
example, the size of the response buffer is set at the maximum (64,000 bytes), although you
can set it to any size.
310
Application Programming Reference
Chapter 5: Teradata Dynamic Workload Management APIs
PERFGROUPS
Flavor
Length
Body
Num
Name
Bytes
Field
Value
0001
Req
17
Request
PERFGROUPS
0004
Resp
6
BufferSize
64000
Sample Output
The following examples show typical data sets returned in character text format for the
PERGROUPS request.
•
Example 1 shows a representative set of user-defined (using schmon) Priority Scheduler
settings that are used by the system when Teradata ASM Workloads rule is disabled.
•
Example 2 shows a representative set of Priority Scheduler settings created in the Teradata
Viewpoint Workload Designer portlet that are used by the system when Teradata ASM
Workloads rule is enabled.
The PERGROUPS request you submit may return information in a different format.
Note: The original system Performance Groups are saved while the Teradata Viewpoint
Workload Designer portlet settings are used and are reactivated if Teradata ASM Workloads
rule is disabled.
Example 1
Submitting request TDWM PERFGROUPS;
Resource Partition items: 5
Resource
Resource
Resource
Resource
Resource
Partition
Partition
Partition
Partition
Partition
Name
Name
Name
Name
Name
: Default
: RP1
: standard
:
:
Performance Group items: 40
RP#:
RP#:
RP#:
RP#:
RP#:
RP#:
RP#:
RP#:
RP#:
RP#:
PG#:
0,
0,
0,
0,
1,
1,
1,
1,
2,
2,
0,
PG-Name:
PG-Name:
PG-Name:
PG-Name:
PG-Name:
PG-Name:
PG-Name:
PG-Name:
PG-Name:
PG-Name:
PG-Name:
L
M
H
R
M1
H1
L1
R1
PGWL5
PGWL10
.
.
.
Application Programming Reference
311
Chapter 5: Teradata Dynamic Workload Management APIs
PERFGROUPS
Example 2
Submitting request TDWM PERFGROUPS;
Resource Partition items: 5
Resource
Resource
Resource
Resource
Resource
Partition
Partition
Partition
Partition
Partition
Name
Name
Name
Name
Name
: DEFAULT
: TACTICAL
: STANDARD
:
:
Performance Group items: 40
RP#:
RP#:
RP#:
RP#:
RP#:
RP#:
RP#:
RP#:
RP#:
RP#:
RP#:
312
0,
0,
0,
0,
2,
2,
2,
2,
2,
0,
0.
PG-Name:
PG-Name:
PG-Name:
PG-Name:
PG-Name:
PG-Name:
PG-Name:
PG-Name:
PG-Name:
PG-Name:
PG-Name:
.
.
.
L
M
H
R
PGWL3
PGWL5
PGWL4
PGWL2
PGWL1
UNUSED9
Application Programming Reference
Chapter 5: Teradata Dynamic Workload Management APIs
TDWM DELAY REQUEST CHANGE
TDWM DELAY REQUEST CHANGE
Purpose
Releases or aborts a specific request or session on the Teradata dynamic workload
management software delay queue.
Input Data
Element
Data Type
Description
IndByte
BYTE
Indicator bits that specify which fields to treat as
NULL if you are using indicator mode.
Each bit in the byte corresponds to one field in the
input data.
If data is supplied for that field, then set the bit to
zero.
If the data for that field is NULL (that is, there is no
data supplied for that field), then set the bit to 1.
Note: The IndByte field is only required if the PM/
API request is submitted in indicator mode.
mon_ver_id
SMALLINT,
NOT NULL
MONITOR software version ID. This can be version
6 or later.
For a general explanation of monitor version choices,
see “MONITOR VERSION” on page 136.
Request Flag
SMALLINT
Indicator of whether the request or session was
aborted or released:
•
•
•
•
0 = Request is aborted
1 = Request is released
2 = Session is aborted
3 = Session is released
Host ID
SMALLINT
ID of the host number upon which the session
containing the delayed request was established.
Reserved
SMALLINT
Mod-4 alignment padding.
Session Number
INTEGER
Number of the session in which the delayed request
was submitted. A unique session number is assigned
by the host (or client) at logon.
Request Number
INTEGER
Active request number.
Note: This field is not used if Request Flag is either 2
or 3.
Application Programming Reference
313
Chapter 5: Teradata Dynamic Workload Management APIs
TDWM DELAY REQUEST CHANGE
Element
Data Type
Description
Workload Class Id
INTEGER
Workload ID associated with the delayed request.
If the request is from the context delay queue (where
there is no workload ID), then the field value is zero.
Note: This field is not used if Request Flag is either 2
or 3.
Monitor Privileges
To use this request, you must have the ABORTSESSION and MONSESSION privileges as part
of your default role or both privileges must be granted directly to you.
For more information on roles and privileges, see Database Administration and Security
Administration.
Usage Notes
The TDWM DELAY REQUEST CHANGE request allows requests or sessions to be processed
out of the normal first-in-first-out (FIFO) order.
Note: Before you submit a TDWM DELAY REQUEST CHANGE request you need to run a
TDWM STATISTICS or MONITOR SESSION request to obtain information about the
delayed query that requires change. Use the output of the request to identify the Host Id,
Session Number, Request Number, and Workload Class Id parameters required as part of the
TDWM DELAY REQUEST CHANGE input.
If the identified request or session is not found in the Teradata dynamic workload
management software delay queue, an error is returned. This condition is expected since
requests or sessions are normally released from the delay queue whereas the information in
the TDWM STATISICS request could be outdated.
Parcels
Parcel
Sequence
Parcel
Flavor
Length (Bytes)
Comments/Key Parcel Body Fields
Success
8
18 to 273
StatementNo=1
ActivityCount=0
ActivityType= 155
(PCLTWMDELRQSTCHGSTMT)
314
EndStatement
11
6
StatementNo = 2-byte integer=1
EndRequest
12
4
None
Application Programming Reference
Chapter 5: Teradata Dynamic Workload Management APIs
TDWM DELAY REQUEST CHANGE
Sample Input
The following example shows how the parcels for a TDWM DELAY REQUEST CHANGE
request, built by CLIv2, appear when sent to the Teradata Database server.
Note: In this example, the size of the response buffer in the example is set at the maximum
(64,000 bytes), although you can set it to any size.
Flavor
Length
Body
Num
Name
Bytes
Field
Value
0001
Req
16
Request
TDWM DELAY
REQUEST CHANGE
0003
Data
24
MonVerID
7
Request Flag
0
Host Id
1
Request Number
5
Session Number
1000
Workload Class Id
10
BufferSize
64000
0004
Resp
6
Sample Output
The TDWM DELAY REQUEST CHANGE request returns values approximately as shown
below when Teradata ASM Workloads rule is enabled and the following input data is specified:
•
Request Flag = 0
•
Host Id =1
•
Request Number = 5
•
Session Number = 1000
•
Workload Class Id = 10
The TDWM DELAY REQUEST CHANGE request commonly returns values in text character
format. Your application program may return the values in a different format or display.
Success parcel:
StatementNo: 1
ActivityCount: 1
ActivityType: 155 FieldCount: 1
DataInfo parcel:
FieldCount: 1
EndStatement.
EndRequest.
Application Programming Reference
315
Chapter 5: Teradata Dynamic Workload Management APIs
TDWM EXCEPTIONS
TDWM EXCEPTIONS
Purpose
Collects Teradata dynamic workload management software exception data from Teradata
Database.
Input Data
Element
Data Type
Description
IndByte
BYTE
Indicator bits that specify which fields to treat as
NULL if you are using indicator mode.
Each bit in the byte corresponds to one field in the
input data.
If data is supplied for that field, then set the bit to
zero.
If the data for that field is NULL (that is, there is no
data supplied for that field), then set the bit to 1.
Note: The IndByte field is only required if the PM/
API request is submitted in indicator mode.
mon_ver_id
SMALLINT,
NOT NULL
MONITOR software version ID. This must be
version 8 or later.
For a general explanation of monitor version
choices, see “MONITOR VERSION” on page 136.
Monitor Privileges
To use this request, you must have the ABORTSESSION and MONSESSION privileges as part
of your default role or both privileges must be granted directly to you.
For more information on roles and privileges, see Database Administration and Security
Administration.
Usage Notes
This request allows an application to receive the Teradata dynamic workload management
software exception information from the Teradata Database. There is one record per
exception.
316
Application Programming Reference
Chapter 5: Teradata Dynamic Workload Management APIs
TDWM EXCEPTIONS
Parcels
Parcel Sequence
Parcel Flavor
Length (Bytes)
Comments/Key Parcel Body Fields
Success
8
18 to 273
StatementNo = 1
ActivityCount = 1
ActivityType =
PCLTWMEXPSTMT 199
DataInfo
71
6 to 64100
Optional: this parcel is present if
request was IndicData parcel.
Record
10
• 5 to
64100(record
mode)
• 6 to
64100(indicato
r mode)
Depending on the request (Data or
IndicData) data is returned in
record or indicator mode. This is
the only record returned
EndStatement
11
6
StatementNo = 2-byte integer
Success
8
18 to 273
Statement 2
ActivityCount = number of record
parcels returned
ActivityType =
PCLTDWMEXPSTMT 199
DataInfo
71
6 to 64100
Optional: this parcel is present if
request was IndicData parcel.
Record
10
• 5 to 64100
(record mode)
• 8 to 64100
(indicator
mode)
Depending on the request (Data or
IndicData) data is returned in
record or indicator mode. There is
one Exception record returned for
each Exceptions.
EndStatement
11
6
StatementNo = 2-byte integer
End Request
12
4
None
Statement Type: 1
The first statement type is a Record parcel format containing the collection duration data that
is generated once for the whole system. The following table describes this Record format.
Field Name
Data Type
Description
SampleSec
SMALLINT
Duration of the collection period, in seconds. This
value represents the collection rate as entered in
Teradata Viewpoint.
Application Programming Reference
317
Chapter 5: Teradata Dynamic Workload Management APIs
TDWM EXCEPTIONS
Statement Type: 2
The second statement type is a Record parcel format containing exception information for
queries collected (and stored in a buffer) for the last collection period. There is one record for
each exception. The following table describes this Record format.
Field Name
Data Type
Description
VprocID
SMALLINT
Vproc the request with the exception was running
on.
Query ID
BIGINT
Query ID associated with the query that
encountered an exception.
UserName
VARCHAR (32)
User name used in the query with the exception.
SessionID
INTEGER
Logical host ID of the query with the exception
RequestNum
SMALLINT
Request number of the query with the exception
LogicalHostID
SMALLINT
Logical host ID of the query with the exception.
AcctString
VARCHAR (32)
Account string of the query with the exception.
WDID
INTEGER
WD ID the query with the exception was running
in.
OpEnvID
INTEGER
Planned environment ID in force when the query
encountered the exception.
SysConID
INTEGER
Health condition ID in force when the query
encountered the exception.
ClassificationTime
FLOAT
Time the query with the exception was classified.
ClassificationDate
INTEGER
Date the query with the exception was classified.
ExceptionTime
FLOAT
Time the query encountered the exception.
ExceptionDate
INTEGER
Date the query encountered the exception.
ExceptionValue
INTEGER
Type of exception that occurred:
•
•
•
•
•
•
•
•
•
•
•
318
01 = Exception time limit exceeded
02 = CPU time (AMP and PE) limit exceeded
03 = AMP CPU skew limit exceeded
04 =AMP I/O count limit exceeded
05 =AMP I/O skew limit exceeded.
06 =Max row count (for a step) exceeded
07 =Final row count (for the query) exceeded
08 =Blocked time limit exceeded
09 = Disk to CPU ratio exceeded
10 = Spool space limit exceeded
11 = I/O space
Application Programming Reference
Chapter 5: Teradata Dynamic Workload Management APIs
TDWM EXCEPTIONS
Field Name
Data Type
Description
ExceptionAction
VARCHAR (10)
Exception action taken by the exception handler:
• A =Abort
• C =Change WD
Note: NewWDId contains the new WD.
• L =Log.
• E =Execute Program
Note: ExProgram contains the program name.
• T =Alert
Note: ExAlert contains the alert name.
• N = No action
This option cannot be combined with other
actions. It disables exception detection.
• S =Abort if the statement is a SELECT and no
update has been done in the current transaction
• Q = Insert a row to DBC.SystemQTbl
For example, CE stands for change WD and execute
program.
NewWDID
INTEGER
WD the query was moved into if the
ExceptionAction was change WD.
ExceptionCode
INTEGER
Database exception code.
ExceptionSubCode
INTEGER
Code for additional information.
Note: This field is not currently used.
ErrorText
VARCHAR (255)
Error text generated for the exception.
ExtraInfo
VARCHAR (200)
Exception values noted at the time of the exception.
RuleID
INTEGER
Teradata dynamic workload management software
rule ID of the rule with the exception handling
directive.
WarningOnly
VARCHAR (1)
Indicator whether this was a warning only.
RejectionCat
SMALLINT
Teradata dynamic workload management software
category this query was rejected from.
Application Programming Reference
319
Chapter 5: Teradata Dynamic Workload Management APIs
TDWM EXCEPTIONS
Sample Input
The following example shows how the parcels for a TDWM EXCEPTIONS request, built by
CLIv2, appear when sent to the Teradata Database server.
Note: In this example, the size of the response buffer in the example is set at the maximum
(64,000 bytes), although you can set it to any size.
Flavor
Length
Body
Num
Name
Bytes
Field
Value
0001
Req
20
Request
TDWM EXCEPTIONS
0003
Data
6
MonVerID
8
0004
Resp
6
Buffer Size
64000
Sample Output
Submitting request TDWM EXCEPTIONS;
TDWM EXCEPTION successful.
Sample Seconds: 60
TDWM Exceptions - # items: 3
320
User Name Req Cat
QueryID
--------- ---- --LUMBER
2 0
163837185173601208
WDID ExcptDate
ExcptTime
Code
ErrorText
------------ ---------- ---11 2009/09/28 11:05:43.00 3156
CPUTime: 687ms.
LUMBER
2 0
163837185173601276
11 2009/09/28 11:05:57.00
CPUTime: 1501ms.
3156
LUMBER
2 0
163837185173601276
11 2009/09/28
I/O: 1720.
3156
11:05:57.00
NewWD
-----
Application Programming Reference
Chapter 5: Teradata Dynamic Workload Management APIs
TDWM LIST WD
TDWM LIST WD
Purpose
Returns the names of the workloads.
Input Data
Element
Data Type
Description
IndByte
BYTE
Indicator bits that specify which fields to treat as NULL if you
are using indicator mode.
Each bit in the byte corresponds to one field in the input data.
If data is supplied for that field, then set the bit to zero.
If the data for that field is NULL (that is, there is no data
supplied for that field), then set the bit to 1.
Note: The IndByte field is only required if the PM/API request
is submitted in indicator mode.
mon_ver_id
enabled_only
SMALLINT,
NOT NULL
MONITOR software version ID. This can be version 6 or later.
SMALLINT
Workload names returned based on whether they are enabled:
For a general explanation of monitor version choices, see
“MONITOR VERSION” on page 136.
• 0 = Enabled or disabled
• 1 = Enabled only
Monitor Privileges
To use this request, you must have the ABORTSESSION and MONSESSION privileges as part
of your default role or both privileges must be granted directly to you.
For more information on roles and privileges, see Database Administration and Security
Administration.
Usage Notes
The TDWM LIST WD request returns the WD information from the internal cache being
used by the Teradata dynamic workload management software. Teradata ASM Workloads rule
must be enabled through the Teradata Viewpoint Workload Designer portlet to use this
request. WDs are returned in the order defined for evaluation.
Application Programming Reference
321
Chapter 5: Teradata Dynamic Workload Management APIs
TDWM LIST WD
Parcels
Parcel
Sequence
Parcel Flavor
Length (Bytes)
Comments/Key Parcel Body Fields
Success
8
18 to 273
StatementNo = 1
ActivityCount = 1 record for each WD being
used at the time. There can a maximum of 246.
ActivityType = 161 (PCLTWMLISTWDSTMT)
DataInfo
71
6 to 64100
Optional: This parcel is present if request was
IndicData parcel.
Record
10
• 5 to 64100
(record
mode)
• 6 to
64100(indi
cator
mode)
Depending on the request (Data or IndicData),
data is returned in record or indicator mode.
There is one WD Information record returned
for each WD satisfying the request. The format
of this record is described below.
EndStatement
11
6
StatementNo = 1
EndRequest
12
4
None
The following table describes the format of the WD Information Record parcel.
Field Name
Data Type
Description
Configuration ID
SMALLINT
Configuration ID of the current rule set.
Enabled Flag
SMALLINT
Indicator of whether the workload is currently
enabled.
WLC ID
INTEGER
WD ID associated with the specified request.
WLC Name
VARCHAR (30)
Name of the WD.
Note: Characters after the name length are not
initialized.
Sample Input
The following example shows how the parcels for a TDWM LIST WD request, built by CLIv2,
appear when sent to the Teradata Database server.
Note: In this example, the size of the response buffer in the example is set at the maximum
(64,000 bytes), although you can set it to any size.
322
Application Programming Reference
Chapter 5: Teradata Dynamic Workload Management APIs
TDWM LIST WD
Flavor
Length
Body
Num
Name
Bytes
Field
Value
0001
Req
16
Request
TDWM LIST WD
0003
Data
4
MonVerID
7
enabled_only
1
BufferSize
64000
0004
Resp
6
Sample Output
With an enabled_only value of 1, this example shows only the enabled WDs on the current
system in character text format for the LIST WD request when Teradata ASM Workloads rule
is enabled. Your application program may return these values in a different format.
Submitting request TDWM LIST WD;
TDWM LIST WD successful.
Application Programming Reference
Config ID
Enable Flag
WLC ID
Name Len
WLC Name
:
:
:
:
:
1
1
3
11
WD-ConsoleH
Config ID
Enable Flag
WLC ID
Name Len
WLC Name
:
:
:
:
:
1
1
5
11
WD-ConsoleL
Config ID
Enable Flag
WLC ID
Name Len
WLC Name
:
:
:
:
:
1
1
4
11
WD-ConsoleM
Config ID
Enable Flag
WLC ID
Name Len
WLC Name
:
:
:
:
:
1
1
2
11
WD-ConsoleR
Config ID
Enable Flag
WLC ID
Name Len
WLC Name
:
:
:
:
:
1
1
1
10
WD-Default
323
Chapter 5: Teradata Dynamic Workload Management APIs
TDWM STATISTICS
TDWM STATISTICS
Purpose
Returns statistics from the Teradata dynamic workload management software.
Input Data
Element
Data Type
Description
IndByte
BYTE
Indicator bits that specify which fields to treat as NULL if you
are using indicator mode.
Each bit in the byte corresponds to one field in the input data.
If data is supplied for that field, then set the bit to zero.
If the data for that field is NULL (that is, there is no data
supplied for that field), then set the bit to 1.
Note: The IndByte field is only required if the PM/API request
is submitted in indicator mode.
mon_ver_id
Request Flag
SMALLINT,
NOT NULL
MONITOR software version ID. This can be version 6 or later.
SMALLINT
Type of statistics returned:
For a general explanation of monitor version choices, see
“MONITOR VERSION” on page 136.
•
•
•
•
•
0 = Object query counts
1 = Object logon counts
2 = Object delayed queries
3 = Workload query counts
4 = Workload delayed queries
Note: This request includes requests that are delayed due to
WD throttles but no longer returns object delay queue
information.
• 5= (Load and archive) utility counts
• 6 = Delayed utility session information
• 7 = All delay statistics (requests 2, 4 and 6)
• 8 = All statistics (requests 0 through 6)
• 9 = Active request (session and query) information
Note: Request Flag 7, 8, and 9 are only valid for monitor
version software ID 8 or later.
Monitor Privileges
To use this request, you must have the ABORTSESSION and MONSESSION privileges as part
of your default role or both privileges must be granted directly to you.
324
Application Programming Reference
Chapter 5: Teradata Dynamic Workload Management APIs
TDWM STATISTICS
For more information on roles and privileges, see Database Administration and Security
Administration.
Usage Notes
The Workload Query Manager (WQM) enforces Teradata ASM rules on the number of active
sessions, queries, workloads and load/archive utilities for specified conditions.
The TDWM STATISTICS request returns information in the various record formats
depending on the Request Flag supplied as described in the following table.
The Request Flag in the input record determines the format of the data in the response records,
and in some cases the type of information contained within each statement (for example, a
query or session).
Use Teradata Viewpoint to learn more about the WQM process.
The following table specifies which format types are returned.
Note: These formats are defined later in this section.
IF a Request Flag is...
THEN Format1
Records Are
Returned...
0 = object query counts
X
1 = object logon counts
X
2 = object delayed queries
3 = workload query counts
THEN Format2
Records Are
Returned...
X
X
4 = workload delayed queries
X
5 = load/archive utility counts
X
6 = utility delayed sessions
X
7 = all delay information
X
8 = all information
9 = Active request (session and
query) information
THEN Format3
Records Are
Returned...
X
X
X
X
Parcels
The TDWM STATISTICS request is a three statement request, with each statement generating
a response. The following is the Parcel Sequence returned if Request Flag 0 through 7 is
requested. Only one parcel is returned.
Statement 1, Statement 2, or Statement 3 is returned depending on the Request Flag. Since an
object or utility can be affected by multiple rules, multiple rows can be returned for requests 2,
4, 6, 7 and 8.
Application Programming Reference
325
Chapter 5: Teradata Dynamic Workload Management APIs
TDWM STATISTICS
Parcel
Sequence
Parcel
Flavor
Length (Bytes)
Comments/Key Parcel Body Fields
Success
8
18 to 273
StatementNo = 1, 2, or 3
ActivityCount = Not applicable
ActivityType = 132 (PCLTWMSTATSSTMT)
DataInfo
71
6 to 64100
Optional; this parcel is present if request was
IndicData parcel.
Record
10
• 5 to 64100
(record
mode)
• 6 to 64100
(indicator
mode)
Depending on the request (Data or IndicData),
data is returned in record or indicator mode.
This record contains information in
StatementNo-1, StatementNo-2, or
StatementNo-3 data format, depending on the
Request Flag in the input data. There is one
Record parcel for each item being tracked by the
WQM. If there are no qualifying records, no
Record parcel is sent.
EndStatement
11
6
StatementNo = 2-byte integer=1, 2 or 3
EndRequest
12
4
None
The following Parcel Sequence is returned if Request Flag is 8 is requested. All three statement
types are returned.
Parcel
Sequence
Parcel
Flavor
Length (Bytes)
Comments/Key Parcel Body Fields
Success
8
18 to 273
StatementNo = 1
ActivityCount = number of queries with
applicable statistics
ActivityType = 132 = PCLTWMSTATSSTMT
DataInfo
71
6 to 64100
Optional: this parcel is present if request was
IndicData parcel.
Record
10
• 5 to 64100
(record
mode)
• 7 to 64100
(indicator
mode)
Depending on the request (Data or IndicData)
data is returned in record or indicator mode.
This record contains information in
StatementNo-1. There is one record parcel for
each item being tracked by the WQM. If there are
no qualifying records, no record parcel is sent.
EndStatement
11
6
StatementNo = 2-byte integer = 1
Success
8
18 to 273
StatementNo = 2
ActivityCount = number of queries with
applicable statistics
ActivityType = 132 = PCLTWMSTATSSTMT
326
Application Programming Reference
Chapter 5: Teradata Dynamic Workload Management APIs
TDWM STATISTICS
Parcel
Sequence
Parcel
Flavor
Length (Bytes)
Comments/Key Parcel Body Fields
DataInfo
71
6 to 64100
Optional: this parcel is present if request was
IndicData parcel.
Record
10
• 5 to
64100(reco
rd mode)
• 7 to 64100
(indicator
mode)
Depending on the request (Data or IndicData)
data is returned in record or indicator mode.
This record contains information in StatementNo
2. There is one record parcel for each item being
tracked by the WQM. If there are no qualifying
records, no record parcel is sent.
EndStatement
11
6
StatementNo = 2-byte integer = 2
Success
8
18 to 273
StatementNo = 3
ActivityCount = number of queries with
applicable statistics
ActivityType = 132 = PCLTWMSTATSSTMT
DataInfo
71
6 to 64100
Optional: this parcel is present if request was
IndicData parcel.
Record
10
• 5 to 64100
(record
mode)
• 7 to 64100
(indicator
mode)
Depending on the request (Data or IndicData)
data is returned in record or indicator mode.
This record contains information in StatementNo
3. There is one record parcel for each item being
tracked by the WQM. If there are no qualifying
records, no record parcel is sent.
EndStatement
11
6
StatementNo = 2-byte integer = 3
EnRequest
12
4
None
Statement Type: 1
The first statement type is a Record parcel format containing statistical information for one
object or workload item. There is one record for each item that is being tracked by the
Teradata dynamic workload management software. The following table describes this Record
format.
Application Programming Reference
327
Chapter 5: Teradata Dynamic Workload Management APIs
TDWM STATISTICS
Field Name
Data Type
Description
Record Type
SMALLINT
Type of information contained in this record:
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
Rule ID
INTEGER
1 = User
2 = Account String
3 = Performance Group (PG)
4 = Account String
5 = Profile
6 = Client ID
7 = Network Address
8 = Application
9 = Collective Rule
10 = Database
11 = Table
12 = WD
13 = Utility
14 = Macro
15 = Stored Procedure
16 = View
17 = QueryBand
ID of the Object Throttle Rule or Workload for this statistic.
If Request Flag is 0 or 1, then the ID of the Object Throttle
Rule is returned.
If the Request Flag is 3, then the ID of the Workload is
returned.
Object Name
VARCHAR (32)
For Request Flags 0 and 1, this is the name of the object
based on its Record Type. When Record Type is set to 11, 14,
15, or 16 this field is the qualifying database name for the
Table Name field.
For Request flag 3, this field is always empty.
Qualified Name
VARCHAR (32)
For Request Flags 0 and 1, this is the name of the table,
macro, or stored procedure object when Record Type is set to
11, 14, 15, or 16.
For Request Flag 3, this field is always empty.
Active
INTEGER
Number of requests currently active. This is the number of
active queries or sessions depending on the information
requested in the input record.
Limit
INTEGER
Current minimum limit on this item. This is the limit on the
number of queries or sessions depending on the
information requested in the input record.
Delayed
INTEGER
Number of requests currently delayed (queued) for this
item.
Note: This field is not applicable if Request Flag is 1.
328
Application Programming Reference
Chapter 5: Teradata Dynamic Workload Management APIs
TDWM STATISTICS
Field Name
Data Type
Description
Rule Name
VARCHAR (32)
Name of the Object Throttle Rule or Workload for this
statistic.
If Request Flag is 0 or 1, then the name of the Object
Throttle Rule is returned.
If the Request Flag is 3, then the name of the Workload is
returned.
Statistic Type
INTEGER
Indicator on what kind of data is returned:
0 = query data
1 = logon data
2 = WDs
Note: This field is only valid on monitor version software
ID 8 or later.
Example 1
If a Request Flag of zero (object query counts) is requested, the following is an example of the
records that are returned as part of the first statement type.
RecordType
--------1
1
2
2
2
3
3
Rule
ID
-0
0
0
0
0
0
0
Obj
Qual Name
Name
---------Ken
Dina
Sales
Presales
Training
H
H2
Active
Limit
Delayed
----4
2
3
2
3
6
1
----5
4
10
10
3
6
1
------0
0
0
0
10
2
0
This example shows the following important information:
•
Two users running (Record Type 1) also have rules defined on the number of queries that
they are allowed to have running simultaneously (Limit).
•
Three accounts running (Record Type 2) and also have rules defined on the number of
queries that they are allowed to have running simultaneously (Limit).
•
Two Performance Groups (Record Type 3) that have rules defined on the number of
queries that they are allowed to have running simultaneously (Limit)
Since the input requested query information (a Request Flag of zero), the numbers shown
reflect the number of active queries for each user, account, and performance group. If logon
information were requested (a Request Flag of 1) in the input, the records would look the
same. However, the numbers shown would reflect the number of active sessions within the
restricted area.
Items that are restricted, but are not currently active on the system, or are bypassed, will not
be returned.
Note: If there are currently no active elements within the system, that is, if no queries are
currently active within the Performance Groups (for example, H and H2 in the example), then
no parcels with a record type of 3 are present.
Application Programming Reference
329
Chapter 5: Teradata Dynamic Workload Management APIs
TDWM STATISTICS
The above example also shows that the number of allowed queries for the Object Name
Training and the Performance Group H is less than the number of queries submitted;
therefore, the Delayed field displays the requests over and above the defined limits.
Example 2
If Tables are restricted, the following records are returned:
RecordType
---------11
11
Rule
ID
-0
0
Obj
Name
------Employee
Leads
Qual
Name
-------PayrollDB
MaketingDB
Active
Limit
---2
1
----10
1
Delayed
------0
1
Example 3
If WDs (Request Flag 3) are requested, the following records are returned:
RecordType
--------12
12
12
Rule
ID
--03
05
05
Obj
Name
-------TacticalWD
StrategicWD
AdHocWD
Qual
Name
----
Active Limit
Delayed
-----4
2
0
------0
1
0
----100
2
-1
Note: -1 limit means that there is no limit.
Example 4
If Request Flag 8 is requested, the following records are returned:
RecordType Rule
ID
-------0
0
0
0
1
0
1
0
1
0
2
0
2
0
11
0
11
0
12
3
12
5
12
5
Obj
Name
---Ken
Dina
Sales
Presales
Training
H
H2
Employee
Leads
TacticalWD
StrategicWD
AdHocWD
Qual
Name
-------
PayrollDB
MaketingDB
Active
Limit
Delayed
----4
2
3
2
3
6
1
2
1
44
2
0
---5
4
10
10
3
6
1
10
1
100
2
-1
----0
0
0
0
10
2
0
0
1
0
1
0
Rule
Name
-----------
Stat
Type
----
LimitTraining
Statement Type: 2
The second statement type is a Record parcel format containing information about queries or
sessions being delayed by the Teradata dynamic workload management software due to an
object, WD or Utility Throttle limit. If Request Flag 7 is requested, one record for each request
or session that is being delayed is returned with one Rule ID. Multiple rows are returned if the
request has more than one rule causing its delay.
The following table describes this Record format.
330
Field Name
Data Type
Description
User name
VARCHAR (32)
User name provided at logon time. The names are padded
with blanks to fill the entire field.
Application Programming Reference
Chapter 5: Teradata Dynamic Workload Management APIs
TDWM STATISTICS
Field Name
Data Type
Description
HostId
SMALLINT
Host ID of the session number associated with the delayed
request or session.
Session Number
INTEGER
Number associated with the held request or session.
Request
Number
INTEGER
Request number associated with the delayed request or
session.
This field is zero if Request Flag is 6.
Rule Name
VARCHAR (32)
Name of the Object Throttle Rule or Workload Class for this
statistic.
If Request Flag is 2 or 6, then the name of the Object Throttle
Rule is returned.
If Request Flag is 4, then the name of the Workload is
returned.
If Request Flag is 9, then the Rule Name field and all
remaining fields, except for RuleType are empty.
Rule ID
INTEGER
ID of the Object Throttle Rule or Workload Class for this
statistic.
If Request Flag is 2 or 6, then the ID of the Object Throttle
Rule is returned.
If Request Flag is 4, then the ID of the Workload is returned.
This ID must be supplied in the Abort/Release interface
(when used). The ID is zero if the Request Flag is 6.
Total Time Held
INTEGER
Total number of wall-clock seconds that this request or
session has been held by the WQM.
Overridable
Boolean
Indicator of whether the database administrator is allowed to
abort or release the request.
Note: The replication and queue table requests are
controlled internally by the database and cannot be altered
by the administrator.
If Request Flag is 6, this field indicates if the delayed session
can be released. A session cannot be released if it exceeds the
internal AMP worker task limit or an internal utility limit.
A delayed session can always be aborted.
Blocking Count
INTEGER
Number of consecutive times that this session has been
identified as blocking at least one other session.
This field is zero if Request Flag is 6.
IFP ID
SMALLINT
ID of the PE vproc which initiated this request.
WD Time Held
INTEGER
Number of seconds that this request or session has been held
by the WQM due to a WD limitation.
Note: This field is only valid on monitor version software ID
8 or later.
Application Programming Reference
331
Chapter 5: Teradata Dynamic Workload Management APIs
TDWM STATISTICS
Field Name
Data Type
Description
Object Time
Held
INTEGER
Number of seconds that this request or session has been held
by the WQM due to an object limitation.
Note: This field is only valid on monitor version software ID
8 or later.
Utility Time
Held
INTEGER
Number of seconds that this request or session has been held
by the WQM due to a Utility limitation.
Note: This field is only valid on monitor version software ID
8 or later.
Rule Type
INTEGER
Indicator on whether the Rule ID is a WD (0), Object (1), or
Utility Rule (2).
If Request Flag is 9, this field is an indicator on whether the
request is a query (1) or session (2).
Note: The Rule Type field is only valid on monitor version
software ID 8 or later.
Example 1
If a Request Flag of 6 is requested, the following Records are returned as part of the second
statement:
User
Name
--Ken
Dina
Host
ID
-01
01
Sess
---1012
1088
Req
Nbr
--0
0
Rule
Name
----
Rule
ID
-0
0
Total
TimeHeld
----45
110
Over
Block
---True
True
----0
0
This report indicates that 2 sessions are being delayed due to WD and/or Object and/or Utility
limits.
Example 2
If a Request Flag of 7 is requested, the following Records are returned as part of the second
statement:
User
Name
---Ken
Ken
Dina
Host
ID
-01
01
01
Sess
---1013
1013
1089
Req
Nbr
-1
1
0
Rule
Name
----
Rule
ID
-4
5
4
Total
TimeHeld
---15
15
110
Over
Block
---True
True
True
----0
0
0
This report indicates that 2 requests are being delayed, but the first request has two rules that
are causing its delay.
Statement Type: 3
The third statement type is a Record parcel format containing information on the load
utilities that are active in the system. There is one record for every load utility type.
This statement type is only returned when utility statistics have been requested. The following
table describes this record format.
332
Application Programming Reference
Chapter 5: Teradata Dynamic Workload Management APIs
TDWM STATISTICS
Field Name
Data Type
Description
Utility Type
SMALLINT
Type of utility information contained in this
record:
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
0 = MultiLoad + FastLoad
1 = MultiLoad
2 = FastLoad
3 = FastExport
4 = ARC
5 - Standalone Mload
6 - Standalone FastLoad
7 - Standalone FastExport
8 - TPT update Op: MultiLoad
9 - TPT load Op: Fastload
10 - TPT export Op: FastExport
11 - JDBC MultiLoad
12 - JDBC FastLoad
13 - JDBC FastExport
14 - CSP Save Dump (FastLoad)
15 - BAR
Count
SMALLINT
Number of utilities of this utility type that are
active.
Limit
SMALLINT
Current limit on the number of utilities of this
type.
A value of -1 indicates there is no limit defined.
Example
The following is an example of the records that are returned as part of third statement type:
TYPE
---0
1
2
3
4
5
6
7
8
9
10
11
12
13
14
Application Programming Reference
COUNT
----0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
LIMIT
----30
30
30
60
350
30
30
60
30
30
60
30
30
60
30
333
Chapter 5: Teradata Dynamic Workload Management APIs
TDWM STATISTICS
Since a row is returned for each utility type, the Limit value can be either the system default
value for the utility or a Teradata ASM rule Throttle value.
Note: When a Teradata ASM rule Throttle value is active, it overrides the default limit.
334
Application Programming Reference
Chapter 5: Teradata Dynamic Workload Management APIs
TDWM SUMMARY
TDWM SUMMARY
Purpose
Returns the Teradata dynamic workload management software WD summary data fields.
Input Data
Field Name
Data Type
Description
IndByte
BYTE
Indicator bits that specify which fields to treat as NULL if
you are using indicator mode.
Each bit in the byte corresponds to one field in the input
data.
If data is supplied for that field, then set the bit to zero.
If the data for that field is NULL (that is, there is no data
supplied for that field), then set the bit to 1.
Note: The IndByte field is only required if the PM/API
request is submitted in indicator mode.
mon_ver_id
SMALLINT,
NOT NULL
MONITOR software version ID. This can be version 6 or
later.
For a general explanation of monitor version choices, see
“MONITOR VERSION” on page 136.
Monitor Privileges
To use this request, you must have the ABORTSESSION and MONSESSION privileges as part
of your default role or both privileges must be granted directly to you.
For more information on roles and privileges, see Database Administration and Security
Administration.
Usage Notes
There is one record per WD active in the system. The data returned depends upon the data
requested through the Request Flag. The record could contain counts of the number of queries
that were classified into the WD in the collection period and the number of queries that
completed in the collection period along with query statistics.
The TDWM Summary request returns information for all queries completed in the summary
interval for the WDs.
If Teradata ASM Workloads rule is not enabled, only the first statement will be returned.
Application Programming Reference
335
Chapter 5: Teradata Dynamic Workload Management APIs
TDWM SUMMARY
Parcels
The TDWM SUMMARY request is treated internally as a two statement request, with each
statement generating a response. The two statement response returned from Teradata
Database contains the following sequence of parcel types:
Parcel
Sequence
Parcel
Flavor
Length (Bytes)
Comments/Key Parcel Body Fields
Success
8
18 to 273
StatementNo = 1
ActivityCount = 1
ActivityType = 156
(PCLTWMSUMMARYSTMT)
DataInfo
71
6 to 64100
Optional: This parcel is present if request was
IndicData parcel.
Record
10
• 5 to
64100(record
mode)
• 6 to 64100
(indicator
mode)
Depending on the request (Data or
IndicData), data is returned in record or
indicator mode.
This is the only record returned.
EndStatement
11
6
StatementNo = 2-byte integer
Success
8
18 to 273
StatementNo = 2
ActivityCount = number of record parcels
returned
ActivityType = 134 (PCLTDWMSUMSTMT)
DataInfo
71
6 to 64100
Optional: This parcel is present if request was
IndicData parcel.
Record
10
• 5 to 64100
(record mode)
• 6 to 64100
(indicator
mode)
Depending on the request (Data or
IndicData), data is returned in record or
indicator mode. There is one Summary Data
record returned for each active WD. The
format of this record is described below.
EndStatement
11
6
StatementNo = 2-byte integer
EndRequest
12
4
None
Statement Type: 1
The response to the first statement results in a Record parcel containing the SampleSec field.
336
Field Name
Data Type
Description
SampleSec
SMALLINT
Duration of the collection period, in seconds. This
value represents the collection rate.
Application Programming Reference
Chapter 5: Teradata Dynamic Workload Management APIs
TDWM SUMMARY
Statement Type: 2
The response to the second statement (Request Flag is 0 or 2) results in a Record parcel that
consists of summary information for an active WD in the system collected in the last
collection period. There is one record for each WD.
Note: If Teradata ASM Workloads rule is not enabled, this statement will not be returned.
The following table describes the format of the Summary Data Record parcel.
Field Name
Data Type
Description
WD ID
INTEGER
WD ID to which the request should be assigned.
Arrivals
INTEGER
Number of queries that were classified into this
WD by theTeradata dynamic workload
management software.
Completions
INTEGER
Number of queries that completed in this WD in
this dashboard or logging interval with:
• No error code or an error code of 3158
• No abort flag
• Either an AMP count of > 0 or a Parser CPU
>0
Minimum Response Time
FLOAT
Minimum response time in centiseconds of any
query.
Maximum Response Time
FLOAT
Maximum response time in centiseconds for any
query.
Average Response Time
FLOAT
Average response time in centiseconds for this
workload based on the total response time of all
completions divided by number of completions.
Minimum CPU Time
FLOAT
Minimum CPU in milliseconds used by any one
AMP in any one query that completed in this
WD in this dashboard or logging interval.
Maximum CPU Time
FLOAT
Maximum CPU in milliseconds used by any one
AMP in any one query that completed in this
WD in this dashboard or logging interval.
Average CPU Time
FLOAT
Running total in milliseconds of Parser CPU +
Total AMP CPU of each query that completed in
this WD divided by the number of completions
of queries in this WD in this dashboard or
logging interval.
Delayed Count
INTEGER
Number of queries that were delayed in this WD.
Average Delay Time
FLOAT
Average delay time in centiseconds for all queries
assigned to this WD.
Exception Count
INTEGER
Number of queries with exceptions in this WD.
Application Programming Reference
337
Chapter 5: Teradata Dynamic Workload Management APIs
TDWM SUMMARY
Field Name
Data Type
Description
Met SLG Count
INTEGER
Number of queries that met WD Response Time
SLG requirements.
Note: If the WD does not have Response Time
SLG requirement, the query will still be counted
as met.
Active Query Count
INTEGER
Number of active queries assigned to this WD.
Active Delayed Count
INTEGER
Number of currently delayed queries in this WD.
Error Count
INTEGER
Number of queries that finished in this WD in
this dashboard or logging interval with an error
code > 0 but not 3158 or 3156.
Abort Count
INTEGER
Number of queries that finished in this WD in
this dashboard or logging interval with an error
code of 0 or 3156 and an abort flag.
Other Count
INTEGER
Number of queries that finished in this WD in
this dashboard or logging interval with no:
•
•
•
•
338
Error code
Abort flag
AMP count
Parser CPU
CollectionDate
DATE
Date of the collection of summary information
as pulled from the StartCollectTime field on the
control vproc.
CollectionTime
FLOAT
Time of the collection of summary information
as pulled from the StartCollectTime field on the
control vproc.
VirtualPartNum
INTEGER
Virtual Partition number of the WD.
AvgIOWaitTime
FLOAT
Average duration of sleeps in milliseconds due to
the I/O rate handling over the life of all requests
completing in this WD during this interval.
MaxIOWaitTime
FLOAT
Maximum duration of sleeps in milliseconds due
to the I/O rate handling of a request completing
in this WD during this interval.
AvgOtherWaitTime
FLOAT
Note: This field is reserved for future use.
MaxOtherWaitTime
FLOAT
Note: This field is reserved for future use.
AvgCPURunDelay
FLOAT
Average wait time in milliseconds in the run
queue of all the requests completing in this WD
during this interval.
MaxCPURunDelay
FLOAT
Maximum wait time in milliseconds in the run
queue of a request completing in this WD during
this interval.
Application Programming Reference
Chapter 5: Teradata Dynamic Workload Management APIs
TDWM SUMMARY
Field Name
Data Type
Description
AvgSeqRespTime
FLOAT
Average of the sum of the response times of the
steps (as if all steps had been executed
sequentially) of all the requests completing in
this WD during this interval, in milliseconds.
MaxSeqRespTime
FLOAT
Maximum sum of the response times of the steps
(as if all steps had been executed sequentially) of
a request completing in this WD during this
interval, in milliseconds.
AvgLogicalIO
FLOAT
Average count of logical I/Os of all requests
completing in this WD during this interval.
MaxLogicalIO
FLOAT
Maximum count of logical I/Os for a request
completing in this WD during this interval.
AvgLogicalKBs
FLOAT
Average logical I/O in KB of all requests
completing in this WD during this interval.
MaxLogicalKBs
FLOAT
Maximum logical I/O usage in KB of all requests
completing in this WD during this interval.
AvgPhysicalIO
FLOAT
Average count of physical I/Os of all requests
completing in this WD during this interval.
MaxPhysicalIO
FLOAT
Maximum physical I/O usage of all requests
completing in this WD during this interval.
AvgPhysicalKBs
FLOAT
Average physical I/O usage in KB of all requests
completing in this WD during this interval.
MaxPhysicalKBs
FLOAT
Maximum physical I/O usage in KB for a request
completing in this WD during this interval.
Sample Input
The following example shows how the parcels for a TDWM SUMMARY request, built by
CLIv2, appear when sent to the Teradata Database server.
Note: In this example, the size of the response buffer in the example is set at the maximum
(64,000 bytes), although you can set it to any size.
Flavor
Length
Body
Num
Name
Bytes
Field
Value
0001
Req
16
Request
TDWM SUMMARY
0003
Data
96
MonVerID
9
0004
Resp
6
BufferSize
64000
Application Programming Reference
339
Chapter 5: Teradata Dynamic Workload Management APIs
TDWM SUMMARY
Sample Output
The following example shows the data returned by the TDWM SUMMARY request. Your
application program may return this data in a different format or display.
Note: Teradata ASM Workloads rule must be enabled to submit a TDWM SUMMARY
request.
The TDWM SUMMARY request reports WD statistics over a given period. As shown in this
example of WD activity returned from the API call, queries have been classified into WDs 1
and 3 and not WDs 2, 4, and 5.
SUCCESS parcel:
StatementNo=1,
ActivityCount=1,
ActivityType=156, FieldCount=1
TDWM Summary Request successful.
Sample Seconds: 120
SUCCESS parcel:
StatementNo=2,
ActivityCount=5,
ActivityType=156, FieldCount=43
TDWM Summary - # of WDIds: 5
WLC
ID
----12
0
Arrivals Complete WereDlyd
Min Resp Max Resp Avg Resp
Collection Date/Time
Exceptns
Min CPU
Met SLG
Max CPU
CurrActv
Avg CPU
CurrDlyd
AvgDelay
Abt Cnt
Err Cnt
Othr Cnt
-------0
0
0.0
--------
--------
-------0
-------0
-------0
-------0
-------1
-------0
0.0
0.0
0.0
0.0
0.0
0.0
0
0
0
0
0
0
0.0
0.0
0.0
0.0
0.0
0.0
0
0
0
0
0
0
0.0
0.0
0.0
0.0
0.0
0.0
0
0
0
0
0
0
0.0
0.0
0.0
0.0
0.0
0.0
0
0
0
0
0
0
0.0
0.0
0.0
0.0
0.0
0.0
0
2011/06/15 18:33:49.00
13
0
0
0
0.0
0
2011/06/15 18:33:49.00
14
0
0
0
0.0
0
2011/06/15 18:33:49.00
15
0
0
0
0.0
0
2011/06/15 18:33:49.00
16
0
0
0
0.0
0
2011/06/15 18:33:49.00
340
Application Programming Reference
Chapter 5: Teradata Dynamic Workload Management APIs
TDWM WD ASSIGNMENT
TDWM WD ASSIGNMENT
Purpose
Changes the workload a session or request is assigned to.
Input Data
Element
Data Type
Description
IndByte
BYTE
Indicator bits that specify which fields to treat as NULL if
you are using indicator mode.
Each bit in the byte corresponds to one field in the input
data.
If data is supplied for that field, then set the bit to zero.
If the data for that field is NULL (that is, there is no data
supplied for that field), then set the bit to 1.
Note: The IndByte field is only required if the PM/API
request is submitted in indicator mode.
mon_ver_id
SMALLIN,
NOT NULL
MONITOR software version ID. This can be version 6 or
later.
For a general explanation of monitor version choices, see
“MONITOR VERSION” on page 136.
host_id
SMALLINT
Host upon which the session was established. The host ID
cannot exceed 1023. A host ID of zero identifies the
database operator console.
session_no
INTEGER
Number for the session associated with this record. This
value is assigned by the host (or client) at logon.
Together with a given Host ID, a session number uniquely
identifies a session on the Teradata Database system.
PE_vproc_no
SMALLINT
PE vproc number where the session runs.
scope
SMALLINT
Scope of the change defined:
• 0 = Current request
• 1 = Session
For examples of the scope field, see “Usage Notes” on
page 342.
WLC_id
Application Programming Reference
INTEGER
WD ID to which the request should be assigned.
341
Chapter 5: Teradata Dynamic Workload Management APIs
TDWM WD ASSIGNMENT
Monitor Privileges
To use this request, you must have the ABORTSESSION and MONSESSION privileges as part
of your default role or both privileges must be granted directly to you.
For more information on roles and privileges, see Database Administration and Security
Administration.
Usage Notes
This request is comparable to changing the session priority by the way of the SQL SET
SESSION ACCOUNT statement when Teradata ASM Workloads rule is not enabled.
Use TDWM WD ASSIGNMENT to change the assigned WD for an individual request or
session in cases where the rules imposed by the current WD prevent it from running as
needed.
Use the MONITOR SESSION request to determine host_id, session_no, PE_vproc_no, scope,
and WLC_id for the TDWM WD ASSIGNMENT input.
Note: Teradata ASM Workloads rule must be enabled in the Teradata Viewpoint Workload
Designer portlet to use this request.
The following table shows how the scope determines the effects of the
TDWM WD ASSIGNMENT.
342
IF...
THEN...
scope = 0 (current request) and there is
no active request.
this request has no effect.
scope = 0 (current request) and there is
an active request.
the current active request is moved into the specified
WD. The “change workload” exception if specified is
ignored for this request.
scope = 1 (session) and there is no active
request
all subsequent requests on this session are assigned into
the specified WD. If specified, the “change workload”
exception is ignored for all requests.
scope = 1 (session) and there is an active
request
the current active request, and all subsequent requests
on the session, move into the specified WD. If specified,
the “change workload” exception is ignored for all
requests.
Application Programming Reference
Chapter 5: Teradata Dynamic Workload Management APIs
TDWM WD ASSIGNMENT
Parcels
Parcel
Sequence
Parcel
Flavor
Length (Bytes)
Comments/Key Parcel Body Fields
Success
8
18 to 273
StatementNo = 1
ActivityCount = 0
ActivityType = 159
(PCLTWMWDASSIGNMENTSTMT)
EndStatement
11
6
StatementNo = 1
EndRequest
12
4
None
Sample Input
The following example shows how the parcels for a TDWM WD ASSIGNMENT request, built
by CLIv2, appear when sent to the Teradata Database server.
Note: In this example, the size of the response buffer in the example is set at the maximum
(64,000 bytes), although you can set it to any size.
Flavor
Length
Body
Num
Name
Bytes
Field
Value
0001
Req
16
Request
TDWM WD ASSIGNMENT
0003
Data
8
MonVerID
7
host_id
1
session_no
1000
PE_vproc_no
16383
scope
1
WLC_id
3
BufferSize
64000
0004
Resp
6
Sample Output
The TDWM WD ASSIGNMENT request returns values approximately as shown below when
Teradata ASM Workloads rule is enabled and the following input data is specified:
•
host_id = 1
•
session_no = 1000
•
PE_vproc_no =16383
•
scope = 1
•
WLC_id = 3
Application Programming Reference
343
Chapter 5: Teradata Dynamic Workload Management APIs
TDWM WD ASSIGNMENT
The TDWM WD ASSIGNMENT request commonly returns values in text character format.
Your application program may return the values in a different format or display.
Success parcel:
StatementNo: 1
ActivityCount: 1
ActivityType: 159
FieldCount: 1
DataInfo parcel:
FieldCount: 1
EndStatement.
EndRequest.
344
Application Programming Reference
Chapter 5: Teradata Dynamic Workload Management APIs
USER EVENT CONTROL
USER EVENT CONTROL
Purpose
Activates and deactivates a user event.
Input Data
Element
Data Type
Description
IndByte
BYTE
Indicator bits that specify which fields to treat as NULL
if you are using indicator mode.
Each bit in the byte corresponds to one field in the input
data.
If data is supplied for that field, then set the bit to zero.
If the data for that field is NULL (that is, there is no data
supplied for that field), then set the bit to 1.
Note: The IndByte field is only required if the PM/API
request is submitted in indicator mode.
mon_ver_id
SMALLINT,
NOT NULL
MONITOR software version ID. This can be version 6 or
later.
For a general explanation of monitor version choices, see
“MONITOR VERSION” on page 136.
Request Type
SMALLINT,
NOT NULL
Type of request specified:
• 0 = Deactivate event identified in Event Name
• 1 = Activate event identified in Event Name
Event Name
VARCHAR (32)
The name of the user event. The event name is a
maximum of 30 characters and must be padded with
blanks. It is also case sensitive.
Duration
INTEGER,
NOT NULL
Time, in minutes, that this user event remains active.
This field is valid for active requests only.
A value of zero means the event will remain true.
Note: The evaluation of all events, including user
events, is based on the System Event Timer defined in
the Teradata Dynamic Workload Designer portlet. If the
Duration value is not a multiple of the System Event
timer, then it is rounded to the next System Event timer
value.
Application Programming Reference
345
Chapter 5: Teradata Dynamic Workload Management APIs
USER EVENT CONTROL
Monitor Privileges
To use this request, you must have the ABORTSESSION and MONSESSION privileges as part
of your default role or both privileges must be granted directly to you.
For more information on roles and privileges, see Database Administration and Security
Administration.
Usage Notes
User Events are defined externally only by the name and the attribute of being either active or
inactive. User Events also have an optional duration time that determines the length of time
the Activate event persists. The event times out at the end of the duration time unless it is deactivated or re-activated. A Duration value of zero indicates the Activate (a Request Type value
of 1) is persistent and lasts until explicitly made inactive by another User Event call. User
Events persist across a TPA restart or system failure.
User Event names are global, or system wide and, therefore, you must make sure that no
conflicting usages of User Event Control request calls occur.
Parcels
The following table lists information about the parcels for the USER EVENT CONTROL
request.
Parcel
Sequence
Flavor
Field Length
Comments and Key Parcel Body Fields
Success
8
18 to 273
StatementNo=1
ActivityCount = 1
ActivityType =
PCLUSEREVENTCONTROLSTMT
(169)
DataInfo
71
6 to 64100
Optional: this parcel is present if
request was IndicData parcel.
Record
10
• 5 to 64100
(record mode)
• 6 to 64100
(indicator
mode)
Depending on the request (Data or
IndicData) data is returned in record
or indicator mode. This is the only
record returned.
EndStatement
11
6
StatementNo = 2-byte integer
EndRequest
12
4
None
The response to the USER EVENT CONTROL request results in a single Record parcel
containing the result of the request.
346
Application Programming Reference
Chapter 5: Teradata Dynamic Workload Management APIs
USER EVENT CONTROL
Field Name
Data Type
Description
User-Defined Event
Status
INTEGER,
NOT NULL
Current status of the user-defined event:
Previous User-Defined
Event Status
INTEGER,
NOT NULL
Previous status of the user-defined event:
• 0 = Inactive
• 1 = Active
• 0 = Previously inactive
• 1 = Previously active
• 2 = Previously not defined
The USER EVENT CONTROL request can be used to activate or inactivate a single, specific
User Event.
The response indicates if the operation was successful. For successful operations, the result
(Previous User-Defined Event Status) shows the previous value of this User Event. This allows
the user to know if the User Event was previously active or not. For example, a successful
operation, can return any of the following results:
The result....
indicates...
1,0
the current User Event is Active and it was previously Inactive.
1,0
the current User Event is Inactive and it was previously Active.
1,2
the current User Event is Active and it was previously not defined.
Note: This table only describes some of the possible response combinations, there are others.
Application Programming Reference
347
Chapter 5: Teradata Dynamic Workload Management APIs
Open APIs (SQL Interfaces)
Open APIs (SQL Interfaces)
This section describes the Teradata Dynamic Workload Management SQL interfaces that are
used to manage the workload and update the stored components (such as, WDs and related
data) in the Teradata Dynamic Workload Management. These SQL interfaces consist of UDFs
and external stored procedures that you can invoke from any application.
The SQL interfaces to workload management are installed by the DIPTDWM script as part of
the Teradata Database installation (see “Requirements for Using the API” on page 18).
These SQL interfaces provide similar functionality to the Teradata Dynamic Workload
Management CLIv2 requests.
Note: When issuing Teradata dynamic workload management software UDFs or calling
Teradata dynamic workload management software external stored procedures, you must fully
qualify them by the database name, TDWM.
For examples of Teradata dynamic workload management software functions and external
stored procedures, see the following topics.
348
Application Programming Reference
Chapter 5: Teradata Dynamic Workload Management APIs
GetPSFVersion
GetPSFVersion
Purpose
Returns the current type of Priority Scheduler.
Definition
REPLACE FUNCTION TDWM.GetPSFVersion()
RETURNS VARCHAR (10),
...
;
Usage Notes
On SLES 10 or earlier systems, Performance Groups are used by either the Priority Scheduler
schmon utility or by Teradata Viewpoint Workload Designer portlet.
On SLES 11 or later systems, Priority Scheduler is managed by Teradata ASM, and is
configured using the Teradata Viewpoint workload management portlets. For more
information on those portlets, see Teradata Viewpoint User Guide.
Return Values
Input Parameter
Description
PERFGROUPS
Current Priority Scheduler uses Performance Groups.
WORKLOADS
Current Priority Scheduler uses workload definitions.
Example
This example shows the current Priority Scheduler being used is workload definitions.
SELECT TDWM.GetPSFVersion();
*** Query completed. One row found. One column returned.
*** Total elapsed time was 1 second.
getpsfversion()
Application Programming Reference
WORKLOADS
349
Chapter 5: Teradata Dynamic Workload Management APIs
TDWMAbortDelayedRequest
TDWMAbortDelayedRequest
Purpose
Aborts a request or utility session on the Teradata dynamic workload management software
delay queue.
Definition
REPLACE FUNCTION TDWM.TDWMAbortDelayedRequest
(HostId
SMALLINT,
SessionNo
INTEGER,
RequestNo
INTEGER,
WDId
INTEGER
)
RETURNS INTEGER
.
.
.
;
Input Parameters
Input Parameter
Description
HostId
Host ID for the session.
SessionNo
Number of the session.
RequestNo
Request number of the task.
If the value is zero, the utility session will be aborted.
WDId
WD ID associated with the request in the delay queue being examined.
Usage Notes
The TDWMAbortDelayedRequest function provides similar functionality to a TDWM
DELAY REQUEST CHANGE request. For more information, see “TDWM DELAY REQUEST
CHANGE” on page 313.
Return Value
This function returns a zero if it is successful.
Example
This example shows how to abort a delayed request on SessionNo 1011.
SELECT TDWM.TDWMAbortDelayedRequest(HostId, SessionNo, RequestNo, 0)
350
Application Programming Reference
Chapter 5: Teradata Dynamic Workload Management APIs
TDWMAbortDelayedRequest
FROM TABLE (TDWM.TDWMGetDelayedQueries('O')) AS t1
WHERE SessionNo=1011;
*** Query completed. One row found. One column returned.
*** Total elapsed time was 3 seconds.
TDWMAbortDelayedRequest(HostId,SessionNo,RequestNo,0)
----------------------------------------------------0
Assuming the request on SessionNo 1011 was delayed, it will be aborted as follows:
SELECT DatabaseName FROM dbc.databasesv;
*** Starting at Tue Apr 26 15:22:42 2005
*** Failure 3151 TWM Workload violation: Delay Request Change Abort
Statement# 1, Info =0
Application Programming Reference
351
Chapter 5: Teradata Dynamic Workload Management APIs
TDWMApply
TDWMApply
Purpose
Applies changes to one or more of the Teradata dynamic workload management software
categories.
Definition
REPLACE PROCEDURE TDWM.TDWMApply
(IN RuleSetId
INTEGER,
IN FilterCat
VARCHAR(1),
IN ThrottleCat
VARCHAR(1),
IN WorkloadCat
VARCHAR(1) ,
IN EventCat
VARCHAR(1)
)
.
.
.
;
Input Parameters
Input Parameter
Description
RuleSetID
ID of the rule set to apply. This must be the current rule set.
FilterCat
Request for the Filters rule category:
• Y = Apply changes to the rule category
• N = Skip this rule category
ThrottleCat
Request for the Object Limits rule category:
• Y = Apply changes to the rule category
• N = Skip this rule category
WorkloadCat
Request for the Workloads rule category:
• Y = Apply changes to the rule category
• N = Skip this rule category
EventCat
Request for the Event category:
• Y = Apply changes to the category
• N = Skip this category
352
Application Programming Reference
Chapter 5: Teradata Dynamic Workload Management APIs
TDWMApply
Usage Notes
Caution:
Do not issue TDWMApply while holding locks on any TDWM database tables. This will cause
a self-deadlock condition because Teradata Database must read the TDWM database tables to
perform this apply.
Using the TDWMApply procedure, you can only apply changes to the active rule set.
This procedure activates all rules in the database for the category being applied.
Example
CALL TDWM.TDWMApply (200, 'Y', 'N', 'N', 'N');
Application Programming Reference
353
Chapter 5: Teradata Dynamic Workload Management APIs
TDWMAssignWD
TDWMAssignWD
Purpose
Changes the workload a session or request it is assigned to.
Definition
REPLACE FUNCTION TDWM.TDWMAssignWD
(HostId
SMALLINT,
SessionNo INTEGER,
VprocNo
INTEGER,
Scope
VARCHAR(1),
WDId
INTEGER
)
RETURNS INTEGER
.
.
.
;
Input Parameters
Input Parameter
Description
HostId
ID of the host upon which the session was issued. HostId cannot exceed
1023. A hostid of zero identifies the database operator console.
SessionNo
Session number. SessionNo combined with HostId produces a unique
session ID.
VprocNo
PE Vproc number where the session runs.
Scope
Scope of the change defined:
• R = Change the workload of the current request
• S = Change the workload of the session
WDId
WD ID to which the request should be assigned.
Usage Notes
If Teradata ASM Workloads rule is not enabled and if the database cannot find a valid host ID
and session number combination, an error message is returned.
The TDWMAssignWD function provides similar functionality to a TDWM WD
ASSIGNMENT request. For more information about this interface, see “TDWM WD
ASSIGNMENT” on page 341.
354
Application Programming Reference
Chapter 5: Teradata Dynamic Workload Management APIs
TDWMAssignWD
Return Value
This function returns a zero if it is successful.
Example
SELECT TDWM.TDWMAssignWD(Hostid, sessionNo, runvprocno, 'S', 7)
FROM TABLE (MonitorSession(1,'*',0)) AS t1
where username='user14';
*** Query completed. 5 rows found. One column returned.
*** Total elapsed time was 2 seconds.
TDWMAssignWD(HostId,SessionNo,RunVprocNo,'S',7)
---------------------------------------------------0
0
0
0
0
Application Programming Reference
355
Chapter 5: Teradata Dynamic Workload Management APIs
TDWMEventControl
TDWMEventControl
Purpose
Activates or deactivates a user-defined event.
Definition
REPLACE PROCEDURE TDWM.TDWMEventControl
(IN EventName
VARCHAR(128) CHARACTER SET LATIN,
IN Operation
VARCHAR(1) CHARACTER SET LATIN,
IN Duration
INTEGER,
OUT NewStatus
VARCHAR(8) CHARACTER SET LATIN,
OUT PriorStatus VARCHAR(8) CHARACTER SET LATIN
)
.
.
.
;
Input Parameters
Input Parameter
Description
EventName
Name of the event specified.
Operation
Status of the event:
• A = Active
• I = Inactive
Duration
Time, in minutes, after the event expires.
A value of zero indicates no expiration time.
Usage Notes
The user-defined event specified must be an existing event in the active rule set and can
include the following actions:
356
•
Notifications (for example, send alerts, run programs, or post to a queue table)
•
Activate a health condition (SysCon) or planned environment (OpEnv). The highest
priority for health conditions and planned environments determines the rule state values
that the system will enforce. Rule attributes that can be changed based on the rule state
include:
•
Rule enable flag
•
Rule session, query, and Utility Throttle limits
•
Workload Throttle limits
Application Programming Reference
Chapter 5: Teradata Dynamic Workload Management APIs
TDWMEventControl
•
Priority Scheduler weights
Note: The Priority Scheduler weights attribute is valid on SLES 10 or earlier systems
only.
When a SysCon or OpEnv is activated, the Teradata dynamic workload management
software will switch the attributes for the rule state if it is the highest priority active state. If
not, it will be placed on the active state list. If it becomes the highest priority active state,
then the Teradata dynamic workload management software will switch to the rule state
attributes.
For more information on SysCon and OpEnv, see the Teradata Viewpoint Help.
The TDWMEventControl procedure provides similar functionality to a USER EVENT
CONTROL request. For more information about this interface, see “USER EVENT
CONTROL” on page 345.
Output Parameters
Column Name
Description
NewStatus
Status of the event after the procedure call.
PriorStatus
Status of the event before the procedure call.
Example
CALL TDWM.TDWMEventControl('NodeDownEvent', 'A', 0, NewStatus, PriorStatus);
Application Programming Reference
357
Chapter 5: Teradata Dynamic Workload Management APIs
TDWMEventMapping
TDWMEventMapping
Purpose
Lists all objects that make up the system state.
Definition
REPLACE FUNCTION
RETURNS TABLE
(ObjectName
ObjectType
ObjectId
ObjectActive
PrecSeverity
EventKind
)
TDWM.TDWMEventMapping
VARCHAR(128)
VARCHAR(10)
INTEGER,
CHAR
INTEGER,
VARCHAR(12)
CHARACTER SET UNICODE,
CHARACTER SET LATIN,
CHARACTER SET LATIN,
CHARACTER SET LATIN,
.
.
.
;
Usage Notes
The TDWMEventMapping function provides similar functionality to an EVENT STATUS
request. For more information about this interface, see “EVENT STATUS” on page 299.
Result Rows
Column Name
Description
ObjectType
Type of object, for example: an Event, Expression, SysCon, OpEnv, and a State.
ObjectId
Internal object ID number.
ObjectName
Name of the object.
ObjectActive
Status of the object:
• 0 = Inactive
• 1 = Active
PrecSeverity
Indicator of the Precedence or Severity of the SysCon or OpEnv object types
only:
• SysCon = Indicates the Severity of the associated SysCon.
• OpEnv = Indicates the Precedence of the associated OpEnv.
358
Application Programming Reference
Chapter 5: Teradata Dynamic Workload Management APIs
TDWMEventMapping
Column Name
Description
EventKind
Text string of the specific event. You may see the following strings as a result of
this interface:
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
User Defined SysCon. The user-defined system condition.
User Defined OpEnv. The user-defined operating environment.
Time Period. The time range.
Fatal AMPs. The number of AMPs with the status of FATAL.
Fatal PEs. The number of PEs with the status of FATAL.
Fatal GTWs. The number of Gateways with the status of FATAL.
Nodes Down. The % of nodes down within a clique.
Minimum available AWTs. The number of in-use AMP AWTs.
AMPs In Flow Control. The number of AMPs in flow control.
Average System CPU. This value is calculated by the CPU usage columns in
the ResUsageSpma and ResUsageSps tables. See Resource Usage Macros and
Tables for information.
System CPU Skew. This value is calculated by the CPU usage columns in
the ResUsageSpma and ResUsageSps tables. See Resource Usage Macros and
Tables for information.
WD CPU %. This value is calculated by the CPU usage columns in the
ResUsageSpma and ResUsageSps tables. See Resource Usage Macros and
Tables for information.
WD SLG Response. The % of request in this WD that have met the defined
Response Time Service Level Goal (SLG).
WD SLG Throughput. The % of request in this WD that have met the
defined Throughput SLG.
WD Arrivals. The number of new requests for this WD.
WD Active Request. The number of currently active requests in this WD.
WD Delay Queue Depth. The number of requests on the Delay Queue for
this WD.
WD Delay Query Time. The max time a request has been delayed in this
WD.
WD AWT Wait Time. The max time a request was on an AMP mailbox
waiting for an AWT.
Example
SELECT ObjectName, ObjectType, ObjectId, ObjectActive
FROM TABLE (TDWM.TDWMEventMapping()) AS t1
where objecttype='syscon';
*** Query completed. 3 rows found. 4 columns returned.
*** Total elapsed time was 1 second.
ObjectName
-----------------------------Extra SysCon1
Degraded SysCon
Normal
Application Programming Reference
ObjectType
---------SYSCON
SYSCON
SYSCON
ObjectId
----------225
250
200
ObjectActive
-----------I
I
A
359
Chapter 5: Teradata Dynamic Workload Management APIs
TDWMEventStatus
TDWMEventStatus
Purpose
Returns the currently defined events.
Definition
REPLACE FUNCTION TDWM.TDWMEventStatus(
RequestType
VARCHAR(1))
RETURNS TABLE
(EventId
INTEGER,
EventStatus
CHAR(1) CHARACTER SET LATIN,
EventActiveDate
INTEGER,
EventActiveTime
FLOAT,
ExpressionId
INTEGER,
ExpressionStatus CHAR(1) CHARACTER SET LATIN,
ExpActiveDate
INTEGER,
ExpActiveTime
FLOAT,
RecordType
VARCHAR(8) CHARACTER SET LATIN,
RecordId
INTEGER,
RecordStatus
CHAR(1) CHARACTER SET LATIN,
DueToDuration
CHAR(1) CHARACTER SET LATIN,
StateActiveDate
INTEGER,
StateActiveTime
FLOAT
)
.
.
.
;
Input Parameter
Input Parameter
Description
RequestType
A= Return all events.
C = Return current state events.
Usage Notes
The TDWMEventStatus function provides similar functionality to an EVENT STATUS
request. For more information about this interface, see “EVENT STATUS” on page 299.
360
Application Programming Reference
Chapter 5: Teradata Dynamic Workload Management APIs
TDWMEventStatus
Result Rows
Column Name
Description
EventId
Internal ID of the Event. A value of zero indicates there is no event
associated with this record entry and there are no events associated with
the Normal SysCon, the Always OpEnv and a State.
Events are reported in the order they appear within the associated
expression. Only events included in the associated expression are
included.
EventStatus
Current status of the event. The value is either Inactive or Active.
EventActiveDate
Date when EventStatus was last changed. This is the date when the
EventStatus was set to Inactive or Active.
EventActiveTime
Time when EventStatus was last changed. This is the time when
EventStatus is set to Inactive or Active.
ExpressionId
Internal ID of the Expression. A value of zero indicates there is no
expression associated with this record entry.
There are no expressions associated with the Normal SysCon, the Always
OpEnv, and a State.
For the CURRENT state request, the first TRUE expression associated
with the associated State is included. When there are multiple TRUE
expressions for a state only the first one processed is reported. The order
of processing is consistent within a rule set and, therefore, the same
TRUE expression is reported on every request.
ExpressionStatus
Current status of the Expression:
• 0 = Inactive
• 1 = Active
ExpActiveDate
Date when ExpressionStatus last changed.
ExpActiveTime
Time when Expression Status was last changed. This is the time when
Expression Status was set to either Active or Inactive.
RecordType
Type of record, for example: a SysCon, OpEnv, or Notify Only
Expression.
RecordId
Internal ID of the SysCon or OpEnv depending on the type of record
specified in the RecordType field.
A value of zero indicates the Notify Only Expression record type.
Application Programming Reference
361
Chapter 5: Teradata Dynamic Workload Management APIs
TDWMEventStatus
Column Name
Description
RecordStatus
Current status of the SysCon or OpEnv record:
• Y = Active
• N = Inactive
DueToDuration
An indicator of whether the corresponding Syscon is being considered as
TRUE or is TRUE:
• 0 = Inactive if the SysCon is TRUE based on the defined expressions.
• 1 = Active if the corresponding SysCon is being considered as TRUE
due to the MinDuration value being in affect.
Note: This field is valid only when SysCon is the specified RecordType.
StateActiveDate
Date when RecordStatus was last changed.
StateActiveTime
Time when RecordStatus was last changed.
Example
SELECT * FROM TABLE (TDWM.TDWMEventStatus('c')) AS t1;
*** Query completed. 3 rows found. 14 columns returned.
*** Total elapsed time was 1 second.
EventId
EventStatus
EventActiveDate
EventActiveTime
ExpressionId
ExpressionStatus
ExpActiveDate
ExpActiveTime
RecordType
RecordId
RecordStatus
DueToDuration
ActiveDate
ActiveTime
EventId
EventStatus
EventActiveDate
EventActiveTime
ExpressionId
ExpressionStatus
ExpActiveDate
ExpActiveTime
RecordType
RecordId
RecordStatus
DueToDuration
ActiveDate
ActiveTime
EventId
EventStatus
EventActiveDate
362
0
I
0
0.00000000000000E 000
0
I
0
0.00000000000000E
SYSCON
1
A
N
1070518
8.39380000000000E
0
I
0
0.00000000000000E
0
I
0
0.00000000000000E
OPENV
1
A
N
1070518
8.39380000000000E
0
I
0
000
004
000
000
004
Application Programming Reference
Chapter 5: Teradata Dynamic Workload Management APIs
TDWMEventStatus
EventActiveTime
ExpressionId
ExpressionStatus
ExpActiveDate
ExpActiveTime
RecordType
RecordId
RecordStatus
DueToDuration
ActiveDate
ActiveTime
Application Programming Reference
0.00000000000000E 000
0
I
0
0.00000000000000E 000
STATE
1
A
N
1070517
1.00006000000000E 005
363
Chapter 5: Teradata Dynamic Workload Management APIs
TDWMExceptionRate
TDWMExceptionRate
Purpose
Returns the first record of the TDWM Exception request, which is the collection rate.
Definition
REPLACE FUNCTION TDWM.TDWMExceptionRate()
RETURNS SMALLINT
.
.
.
;
Return Value
The SMALLINT data type returns the duration of the collection period in seconds. This value
represents the collection rate.
Example
SELECT TDWM.TDWMExceptionRate();
*** Query completed. One row found. One column returned.
*** Total elapsed time was 1 second.
TDWMExceptionRate()
------------------60
364
Application Programming Reference
Chapter 5: Teradata Dynamic Workload Management APIs
TDWMExceptions
TDWMExceptions
Purpose
Collects the Teradata dynamic workload management software exception data from the
Teradata Database.
Definition
REPLACE FUNCTION TDWM.TDWMEXCEPTIONS()
RETURNS TABLE
(
VProcID
SMALLINT,
QueryID
BIGINT,
UserName
VARCHAR(128) CHARACTER SET UNICODE,
SessionID
INTEGER,
RequestNum
INTEGER,
LogicalHostID
SMALLINT,
AcctString
VARCHAR(128) CHARACTER SET UNICODE,
WDID
INTEGER,
OpEnvID
INTEGER,
SysConID
INTEGER,
ClassifyTime
FLOAT,
ClassifyDate
INTEGER,
ExceptionTime
FLOAT,
ExceptionDate
INTEGER,
ExceptionValue
INTEGER,
ExceptionAction
VARCHAR(10) CHARACTER SET LATIN,
NewWDID
INTEGER,
ExceptionCode
INTEGER,
ExceptionSubCode
INTEGER,
ErrorText
VARCHAR(255) CHARACTER SET UNICODE,
ExtraInfo
VARCHAR(200) CHARACTER SET UNICODE,
RuleID
INTEGER,
WarningOnly
VARCHAR(1) CHARACTER SET LATIN,
RejectionCat
SMALLINT
)
.
.
.
;
Usage Notes
The TDWMExceptions function provides similar functionality to a TDWM Exceptions
request.For more information about this interface, see “TDWM EXCEPTIONS” on page 316.
Application Programming Reference
365
Chapter 5: Teradata Dynamic Workload Management APIs
TDWMExceptions
Result Rows
Field Name
Description
VprocID
Vproc the request with the exception was running on.
QueryID
Query ID associated with the query that encountered an exception.
UserName
User name used in the query with the exception.
SessionID
Session ID of the query with the exception.
RequestNum
Request number of the query with the exception.
LogicalHostID
Logical host ID of the query with the exception.
AcctString
Account string of the query with the exception.
WDID
WD ID the query with the exception was running in.
OpEnvID
Planned environment ID in force when the query encountered the
exception.
SysConID
Health condition ID in force when the query encountered the exception.
ClassifyTime
Time the query with the exception was classified.
ClassifyDate
Date the query with the exception was classified.
ExceptionTime
Time the query encountered the exception.
ExceptionDate
Date the query encountered the exception.
ExceptionValue
Type of exception that occurred:
•
•
•
•
•
•
•
•
•
•
•
366
01 = Exception time limit exceeded
02 = CPU time (AMP and PE) limit exceeded
03 = AMP CPU skew limit exceeded
04 = AMP I/O count limit exceeded
05 = AMP I/O skew limit exceeded
06 = Max row count (for a step) exceeded
07 =Final row count (for the query) exceeded
08 = Blocked time limit exceeded
09 =Disk to CPU ratio exceeded
10 = Spool space limit exceeded
11 = I/O space
Application Programming Reference
Chapter 5: Teradata Dynamic Workload Management APIs
TDWMExceptions
Field Name
Description
ExceptionAction
Exception action taken by the exception handler:
• A =Abort
• C =Change WD
Note: New WDId contains the new WD.
• L =Log.
• E =Execute Program
Note: ExProgram contains the program name.
• T =Alert
Note: ExAlert contains the alert name.
• N = No action
This option cannot be combined with other actions. It disables
exception detection.
• S =Abort if the statement is a SELECT and no update has been done in
the current transaction
• Q = Insert a row to DBC.SystemQTbl
For example, CE stands for change WD and execute program.
NewWDID
WD the query was moved into if the ExceptionAction was change WD.
ExceptionCode
Database exception code.
ExceptionSubCode
Code for additional information.
Note: This field is not currently used.
ErrorText
Error text generated for the exception.
ExtraInfo
Exception values noted at the time of the exception.
RuleID
Teradata dynamic workload management software rule ID of the rule with
the exception handling directive.
WarningOnly
Indicator whether this was a warning only.
RejectionCat
Teradata dynamic workload management software category this query was
rejected from.
Example
SELECT * from table (TDWM.TDWMExceptions()) as t2;
*** Query completed. 1 row found. 24 columns returned.
*** Total elapsed time was 1 second.
VprocId
16383
QueryId
163837185173601767
UserName LUMBER
SessionId
32
RequestNum
2
LogicalHostId
1
AcctString LUMBER
WdId
11
Application Programming Reference
367
Chapter 5: Teradata Dynamic Workload Management APIs
TDWMExceptions
OpEnv
1
SysCon
1
ClassifyTime 1.55443000000000E 005
ClassifyDate
1090928
ExceptionTime 1.55449000000000E 005
ExceptionDate
1090928
ExceptionValue
2
ExceptionAction LA
NewWDID
11
ExceptionCode
3156
ExceptionSubCode
0
ErrorText CPUTime: 1734ms.
ExtraInfo
RuleId
2
WarningOnly
RejectionCat
0
368
Application Programming Reference
Chapter 5: Teradata Dynamic Workload Management APIs
TDWMGetDelayedQueries
TDWMGetDelayedQueries
Purpose
Returns the delayed query data fields and delay information for releases prior to Teradata
Database 13.10 Teradata Tools and Utilities 13.10.
Definition
REPLACE FUNCTION TDWM.TDWMGetDelayedQueries
(RequestType VARCHAR(1) CHARACTER SET LATIN
)
RETURNS TABLE
(Username
VARCHAR(128) CHARACTER SET UNICODE,
HostId
SMALLINT,
SessionNo
NTEGER,
RequestNo
INTEGER,
RuleName
VARCHAR(128) CHARACTER SET UNICODE,
RuleId
INTEGER,
TotalTimeHeld
INTEGER,
OverRidable
CHAR CHARACTER SET LATIN,
BlockingCnt
INTEGER,
PEId
INTEGER,
WDTimeHeld
INTEGER,
ObjTimeHeld
INTEGER,
UtilTimeHeld
INTEGER,
RuleType
INTEGER
)
.
.
.
;
Input Parameter
Parameter
Description
RequestType
O = Return object delay queue
W = Return workload delay queue
A = Return all delayed queues
Usage Notes
This table function is only supported in Constant Mode.
Application Programming Reference
369
Chapter 5: Teradata Dynamic Workload Management APIs
TDWMGetDelayedQueries
Result Rows
Column Name
Description
Username
User name of the session. This is the name specified when the user is
created; it is used to log on to a session. Within Teradata Database, user
name is almost equivalent to database name.
HostId
Host ID of the session number associated with the delayed request.
SessionNo
Session number associated with the held request.
RequestNo
Request number associated with the delayed request.
RuleName
Name of the rule identified in the Rule ID field.
RuleId
ID of the Workload or the Object Throttle Rule that caused the query to be
delayed.
TotalTimeHeld
Total number of wall-clock seconds that this request or session has been
held.
OverRidable
Request or session allowed to be aborted or released by the administrator. A
session cannot be released if it exceeds the internal AMP worker task limit.
A delayed session can always be aborted.
If the value is Y, then the request or session is overridable.
If the value is N, then the request or session is not overridable.
Note: The replication and queue table requests are controlled internally by
the database and cannot be altered by the administrator.
If Request Flag is 6, this field indicates if the delayed session can be released.
A session cannot be released if it exceeds the internal AMP worker task limit
or an internal utility limit.
A delayed session can always be aborted.
BlockingCnt
Count of the number of consecutive times that this request has been
identified as blocking at least one other session.
The value is zero if Request Flag is 6.
370
PEId
Identifier of the PE VPROC which initiated this request.
WDTimeHeld
Number of seconds the query was held due to a WD rule.
ObjTimeHeld
Number of seconds the query was held due to an Object rule.
UtilTimeHeld
Number of seconds the query was held due to a Utility rule.
RuleType
Indicator on whether the Rule ID is a WD (0), Object (1), or Utility Rule
(2).
Application Programming Reference
Chapter 5: Teradata Dynamic Workload Management APIs
TDWMGetDelayedQueries
Example 1
This example shows how to get the object delay queue.
SELECT * FROM TABLE (TDWM.TDWMGetDelayedQueries('O')) AS t1;
where 'O' is for object.
*** Query completed. One row found. 9 columns returned.
*** Total elapsed time was 1 second.
Username
HostId
SessionNo
RequestNo
WDName
WDId
TimeHeld
OverRidable
BlockingCnt
LUMBER
1
1010
3
test2
1
6676
Y
0
Example 2
This example shows how to get the workload delay queue.
SELECT * FROM TABLE (TDWM.TDWMGetDelayedQueries('W')) AS t1;
where 'W' is for workload delay queue.
*** Query completed. 2 rows found. 9 columns returned.
*** Total elapsed time was 1 second.
Username
HostId
SessionNo
RequestNo
WDName
WDId
TimeHeld
OverRidable
BlockingCnt
LUMBER
1
1008
3
test-wd
6
7131
Y
0
Username
HostId
SessionNo
RequestNo
WDName
WDId
TimeHeld
OverRidable
BlockingCnt
LUMBER
1
1009
3
test-wd
6
7114
Y
0
Example 3
This example shows how to get all the delay queues.
SELECT * FROM TABLE (TDWM.TDWMGetDelayedQueries('A')) AS t1;
where 'A' or null is for all delay queues.
*** Query completed. 3 rows found. 9 columns returned.
Application Programming Reference
371
Chapter 5: Teradata Dynamic Workload Management APIs
TDWMGetDelayedQueries
*** Total elapsed time was 1 second.
Username HostId SessionNo RequestNo WDName WDId TimeHeld OverRidable
-------- ------ --------- --------- ------ ---- -------- --------LUMBER
1
1010
3 test2
1
7717 Y
LUMBER
1
1008
3 test
6
7748 Y
LUMBER
1
1009
3 test
6
7731 Y
372
Application Programming Reference
Chapter 5: Teradata Dynamic Workload Management APIs
TDWMGetDelayedUtilities
TDWMGetDelayedUtilities
Purpose
Returns the utility delay queue.
Definition
REPLACE FUNCTION TDWM.TDWMGetDelayedUtilities ()
RETURNS TABLE
(Username
VARCHAR(128), CHARACTER SET LATIN,
HostId
SMALLINT,
SessionNo
INTEGER,
TotalTimeHeld INTEGER,
OverRidable
CHAR CHARACTER SET LATIN,
PEId
INTEGER,
RequestNum
INTEGER,
WDTimeHeld
INTEGER,
ObjTimeHeld
INTEGER,
UtilTimeHeld
INTEGER,
RuleType
INTEGER
RuleName
VARCHAR(128) CHARACTER SET UNICODE
)
.
.
.
;
Result Rows
Column Name
Description
Username
User name of the session. This is the name specified when the user is created; it is
used to log on to a session. Within Teradata Database, user name is almost
equivalent to database name.
HostId
Host ID of the session number associated with the delayed utility.
SessionNo
Session number associated with the held utility.
TotalTimeHeld
Total number of wall-clock seconds that this request has been held.
Application Programming Reference
373
Chapter 5: Teradata Dynamic Workload Management APIs
TDWMGetDelayedUtilities
Column Name
Description
OverRidable
Request or session allowed to be aborted or released by the administrator. A
session cannot be released if it exceeds the internal AMP worker task limit. A
delayed session can always be aborted.
If the value is Y, then this request or session is overridable.
If the value is N, then this request or session is not overridable.
Note: The replication and queue table requests are controlled internally by the
database and cannot be altered by the administrator.
If Request Flag is 6, this field indicates if the delayed session can be released. A
session cannot be released if it exceeds the internal AMP worker task limit or an
internal utility limit.
A delayed session can always be aborted.
RuleID
ID of the rule that caused this query to be delayed.
RequestNum
Request number associated with the held utility.
WDTimeHeld
Number of seconds this request has been held due to a WD rule.
ObjTimeHeld
Number of seconds this request has been held due to an Object rule.
UtilTimeHeld
Number of seconds this request has been held due to a Utility rule.
RuleType
Indicator on whether the Rule ID is a WD (0), Object (1), or Utility Rule (2).
RuleName
Name of the rule identified in the Rule ID field.
Example
SELECT * FROM TABLE (TDWM.TDWMGetDelayedUtilities()) AS t1;
*** Query completed. 4 rows found. 6 columns returned.
*** Total elapsed time was 1 second.
Username
---------USER1
USER1
USER1
DBC
374
HostId
-----1
1
1
1
SessionNo
--------2709
2710
2711
2712
Total
OverRidable RuleId
TimeHeld
-------- ----------- -----16
0
1
12
0
2
9
0
3
5
0
4
Application Programming Reference
Chapter 5: Teradata Dynamic Workload Management APIs
TDWMInquire
TDWMInquire
Purpose
Returns the status of each category (that is, whether it is active or not).
Definition
REPLACE FUNCTION TDWM.TDWMInquire()
RETURNS TABLE
(RuleSetId
INTEGER,
Filter_category
VARCHAR(10) CHARACTER
Throttle_category VARCHAR(10) CHARACTER
Workload_category VARCHAR(10) CHARACTER
Vent_category
VARCHAR(10) CHARACTER
)
.
.
.
;
SET
SET
SET
SET
LATIN,
LATIN,
LATIN,
LATIN
Result Rows
Column Name
Description
RuleSetId
ID of the rule set to apply. This must be the current rule set.
Filter_Category
Current status of the Filters rule category. The value is either Active or
Inactive.
Throttle_Category
Current status of the Throttle rule category. The value is either Active or
Inactive.
Workload_Category
Current status of the WD rule category. The value is either Active or
Inactive.
Event_Category
Current status of the Event category. The value is either Active or Inactive.
Example
SELECT * FROM TABLE (TDWM.TDWMinquire()) AS t1;
*** Query completed. One row found. 5 columns returned.
*** Total elapsed time was 5 seconds.
RuleSetId Filter_Category Throttle_Category Workload_Category Event_Category
--------- --------------- ----------------- ----------------- -------------9060
Inactive
Inactive
Active
Active
Application Programming Reference
375
Chapter 5: Teradata Dynamic Workload Management APIs
TDWMListWDs
TDWMListWDs
Purpose
Returns a list of the WDs.
Definition
REPLACE FUNCTION
(EnabledOnly
)
RETURNS TABLE
(RuleSetId
EnabledFlag
WDId
WDName
)
.
.
.
;
TDWM.TDWMListWDs
VARCHAR(1) CHARACTER SET LATIN
INTEGER,
VARCHAR(10) CHARACTER SET LATIN,
INTEGER,
VARCHAR(128) CHARACTER SET UNICODE
Input Parameter
Parameter
Description
EnabledOnly
Determines the type of WDs returned:
• N = All disabled and enabled
• Y = Enabled only.
Usage Notes
This table function is only supported in Constant Mode.
The TDWMListWDs function provides similar functionality to a TDWM LIST WD
request.For more information about this interface, see “TDWM LIST WD” on page 321.
Result Rows
376
Column Name
Description
RuleSetId
Rule set in which the WD is located.
EnabledFlag
Indicator of whether the WDs specified are enabled or disabled.
WDId
WD ID to which the request should be assigned.
WDName
Name of the WD.
Application Programming Reference
Chapter 5: Teradata Dynamic Workload Management APIs
TDWMListWDs
Example
SELECT * FROM TABLE (TDWM.TDWMListWDs('Y')) AS t1;
*** Query completed. 40 rows found. 4 columns returned.
*** Total elapsed time was 2 seconds.
RuleSetId
----------9889
9889
9889
9889
9889
9889
9889
9889
9889
9889
Application Programming Reference
EnabledFlag
----------Enabled
Enabled
Enabled
Enabled
Enabled
Enabled
Enabled
Enabled
Enabled
Enabled
WDId
----------201
202
203
204
205
206
207
208
209
210
WDName
-----------------------------WD1
WD2
WD3
WD4
WD5
WD6
WD7
WD8
WD9
WD10
377
Chapter 5: Teradata Dynamic Workload Management APIs
TDWMLoadUtilStatistics
TDWMLoadUtilStatistics
Purpose
Returns the statistics on the load utilities that are available in the system.
Definition
REPLACE FUNCTION TDWM.TDWMLoadUtilStatistics()
RETURNS TABLE
(UtilityType VARCHAR(10),
UtilityCount SMALLINT,
UtilityLimit SMALLINT
)
.
.
.
;
Result Rows
Column Name
Description
UtilityType
Type of utility:
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
378
0 = MultiLoad + FastLoad
1 = MultiLoad
2 = FastLoad
3 = FastExport
4 = ARC
5 - Standalone Mload
6 - Standalone FastLoad
7 - Standalone FastExport
8 - TPT update Op: MultiLoad
9 - TPT load Op: Fastload
10 - TPT export Op: FastExport
11 - JDBC MultiLoad
12 - JDBC FastLoad
13 - JDBC FastExport
14 - CSP Save Dump (FastLoad)
15 - BAR
UtilityCount
Number of utilities of this type that are active.
UtilityLimit
Current limit on the number of utilities of this type.
Application Programming Reference
Chapter 5: Teradata Dynamic Workload Management APIs
TDWMLoadUtilStatistics
Note: There is one record for every utility.
Example
SELECT * FROM TABLE (TDWM.TDWMLoadUtilSTATISTICS()) AS t1;
*** Query completed. 4 rows found. 3 columns returned.
*** Total elapsed time was 3 seconds.
UtilityType
----------MultiLoad
FastLoad
FastExport
ARC
Application Programming Reference
UtilityCount
-----------0
0
0
0
UtilityLimit
-----------30
30
60
350
379
Chapter 5: Teradata Dynamic Workload Management APIs
TDWMReleaseDelayedRequest
TDWMReleaseDelayedRequest
Purpose
Releases a request or utility session in the Teradata dynamic workload management software
delay queue.
Definition
REPLACE FUNCTION TDWM.TDWMReleaseDelayedRequest
(HostId
SMALLINT,
SessionNo
INTEGER,
RequestNo
INTEGER,
WDId
INTEGER
)
RETURNS INTEGER
.
.
.
;
Input Parameters
Input Parameter
Description
HostId
Host ID for the session.
SessionNo
Number of the session.
RequestNo
Request number of the task.
If the value is zero, then the utility session will be released.
WDId
WD ID associated with the request in the delay queue being acted on.
Usage Notes
The TDWMReleaseDelayedRequest function provides similar functionality to a TDWM
DELAY REQUEST CHANGE request. For more information about this interface, see
“TDWM DELAY REQUEST CHANGE” on page 313.
Return Value
This function returns a zero if it is successful.
Example 1: Releasing a Delayed Request
SELECT TDWM.TDWMReleaseDelayedRequest(HostId, SessionNo, RequestNo, 0)
FROM TABLE (TDWMGetDelayedQueries('O')) AS t1
WHERE SessionNo=4531;
380
Application Programming Reference
Chapter 5: Teradata Dynamic Workload Management APIs
TDWMReleaseDelayedRequest
*** Query completed. One row found. One column returned.
*** Total elapsed time was 1 second.
TDWMReleaseDelayedRequest(HostId,SessionNo,RequestNo,0)
------------------------------------------------------0
Example 2: Releasing Multiple Delayed Requests
SELECT TDWM.TDWMAbortDelayedRequest(HostId, SessionNo, RequestNo, 0)
FROM TABLE (TDWMGetDelayedQueries('O')) AS t1
WHERE t1.Username='TwmUser33';
*** Query completed. One row found. One column returned.
*** Total elapsed time was 1 second.
TDWMAbortDelayedRequest(HostId,SessionNo,RequestNo,0)
----------------------------------------------------0
Application Programming Reference
381
Chapter 5: Teradata Dynamic Workload Management APIs
TDWMRuleControl
TDWMRuleControl
Purpose
Updates the EnabledFlag of the rule and the EnabledFlag in the base state for the rule in the
TDWM database.
Definition
REPLACE PROCEDURE TDWM.TDWMRuleControl
(IN RuleSetId
INTEGER,
IN RuleName
VARCHAR(128) CHARACTER SET LATIN,
IN Operation
VARCHAR(1) CHARACTER SET LATIN,
IN TDWMLock
VARCHAR(1) CHARACTER SET LATIN
)
.
.
.
;
Input Parameters
Input Parameter
Description
RuleSetId
ID of the rule set in which the rule is found.
RuleName
Name of the rule specified.
Operation
Request to enable or disable the rule:
• E = Enable the rule
• D = Disable the rule
TDWMLock
Type of request performed on the TDWMLock table:
• W = Wait for the TDWMLock
• A = Abort if the TDWMLock table is locked
• S = Perform the update without locking the TDWMLock table
Note: The TDWM database places an exclusive lock on the
TDWMLock table at startup.
Usage Notes
The TDWMRuleControl procedure must be used with rules defined only with the base state as
this is the only state value that the procedure changes.
Example
CALL TDWM.TDWMRuleControl(1, 'throttle1', 'D', 'W');
382
Application Programming Reference
Chapter 5: Teradata Dynamic Workload Management APIs
TDWMSetLimits
TDWMSetLimits
Purpose
Updates the System Throttle limits of a rule in the TDWM database.
Definition
REPLACE PROCEDURE TDWM.TDWMSetLimits
(IN RuleSetId
INTEGER,
IN RuleName
VARCHAR(128) CHARACTER SET LATIN,
IN TDWMLock
VARCHAR(1) CHARACTER SET LATIN,
IN SessionLimit INTEGER,
IN QueryLimit
INTEGER,
IN UtilityLimit INTEGER
)
.
.
.
;
Input Parameters
Input Parameters
Description
RuleSetId
Rule set in which the rule is found.
RuleName
Name of the rule specified.
TDWMLock
Type of request performed on the TDWMLock table:
• W = Wait for the TDMWLock
• A = Abort if the TDWMLock table is locked
• S = Perform the update without locking the TDWMLock table
Note: The TDWM database places an exclusive lock on the TDWMLock
table at startup.
SessionLimit
Maximum number of concurrent sessions. NULL indicates that the field is
not changed.
QueryLimit
Maximum number of concurrent queries. NULL indicates that the field is
not changed.
UtilityLimit
Maximum number of concurrent utilities. NULL indicates that the field is
not changed.
Example
CALL TDWM.TDWMSetLimits(1, 'throttle1', 'A', NULL, 10, NULL);
Application Programming Reference
383
Chapter 5: Teradata Dynamic Workload Management APIs
TDWMSummary
TDWMSummary
Purpose
Returns the Teradata dynamic workload management software WD summary data fields.
Definition
REPLACE FUNCTION TDWM.TDWMSummary()
RETURNS TABLE
(WDId INTEGER,
Arrivals INTEGER,
Completions INTEGER,
MinRespTime FLOAT,
MaxRespTime FLOAT,
AvgRespTime FLOAT,
MinCPUTime FLOAT,
MaxCPUTime FLOAT,
AvgCPUTime FLOAT,
DelayedCnt INTEGER,
AvgDelayTime FLOAT,
ExceptionCnt INTEGER,
MetSLGCnt INTEGER,
ActiveQueryCnt INTEGER,
ActiveDelayedCnt INTEGER,
ErrorCnt INTEGER,
AbortCnt INTEGER,
VirtualPartNum INTEGER,
AvgIOWaitTime FLOAT,
MaxIOWaitTime FLOAT,
AvgOtherWaitTime FLOAT,
MaxOtherWaitTime FLOAT,
AvgCPURunDelay FLOAT,
MaxCPURunDelay FLOAT,
AvgSeqRespTime FLOAT,
MaxSeqRespTime FLOAT,
AvgLogicalIO FLOAT,
MaxLogicalIO FLOAT,
AvgLogicalKBs FLOAT,
MaxLogicalKBs FLOAT,
AvgPhysicalIO FLOAT,
MaxPhysicalIO FLOAT,
AvgPhysicalKBs FLOAT,
MaxPhysicalKBs FLOAT
)
.
.
.
;
384
Application Programming Reference
Chapter 5: Teradata Dynamic Workload Management APIs
TDWMSummary
Usage Notes
The TDWMSummary function provides similar functionality to a TDWM Summary request.
For more information about this interface, see “TDWM SUMMARY” on page 335.
TDWMSummary returns information for all queries completed in the summary interval for
the WD.
Result Rows
Column Name
Description
WDId
WD ID to which the request should be assigned.
Arrivals
Number of queries that were classified into this WD by the Teradata
dynamic workload management software.
Completions
Number of queries that completed in this WD in this dashboard or
logging interval with:
• No error code or an error code of 3158
• No abort flag
• Either an AMP count of > 0 or a Parser CPU > 0
MinRespTime
Minimum response time in centiseconds of any query.
MaxRespTime
Maximum response time in centiseconds of any query.
AvgRespTime
Average response time in centiseconds for this workload based on the
total response time of all completions divided by number of
completions.
MinCPUTime
Minimum CPU in milliseconds used by any one AMP in any one query
that completed in this WD in this dashboard or logging interval.
MaxCPUTime
Maximum CPU in milliseconds used by any one AMP in any one query
that completed in this WD in this dashboard or logging interval.
AvgCPUTime
Running total in milliseconds of Parser CPU + Total AMP CPU of each
query that completed in this WD divided by the number of completions
of queries in this WD in this dashboard or logging interval.
DelayedCnt
Number of queries that have been delayed in this workload.
AvgDelayTime
Average delay time in centiseconds of all the queries that have been
delayed in this workload.
ExceptionCnt
Number of queries with exceptions in this workload.
MetSLGCnt
Number of queries that met WD Response Time SLG requirements.
Note: If the WD does not have Response Time SLG requirement, the
query will still be counted as met.
ActiveQueryCnt
Application Programming Reference
Number of active queries in this workload.
385
Chapter 5: Teradata Dynamic Workload Management APIs
TDWMSummary
386
Column Name
Description
ActiveDelayCnt
Number of queries currently delayed in this workload.
ErrorCnt
Number of queries that finished in this WD in this dashboard or
logging interval with an error code > 0 but not 3158 or 3156.
AbortCnt
Number of queries that finished in this WD in this dashboard or
logging interval with an error code of 0 or 3156 and an abort flag.
VirtualPartNum
Virtual Partition number of the WD.
AvgIOWaitTime
Average duration of sleeps in milliseconds due to the I/O rate handling
over the life of all requests completing in this WD during this interval.
MaxIOWaitTime
Maximum duration of sleeps in milliseconds due to the I/O rate
handling of a request completing in this WD during this interval.
AvgOtherWaitTime
Note: This field is reserved for future use.
MaxOtherWaitTime
Note: This field is reserved for future use.
AvgCPURunDelay
Average wait time in milliseconds in the run queue of all the requests
completing in this WD during this interval.
MaxCPURunDelay
Maximum wait time in milliseconds in the run queue of a request
completing in this WD during this interval.
AvgSeqRespTime
Average of the sum of the response times of the steps (as if all the steps
had been executed sequentially) of all the requests completing in this
WD during this interval, in milliseconds.
MaxSeqRespTime
Maximum sum of the response times of the steps (as if all steps had
been executed sequentially) of a request completing in this WD during
this interval, in milliseconds
AvgLogicalIO
Average count of logical I/Os for a request completing in this WD
during this interval.
MaxLogicalIO
Maximum count of logical I/Os for a request completing in this WD
during this interval.
AvgLogicalKBs
Average logical I/O usage in KB of all requests completing in this WD
during this interval.
MaxLogicalKBs
Maximum logical I/O usage in KB for a request completing in this WD
during this interval.
AvgPhysicalIO
Average count of physical I/Os of all requests completing in this WD
during this interval.
MaxPhysicalIO
Maximum physical I/O usage of all requests completing in this WD
during this interval.
AvgPhysicalKBs
Average physical I/O usage in KB of all requests completing in this WD
during this interval.
MaxPhysicalKBs
Maximum physical I/O usage in KB for a request completing in this
WD during this interval.
Application Programming Reference
Chapter 5: Teradata Dynamic Workload Management APIs
TDWMSummary
Example
SELECT WDId, Arrivals, MetSLGCnt, ActiveReqs FROM TABLE (TDWM.TDWMSummary()) AS t2 WHERE arrivals <>0;
*** Query completed. 13 rows found. 4 columns returned.
*** Total elapsed time was 1 second.
WDId
----------213
217
221
240
Arrivals
----------8
1
3
109
MetSLGCnt
----------8
0
3
91
Application Programming Reference
ActiveReqs
----------0
0
0
1
387
Chapter 5: Teradata Dynamic Workload Management APIs
TDWMSummaryRate
TDWMSummaryRate
Purpose
Returns the collection rate.
Definition
REPLACE FUNCTION TDWM.TDWMSummaryRate ()
RETURNS SMALLINT
.
.
.
;
Usage Notes
Use the SetSessionRate function to set the collection rate for updating session-level statistics
within memory.
The TDWMSummaryRate function provides similar functionality to a TDWM Summary
request. For more information about this interface, see “TDWM SUMMARY” on page 335.
Return Value
This function returns the duration of the collection period in seconds. This value represents
the collection rate.
Example
SELECT TDWM.TDWMSummaryRate();
*** Query completed. One row found. One column returned.
*** Total elapsed time was 3 seconds.
TDWMSummaryRate()
----------------60
388
Application Programming Reference
Chapter 5: Teradata Dynamic Workload Management APIs
TDWMThrottleStatistics
TDWMThrottleStatistics
Purpose
Returns statistics for throttled database objects or throttled workloads.
Definition
REPLACE FUNCTION TDWM.TDWMThrottleStatistics
(RequestType
VARCHAR(1) CHARACTER SET LATIN
)
RETURNS TABLE
(ObjectType
VARCHAR(17) CHARACTER SET LATIN,
RuleId
INTEGER,
RuleName
VARCHAR(128) CHARACTER SET UNICODE,
ObjectName
VARCHAR(128) CHARACTER SET UNICODE,
SubName
VARCHAR(128) CHARACTER SET UNICODE,
Active
INTEGER,
ThrottleLimit INTEGER,
Delayed
INTEGER,
)
.
.
.
;
Input Parameter
Parameter
Description
RequestType
Q = Return query statistics for throttled database objects.
S = Return session statistics for throttled database objects.
W = Return workload statistics for throttled workloads.
Usage Notes
The TDWMThrottleStatistics function provides similar functionality to a TDWM
STATISTICS request. For more information, see “TDWM STATISTICS” on page 324.
Application Programming Reference
389
Chapter 5: Teradata Dynamic Workload Management APIs
TDWMThrottleStatistics
Result Rows
Column Name
Description
ObjectType
Type of object associated with this statistic:
•
•
•
•
•
•
•
•
•
•
•
•
•
•
RuleId
User
Account
Performance Group
Account String
Profile
Client
Network Address
Application
Database
Table
Macro
Stored Procedure
Workload
Utility
When this field is a Workload, it contains the Workload ID.
This field is zero if this is not for a workload item.
RuleName
When this field is a Workload, it contains the Workload name.
ObjectName
Name of the item.
SubName
If applicable, this name qualifies the above name. Typically this field contains
the database name when the Name field refers to a database table.
Active
Number of requests currently active for this object. This is, the number of active
queries or sessions depending on the information requested in the input record.
ThrottleLimit
Current Teradata dynamic workload management software limit on the object.
This is the limit on the number of queries or session depending on the
information requested in the input record.
A value of -1 indicates that no System Throttle limit is defined.
Note: Active and delayed sessions are not valid when the ThrottleLimit value is
-1.
Delayed
Number of requests on the delay queue at this time for this object.
Example 1: Requesting Query Throttle Statistics
select * from table (TDWM.TDWMThrottleStatistics('Q')) AS t1;
*** Query completed. 4 rows found. 8 columns returned.
*** Total elapsed time was 1 second.
ObjectType
----------
390
RuleId RuleName
----- ----------
ObjectName
----------
Subname
----------
Active
------
ThrottleLimit
-------------
Delayed
-------
Application Programming Reference
Chapter 5: Teradata Dynamic Workload Management APIs
TDWMThrottleStatistics
User
User
Table
Macro
1
2
3
4
test2
test4
table test
macro test
LUMBER
LUMBER
LUMBER
LUMBER
2
1
1
0
ORDERS
VENDMACRO
2
1
1
1
1
0
0
1
Example 2: Requesting Session Throttle Statistics
select * from table (TDWM.TDWMThrottleStatistics('S')) AS t1;
*** Query completed. 2 rows found. 8 columns returned.
*** Total elapsed time was 1 second.
ObjectType
---------User
User
RuleId RuleName
---- ---------1
test2
2
test4
ObjectName
---------LUMBER
LUMBER
Subname
----------
Active
-----2
2
ThrottleLimit
------------4
2
Delayed
------0
0
Example 3: Requesting Workload Throttle Statistics
select * from table (TDWM.TDWMThrottleStatistics('W')) AS t1;
*** Query completed. 2 rows found. 8 columns returned.
*** Total elapsed time was 1 second.
ObjectType
---------Workload
Workload
Workload
Workload
Workload
Workload
Workload
RuleId
---0
2
3
4
5
1
6
RuleName
ObjectName
------------ ---------WD-ConsoleR
WD-ConsoleH
WD-ConsoleM
WD-ConsoleL
WD-Default
test-wd
Application Programming Reference
Subname
----------
Active
------1
0
0
0
0
0
0
ThrottleLimit
------------0
-1
-1
-1
-1
-1
0
Delayed
------1
0
0
0
0
0
2
391
Chapter 5: Teradata Dynamic Workload Management APIs
TDWMThrottleStatistics
392
Application Programming Reference
CHAPTER 6
Query Band APIs
This chapter discusses how to retrieve a query band. A query band can be retrieved through
two types of interfaces:
•
“PM/API (CLIv2 Request)”
•
“Open APIs (SQL Interfaces)”
Before using the query band APIs, you may want to familiarize yourself with the following
topics:
•
“PM/APIs” on page 16
•
“Open APIs” on page 17
•
“Query Band API Features” on page 32
•
“Examples Using PM/API and Open APIs” on page 33
Application Programming Reference
393
Chapter 6: Query Band APIs
PM/API (CLIv2 Request)
PM/API (CLIv2 Request)
This section describes the MONITOR QUERYBAND CLIv2 request.
MONITOR QUERYBAND is the only query band CLIv2 request currently available. This
request provides similar functionality to the MonitorQueryBand function. For information
on the MONITOR QUERYBAND request, see the topic that follows.
394
Application Programming Reference
Chapter 6: Query Band APIs
MONITOR QUERYBAND
MONITOR QUERYBAND
Purpose
Returns the concatenated transaction and session query band for the specified session.
Input Data
Element
Data Type
Description
IndByte
BYTE
Indicator bits that specify which fields to treat as NULL if
you are using indicator mode.
Each bit in the byte corresponds to one field in the input
data.
If data is supplied for that field, then set the bit to zero.
If the data for that field is NULL (that is, there is no data
supplied for that field), then set the bit to 1.
Note: The IndByte field is only required if the PM/API
request is submitted in indicator mode.
mon_ver_id
SMALLINT,
NOT NULL
MONITOR software version ID. This can be version 6 or
later.
For a general explanation of monitor version choices, see
“MONITOR VERSION” on page 136.
host_id
SMALLINT
Logical ID of a host (or client) with sessions logged on. For
example, a hostid of zero identifies internal sessions or
system console sessions.
host_id cannot exceed 1023.
SessionNo
INTEGER
Number of the session. session_no combined with host_id
represents a unique session ID.
RunPEVprocNo
SMALLINT
PE vproc number where the session runs. This is typically
obtained from the RunVprocNo data field of the
MONITOR SESSION response (see “Group I Data Fields”
on page 109). If this field is specified with NULL or zero,
then all PEs will be searched for the session, causing
significant overhead.
Monitor Privileges
To use this request, you must have the MONSESSION privilege as part of your default role or
this privilege must be granted directly to you.
For more information on roles and privileges, see Database Administration and Security
Administration.
Application Programming Reference
395
Chapter 6: Query Band APIs
MONITOR QUERYBAND
Usage Notes
If you encounter a problematic query that is using a large amount of system resources, use the
associated query band to identify the source application issuing the request.
The MONITOR QUERYBAND request cannot be used on internal sessions or sessions that
are logged onto the MONITOR partition. The query band is not stored for these types of
sessions and is only stored for SQL partitions.
Parcels
The MONITOR QUERYBAND request is treated internally as a one statement request that
generates one response. The statement response returned from Teradata Database contains
the following sequence of parcel types:
Parcel
Sequence
Parcel
Flavor
Length (Bytes)
Comments and Key Parcel Body Fields
Success
8
18 to 273
Statement No = 1
ActivityCount = 1
ActivityType = 168
(PCLMONQUERYBANDSTMT)
DataInfo
71
6 to 64100
Optional; this parcel is present if request was
IndicData parcel.
Record
10
• 5 to 64100
(record
mode)
• 6 to 64100
(indicator
mode)
Depending on request (Data or IndicData), data is
in record or indicator mode. This record contains
the query band text.
EndStatement
11
6
StatementNo = 2-byte integer
EndRequest
12
4
None
The Record parcel returns the following field:
Element
Data Type
Description
QueryBand
VARCHAR (0 to 8210),
NOT NULL
Concatenated query band string for the
transaction and session.
The QueryBand column returns the following concatenated transaction and session query
band text:
=T>transaction query band =S> session query band
396
Application Programming Reference
Chapter 6: Query Band APIs
MONITOR QUERYBAND
IF there…
THEN the text will contain…
is only a transaction query band
=T>transaction query band
is only a session query band
=S>session query band
are no query bands
NULL. The return string is zero bytes or NULL in indicator
mode.
Sample Input
The following example shows how the parcels for a MONITOR QUERYBAND request, built
by CLIv2, appear when sent to the Teradata Database server.
Note: In this example, the size of the response buffer in the example is set at the maximum
(64,000 bytes), although you can set it to any size.
Flavor
Length
Body
Num
Name
Bytes
Field
Value
0001
Req
16
Request
MONITOR
QUERYBAND
0003
Data
12
HostId
1
SessionNo
1002
RunPEVprocNo
16383
BufferSize
64000
0004
Resp
6
Sample Output
The following example shows a concatenated query band string that is returned for the
current transaction and session.
=T> job=x1; =S> org=Finance;report=Fin123;
Related Topics
For information on setting the query band for a session or transaction, see SET
QUERY_BAND in SQL Data Definition Language.
Application Programming Reference
397
Chapter 6: Query Band APIs
Open APIs (SQL Interfaces)
Open APIs (SQL Interfaces)
This section describes the SQL interfaces for retrieving a query band and parsing the query
band string for name and value pairs. The SQL interfaces consist of UDFs and external stored
procedures that you can invoke from any application.
Query band external stored procedures run on the PE and can retrieve query bands directly
from memory. Query band functions run on the AMPs and require message passing to
retrieve the query band. The external stored procedures provide better performance than
query band functions.
Note: When issuing query band UDFs, you do not need to fully qualify them by database
name. They are automatically searched by the DBS in the SYSLIB database.
When calling query band external stored procedures, you must fully qualify them by the
database name, SYSLIB.
For examples of query band functions and external stored procedures, see the following
topics.
398
Application Programming Reference
Chapter 6: Query Band APIs
GetQueryBand
GetQueryBand
Purpose
Returns the concatenated query band string for the current transaction and session.
Definition
REPLACE FUNCTION SYSLIB.GetQueryBand()
RETURNS VARCHAR (4106),
.
.
.
;
Usage Notes
The GetQueryBand function can be used in a SELECT statement and can be an input
parameter for a table function.
This function is created in the SYSLIB database by the DEM DIP script. EXECUTE privileges
are granted to PUBLIC by default. For more information, see “Requirements for Using the
API” on page 18.
Return Value
The GetQueryBand function returns the concatenated transaction and session queryband.
Example
SELECT GetQueryBand();
*** Query completed. One row found. One column returned.
*** Total elapsed time was 1 second.
GetQueryBand()
------------------------------------------------------------------=S> a=1;b=2;c=3;d=4;
Related Topics
For information on setting the query band for a session or transaction, see SET
QUERY_BAND in SQL Data Definition Language.
Application Programming Reference
399
Chapter 6: Query Band APIs
GetQueryBandPairs
GetQueryBandPairs
Purpose
Returns the name and value pairs in the query band.
Definition
REPLACE FUNCTION SYSLIB.GetQueryBandPairs(
QueryBandIn VARCHAR(4106),
SearchType SMALLINT
)
RETURNS TABLE
(QBName VARCHAR(129),
QBValue VARCHAR(257)
)
.
.
.
;
REPLACE FUNCTION SYSLIB.GetQueryBandPairs
(QueryBandIn VARCHAR(4106),
SearchType
SMALLINT
)
RETURNS TABLE
(QBName VARCHAR(129),
QBValue VARCHAR(257)
)
.
.
.
;
Input Parameters
Input Parameter
Description
QueryBandIn
Query band string.
SearchType
0 = Return the name-value pairs in both transaction and session query bands
are returned. If the same name occurs in both the transaction and the session
query bands, the value for the transaction query band is returned.
1 = Return only the name-value pairs in the transaction query band.
2 = Return only the name-value pairs in the session query band.
400
Application Programming Reference
Chapter 6: Query Band APIs
GetQueryBandPairs
Result Rows
Column Name
Description
QBName
Name of the query band.
QBValue
Value of the query band.
Usage Notes
GetQueryBandPairs are two overloaded table functions. One requires the query band string to
be passed in; the other uses internal calls to retrieve the query band.
Both functions are created in the SYSLIB database by the DEM DIP script. EXECUTE
privileges are granted to PUBLIC by default. For more information, see “Requirements for
Using the API” on page 18.
Example 1
The following example shows how to call the GetQueryBandPairs function.
SELECT * FROM TABLE(GetQueryBandPairs(0)) AS t1;
*** Query completed. 3 rows found. 2 columns returned.
*** Total elapsed time was 1 second.
QBName
-------------ORG
JOB
JOBID
QBValue
--------------FINANCE
ENDOFMONTH
193858
Example 2
The following example shows how to call the GetQueryBandPairs function using the
MonitorQueryBand function as input.
SELECT * FROM TABLE(GetQueryBandPairs(MonitorQueryBand(1, 103, 16383),
0))
AS t1;
*** Query completed. 3 rows found. 2 columns returned.
*** Total elapsed time was 1 second.
QBName
-------------ORG
JOB
JOBID
Application Programming Reference
QBValue
--------------FINANCE
ENDOFMONTH
193858
401
Chapter 6: Query Band APIs
GetQueryBandSP
GetQueryBandSP
Purpose
Returns the concatenated query band for the current transaction and session.
Definition
REPLACE PROCEDURE SYSLIB.GetQueryBandSP
(OUT queryband VARCHAR(4106)
)
.
.
.
;
Usage Notes
The GetQueryBandSP procedure retrieves the query band directly from memory, so it
performs better than the GetQueryBand UDF.
This procedure is created in the SYSLIB database by the DEM DIP script. EXECUTE privileges
are granted to PUBLIC by default. For more information, see “Requirements for Using the
API” on page 18.
For information on setting the query band for a session or transaction, see SET
QUERY_BAND in SQL Data Definition Language.
Output Parameter
The query band output parameter contains the concatenated transaction and session query
bands.
Example
CALL SYSLIB.GetQueryBandSP(qb);
*** Procedure has been executed.
*** Total elapsed time was 1 second.
queryband
----------------------------------------------------------------=T> aa=123;bb=yxs;cc=mmmmm; =S> a=1;b=2;c=3;d=4;
402
Application Programming Reference
Chapter 6: Query Band APIs
GetQueryBandValue
GetQueryBandValue
Purpose
Returns the value of the specified name in the current query band.
Definition
REPLACE FUNCTION SYSLIB.GetQueryBandValue
(QueryBandIn VARCHAR(4106),
SearchType SMALLINT,
QBName VARCHAR(129)
)
RETURNS VARCHAR (257)
.
.
.
;
REPLACE FUNCTION SYSLIB.GetQueryBandValue
(SearchType SMALLINT,
QBName VARCHAR(129)
)
.
.
.
;
Input Parameters
Input Parameter
Description
QueryBandIn
Query band string.
SearchType
0 = Return the value of the first name-value pair where name is specified
by the QBName input argument. If the query band contains name-value
pairs for the transaction and session, the function searches the
transaction name-value pairs first.
1= Search the transaction name-value pairs in the query band and
return the value that corresponds to the name specified by the QBName
input argument.
2 = Search the session name-value pairs in the query band and return
the value that corresponds to the name specified by the QBName input
argument.
QBName
Application Programming Reference
Name in the query band pair to search for.
403
Chapter 6: Query Band APIs
GetQueryBandValueSP
Output Parameter
Both GetQueryBandValue functions return the value for the specified name in the query
band. If no match is found for QBName, an empty string is returned.
Usage Notes
The GetQueryBandValue functions are two overloaded functions. One requires the query
band string to be passed in; the other uses internal calls to retrieve the query band.
Both functions are created in the SYSLIB database by the DEM DIP script. EXECUTE
privileges are granted to PUBLIC by default. For more information, see “Requirements for
Using the API” on page 18.
Example 1
SELECT GetQueryBandValue(0,'aa');
*** Query completed. One row found. One column returned.
*** Total elapsed time was 1 second.
GetQueryBandValue(0,'aa')
-------------------------------------111
Example 2
SELECT t1.queryid, t1.queryband(FORMAT 'X(20)') FROM
dbc.dbqlogtbl t1 WHERE GetQueryBandValue(t1.queryband, 0, 'aa') =
'123';
*** Query completed. 5 rows found. 2 columns returned.
*** Total elapsed time was 1 second.
QueryID
-------------32,703
32,706
32,707
32,709
32,710
QueryBand
-------------------=T> aa=123;bb=yxs;cc
=T> aa=123;bb=yxs;cc
=T> aa=123;bb=yxs;cc
=T> aa=123;bb=yxs;cc
=T> aa=123;bb=yxs;cc
PurposeGetQueryBandValueSP
Returns the value of the specified name in the current query band.
Definition
REPLACE PROCEDURE SYSLIB.GetQueryBandValueSP
(IN SearchType SMALLINT,
IN QBName VARCHAR (129),
OUT QBValue VARCHAR(257)
)
.
.
404
Application Programming Reference
Chapter 6: Query Band APIs
GetQueryBandValueSP
.
;
Input Parameters
Input Parameter
Description
SearchType
0 = Return the value of the first name-value pair where name is specified
by the QBName input argument. If the query band contains name-value
pairs for the transaction and session, the function searches the
transaction name-value pairs first.
1= Search the transaction name-value pairs in the query band and
return the value that corresponds to the name specified by the QBName
input argument.
2 = Search the session name-value pairs in the query band and return
the value that corresponds to the name specified by the QBName input
argument.
QBName
Name in the query band pair to search for.
Output Parameter
Output Parameter
Description
QBValue
Value of specified name.
Example
CALL SYSLIB.GetQueryBandValueSP(1,'aa',qbval);
*** Procedure has been executed.
*** Total elapsed time was 1 second.
QBValue
-------------------------------------
Application Programming Reference
405
Chapter 6: Query Band APIs
MonitorQueryBand
111
MonitorQueryBand
Purpose
Returns the concatenated query band for the specified session.
Definition
REPLACE FUNCTION SYSLIB.MonitorQueryBand
(HostId
SMALLINT,
SessionNo INTEGER,
RunPEVprocNo SMALLINT)
RETURNS VARCHAR(4106)
)
.
.
.
;
Input Parameters
Input Parameter
Description
HostId
Logical ID of a host.
SessionNo
Number of the session to get the query band for.
RunPEVprocNo
PE vproc number where the session runs. This is obtained from the
RunVprocNo field of a MONITOR SESSION response (see “Group I
Data Fields” on page 109).
Usage Notes
The privileges to use this function are not granted by default. The database administrator
must explicitly grant the privilege to users that require it.
The MonitorQueryBand function provides similar functionality to a MONITOR
QUERYBAND request. For more information about this interface, see “MONITOR
QUERYBAND” on page 395.
Return Value
If successful, the function returns the concatenated query band string as VARCHAR. If there is
no concatenated query band, the function returns an empty string.
Example
SELECT MonitorQueryBand (1, 1003, 16382);
406
Application Programming Reference
Chapter 6: Query Band APIs
MonitorQueryBand
* * * Query completed. One row found. One column returned.
* * * Total elapsed time was 5 seconds.
MonitorQueryBand (1, 1003, 16382)
--------------------------------=T= job=x1; =S= org=Finance; report=Fin123;
Related Topics
For information on setting the query band for a session or transaction, see SET
QUERY_BAND in SQL Data Definition Language.
Application Programming Reference
407
Chapter 6: Query Band APIs
QueryBandReservedNames_TBF
QueryBandReservedNames_TBF
Purpose
Returns all the query band names and descriptions, including those dropped from a release.
Definition
REPLACE FUNCTION SYSLIB.QueryBandReservedNames_TBF ()
RETURNS TABLE
(queryband_name
VARCHAR(128) CHARACTER SET UNICODE,
release_introduced CHAR(5) CHARACTER SET LATIN,
release_dropped
CHAR(5) CHARACTER SET LATIN,
category
CHAR(1) CHARACTER SET LATIN,
max_len
INTEGER,
default_value
VARCHAR(256) CHARACTER SET UNICODE,
description
VARCHAR(512) CHARACTER SET UNICODE,
queryband_type
CHAR(1) CHARACTER SET LATIN
)
.
.
.
;
REPLACE VIEW SYSLIB.QueryBandReservedNames AS
SELECT queryband_name, category, max_len,
default_value, description, queryband_type
FROM TABLE (QueryBandReservedNames_TBF()) as t1
WHERE release_dropped IS NULL
;
Usage Notes
The QueryBandReservedNames view returns the current query band names only.
The QueryBandReservedNames_TBF function and QueryBandReservedNames view are
created in the SYSLIB database by the DEM DIP script. The privileges to use the
QueryBandReservedNames_TBF function and QueryBandReservedNames view are granted
to PUBLIC.
Result Rows
408
Column Name
Description
Queryband_Name
Name of the query band.
Application Programming Reference
Chapter 6: Query Band APIs
QueryBandReservedNames_TBF
Column Name
Description
Release_Introduced
Version number of when the query band name was introduced.
The version number is at the granularity of a minor release in
standard format (that is, two digits for a major release number
followed by a period and two digits for a minor release number).
For example, '14.0' and '14.10'.
Release_Dropped
Value is either NULL or the version number of when the query
band name was dropped. The version number is at the granularity
of a minor release in standard format (that is, two digits for a
major release number followed by a period and two digits for a
minor release number). For example, '14.0' and '14.10'.
Category
• T = The Teradata restricted name. These query band names are
directives to Teradata Database.
• A = The Application query band name. These query band
names are recommended names for use by Teradata, Customer,
and Partner applications.
• I = The Teradata internal name. These query band names are
for internal Teradata use and should not be used by
applications.
Max_Len
Maximum length of the value for the property. The default is 256.
Default_Value
Default value of the property, which is NULL.
Description
Description of how the query band name is used and whether it is
appropriate for a session or transaction query band, or both.
Queryband_Type
• S = The session query band.
• T = The Transaction query band.
• B = The session and transaction query band.
Example
SELECT queryband_name(FORMAT 'X(30)'), release_introduced from
table(queryband reservednames_tbf()) as t1 order by 1;
*** Query completed. 28 rows found. 2 columns returned.
*** Total elapsed time was 3 seconds.
queryband_name
-----------------------------ACTION
APPLICATIONNAME
BLOCKCOMPRESSION
CLIENTUSER
DEADLINE
DESTINATION
GROUP
IMPORTANCE
JOBDEADLINE
JOBID
JOBLEN
JOBSEQ
Application Programming Reference
release_introduced
-----------------12.00
12.00
14.0
12.00
12.00
12.00
12.00
12.00
12.00
12.00
12.00
12.00
409
Chapter 6: Query Band APIs
QueryBandReservedNames_TBF
MAXQUERYTIME
PROXYROLE
PROXYUSER
QUERYISSUETIME
REDRIVE
SOURCE
STARTIME
TVSMIGRATION
TVSTEMPERATURE
TVSTEMPERATURE_FALLBACK
TVSTEMPERATURE_FALLBACKCLOBS
TVSTEMPERATURE_PRIMARY
TVSTEMPERATURE_PRIMARYCLOBS
UTILITYDATASIZE
UTILITYNAME
VERSION
410
12.00
13.00
13.00
12.00
14.00
12.00
12.00
13.10
13.10
14.00
14.00
14.00
14.00
13.10
13.10
12.00
Application Programming Reference
APPENDIX A
Sample PM/API Application
This appendix provides a sample PM/API application based on a sample CLI program. A
PM/API application is no more than a CLI application. The only difference between a regular
SQL CLI application and a PM/API application is:
•
PM/API logs on to a Monitor partition
•
SQL logs onto DBC/SQL partition
Note: This sample PM/API application is for an earlier monitor version. You will need to use
monitor version 9 to return PM/API fields used in creating and enhancing applications.
Sample Application
The following is a sample of a CLI program.
/**********************************************************************/
/* This is a sample PM/API application.
*/
/* 1) Prompts for a logon string
*/
/* 2) Connects to a Teradata RDBMS and establishes a MONITOR session */
/* 3) Prompts for input parameter for MONITOR SESSION; PM/API command */
/* 4) Submits MONITOR SESSION;
*/
/* 5) Retrieves the response, formats and prints the response parcels */
/* 6) Above 3 - 5 are repeated until Q is entered in #3.
*/
/* 7) Disconnets.
*/
/**********************************************************************/
#include <stdio.h>
#include <string.h>
#include <stdlib.h>
#include "samplepmpc.h"
// Global variables
struct DBCAREA dbc;
char
cnta[4];
int
IndicatorMode;
/* see dbcarea.h for definition of structure */
unsigned short TargetVersion = 6;
char
RespMode = 'R';
static int IndicFieldCount = 0;
static char CurrRequestText[32];
#define MON_SESS_REQ
1
// List of field names for Monitor Session Record 2
Application Programming Reference
411
Appendix A: Sample PM/API Application
Sample Application
char *MonSesRec2fieldnamelist[]= {
"HostId",
"LogonProcId",
"RunProcId",
"SessionNo",
"UserName",
"UserAccount",
"UserId",
"LSN",
"LogonTime",
"LogonDate",
"PartName",
"Priority",
"IFPState",
"IFPCPUSec",
"XactCount",
"ReqCount",
"ReqCacheHits",
"AMPState",
"AMPCPUSec",
"AMPIO",
"DeltaAMPSpool",
"Blk1HostId",
"Blk1SessNo",
""Blk1UserId",
"Blk1LMode",
"Blk1OType",
"Blk1ObjDBId",
"Blk1ObjTId",
"Blk1Status",
"Blk2HostId",
"Blk2SessNo",
"Blk2UserId",
"Blk2LMode",
"Blk2OType",
"Blk2ObjDBId",
"Blk2ObjTId",
"Blk2Status",
"Blk3HostId",
"Blk3SessNo",
"Blk3UserId",
"Blk3LMode",
"Blk3OType",
"Blk3ObjDBId",
"Blk3ObjTId",
"Blk3Status",
"MoreBlockers",
"LogonSource",
"TempSpaceUsage",
"HotAmp1CPU",
"HotAmp2CPU",
"HotAmp3CPU",
"HotAmp1IO ",
"HotAmp2IO ",
"HotAmp3IO ",
"HotAmp1CPUId",
"HotAmp2CPUId",
"HotAmp3CPUId",
"HotAmp1IOId",
412
Application Programming Reference
Appendix A: Sample PM/API Application
Sample Application
"HotAmp2IOId",
"HotAmp3IOId",
"LowAmp1CPU",
"LowAmp2CPU",
"LowAmp3CPU",
"LowAmp1IO ",
"LowAmp2IO ",
"LowAmp3IO ",
"LowAmp1CPUId",
"LowAmp2CPUId",
"LowAmp3CPUId",
"LowAmp1IOId",
"LowAmp2IOId",
"LowAmp3IOId",
"AmpCount",
"AvgAmpCPUSec",
"AvgAmpIOCnt",
"ReqStartTime",
"ReqStartDate",
"ReqCPU",
"ReqIO",
"RequestNo",
"WlcId",
"DontReclassifyFlag",
};
/* This routine displays the presence bits along with the field name. */
static void PrintPresenceBits(char *ptr,int fieldcount,char **fieldnamelist)
{
char *tempptr=ptr;
char temp = *ptr;
int i=0;
int bitOn;
char buf[200];
int endlist=0;
printf("\nPresence Bits:\n");
while (i < fieldcount)
{
bitOn = (temp & (char)0x80);
if (!endlist)
{
if (!fieldnamelist ||
(fieldnamelist && strlen(fieldnamelist[i]) == 0))
endlist = 1;
};
if (endlist)
{
sprintf(buf,"Field%03d",i+1);
}
else
strcpy(buf,fieldnamelist[i]);
if (bitOn)
printf("[%02d] %30s \tis \tNULL\n",i,buf);
else
printf("[%02d] %30s \tis \tNOT NULL\n",i,buf);
Application Programming Reference
413
Appendix A: Sample PM/API Application
Sample Application
i++;
if ((i % 8) == 0)
{
tempptr++;
temp = *tempptr;
}
else
temp = temp << 1;
}
printf("\n");
}
/***************************************************************/
/* WRITE_ERROR -- Prints error message that is located in
*/
/*
the response buffer--Error or Failure Parcel */
/***************************************************************/
static void Write_error(char *parcel)
{
int i;
Error_Fail_t *Error_Fail;
Error_Fail = ((struct ERROR_FAIL_Type *) (parcel));
printf("DBS Error code: %d : ",Error_Fail->Code);
for(i=0;i < (int)Error_Fail->Length;i++)
printf("%c",Error_Fail->Msg[i]);
printf("\n");
} /**end write_error**/
/* MONITOR SESSION formatting routines */
static void PrtSes1(char *dataptr)
{
short *SampleRate;
SampleRate = (short *) (dataptr);
printf("Sample rate: %d seconds\n\n", *SampleRate);
}
static void PrtSes2(char *dataptr, int version)
{
MonSesRec2_t *MonSesRec2;
MonSesRecV3_t *MonSesRecV3;
MonSesRecV4_t *MonSesRecV4;
MonSesRecV5_t *MonSesRecV5;
MonSesRec2 = (MonSesRec2_t *) (dataptr);
if (version >= MONVERSION3)
{
MonSesRecV3 = (MonSesRecV3_t *)(((char *) (&MonSesRec2->LogonSource)) +
MonSesRec2->LogonSourceLen);
}
if (version >=MONVERSION4)
{
MonSesRecV4 = (MonSesRecV4_t *) (MonSesRecV3 +1);
}
if (version >=MONVERSION5)
414
Application Programming Reference
Appendix A: Sample PM/API Application
Sample Application
{
MonSesRecV5 = (MonSesRecV5_t *) (MonSesRecV4 +1);
}
printf("HostId: %8d
", MonSesRec2->HostId);
printf("SessionNo: %d\n", MonSesRec2->SessionNo);
printf("LogonPENo: %5d
", MonSesRec2->LogonProcId);
printf("RunVprocNo: %5d\n", MonSesRec2->RunProcId);
printf("PartName: %.16s", MonSesRec2->PartName);
printf("PEState: %.18s\n\n", MonSesRec2->PEState);
printf("LogonDate: %04d/%02d/%02d
",
(int) MonSesRec2->LogonDate / 10000 + 1900,
(int) MonSesRec2->LogonDate / 100 % 100,
(int) MonSesRec2->LogonDate % 100);
printf("LogonTime: %02d:%02d:%05.2f\n",
(int) MonSesRec2->LogonTime / 10000,
(int) MonSesRec2->LogonTime / 100 % 100,
(int) MonSesRec2->LogonTime % 100 +
MonSesRec2->LogonTime (int) MonSesRec2->LogonTime);
printf("UserID: %d ", MonSesRec2->UserID);
printf("LSN: %d\n", MonSesRec2->LSN);
printf("UserName: %.30s\n", MonSesRec2->UserName);
printf("UserAccount: %.30s\n\n", MonSesRec2->UserAccount);
printf("PECPUSec: %10.2f
", MonSesRec2->PECPUSec);
printf("XactCount: %13.2f\n", MonSesRec2->XactCount);
printf("ReqCount: %10.1f
", MonSesRec2->ReqCount);
printf("ReqCacheHits: %10.1f\n\n", MonSesRec2->ReqCacheHits);
printf("AMPState: %.18s\n", MonSesRec2->AMPState);
printf("AMPCPUSec: %9.2f
", MonSesRec2->AMPCPUSec);
printf("AMPIO: %7.2f\n", MonSesRec2->AMPIO);
printf("Request_AMPSpool: %4.1f\n\n", MonSesRec2->Delta_AMPSpool);
printf("Blk_1_HostId: %6d
", MonSesRec2->Blk_1_HostId);
printf("Blk_2_HostId: %6d
", MonSesRec2->Blk_2_HostId);
printf("Blk_3_HostId: %6d\n", MonSesRec2->Blk_3_HostId);
printf("Blk_1_SessNo: %6d
", MonSesRec2->Blk_1_SessNo);
printf("Blk_2_SessNo: %6d
", MonSesRec2->Blk_2_SessNo);
printf("Blk_3_SessNo: %6d\n", MonSesRec2->Blk_3_SessNo);
printf("Blk_1_UserID: %6d
", MonSesRec2->Blk_1_UserID);
printf("Blk_2_UserID: %6d
", MonSesRec2->Blk_2_UserID);
printf("Blk_3_UserID: %6d\n", MonSesRec2->Blk_3_UserID);
printf("Blk_1_LMode: %c
", MonSesRec2->Blk_1_LMode);
printf("Blk_2_LMode: %c
", MonSesRec2->Blk_2_LMode);
printf("Blk_3_LMode: %c\n", MonSesRec2->Blk_3_LMode);
printf("Blk_1_OType: %c
", MonSesRec2->Blk_1_OType);
printf("Blk_2_OType: %c
", MonSesRec2->Blk_2_OType);
printf("Blk_3_OType: %c\n", MonSesRec2->Blk_3_OType);
printf("Blk_1_ObjDBId: %5d
", MonSesRec2->Blk_1_ObjDBId);
printf("Blk_2_ObjDBId: %5d
", MonSesRec2->Blk_2_ObjDBId);
printf("Blk_3_ObjDBId: %5d\n", MonSesRec2->Blk_3_ObjDBId);
Application Programming Reference
415
Appendix A: Sample PM/API Application
Sample Application
printf("Blk_1_ObjTId: %6d
", MonSesRec2->Blk_1_ObjTId);
printf("Blk_2_ObjTId: %6d
", MonSesRec2->Blk_2_ObjTId);
printf("Blk_3_ObjTId: %6d\n", MonSesRec2->Blk_3_ObjTId);
printf("Blk_1_Status: %c
", MonSesRec2->Blk_1_Status);
printf("Blk_2_Status: %c
", MonSesRec2->Blk_2_Status);
printf("Blk_3_Status: %c\n", MonSesRec2->Blk_3_Status);
printf("MoreBlockers: %c\n\n", MonSesRec2->MoreBlockers);
MonSesRec2->LogonSource[MonSesRec2->LogonSourceLen] = '\0';
printf("LogonSource: %.128s\n\n", MonSesRec2->LogonSource);
/* MonVerId 3 fields */
if (version < MONVERSION3)
return;
printf("HotAmp1CPU: %9.2f
", MonSesRecV3->HotAmp1CPU);
printf("HotAmp2CPU: %9.2f
", MonSesRecV3->HotAmp2CPU);
printf("HotAmp3CPU: %9.2f\n", MonSesRecV3->HotAmp3CPU);
printf("HotAmp1CPUId: %7d
", MonSesRecV3->HotAmp1CPUId);
printf("HotAmp2CPUId: %7d
", MonSesRecV3->HotAmp2CPUId);
printf("HotAmp3CPUId: %7d\n\n", MonSesRecV3->HotAmp3CPUId);
printf("HotAmp1IO: %10.2f
", MonSesRecV3->HotAmp1IO);
printf("HotAmp2IO: %10.2f
", MonSesRecV3->HotAmp2IO);
printf("HotAmp3IO: %10.2f\n", MonSesRecV3->HotAmp3IO);
printf("HotAmp1IOId: %8d
", MonSesRecV3->HotAmp1IOId);
printf("HotAmp2IOId: %8d
", MonSesRecV3->HotAmp2IOId);
printf("HotAmp3IOId: %8d\n\n", MonSesRecV3->HotAmp3IOId);
printf("LowAmp1CPU: %9.2f
", MonSesRecV3->LowAmp1CPU);
printf("LowAmp2CPU: %9.2f
", MonSesRecV3->LowAmp2CPU);
printf("LowAmp3CPU: %9.2f\n", MonSesRecV3->LowAmp3CPU);
printf("LowAmp1CPUId: %7d
", MonSesRecV3->LowAmp1CPUId);
printf("LowAmp2CPUId: %7d
", MonSesRecV3->LowAmp2CPUId);
printf("LowAmp3CPUId: %7d\n\n", MonSesRecV3->LowAmp3CPUId);
printf("LowAmp1IO: %10.2f
", MonSesRecV3->LowAmp1IO);
printf("LowAmp2IO: %10.2f
", MonSesRecV3->LowAmp2IO);
printf("LowAmp3IO: %10.2f\n", MonSesRecV3->LowAmp3IO);
printf("LowAmp1IOId: %8d
", MonSesRecV3->LowAmp1IOId);
printf("LowAmp2IOId: %8d
", MonSesRecV3->LowAmp2IOId);
printf("LowAmp3IOId: %8d\n\n", MonSesRecV3->LowAmp3IOId);
printf("AvgAmpCPUSec:%8.2f
", MonSesRecV3->AvgAmpCPUSec);
printf("AvgAmpIOCnt: %8.2f\n", MonSesRecV3->AvgAmpIOCnt);
printf("AmpCount: %11d\n\n", MonSesRecV3->AmpCount);
printf("TempSpaceUsg: %7.2f\n\n", MonSesRecV3->TempSpaceUsage);
if (version <MONVERSION4)
return;
/* MonVerId 4 fields */
416
Application Programming Reference
Appendix A: Sample PM/API Application
Sample Application
printf("ReqStartTime: %04d/%02d/%02d
(int) MonSesRecV4->ReqStartDate /
(int) MonSesRecV4->ReqStartDate /
(int) MonSesRecV4->ReqStartDate %
printf("%02d:%02d:%05.2f",
(int) MonSesRecV4->ReqStartTime /
(int) MonSesRecV4->ReqStartTime /
(int) MonSesRecV4->ReqStartTime %
MonSesRecV4->ReqStartTime (int) MonSesRecV4->ReqStartTime);
printf("
printf("
",
10000 + 1900,
100 % 100,
100);
10000,
100 % 100,
100 +
ReqCPU: %10.2f", MonSesRecV4->ReqCPU);
ReqIO: %10.2f\n", MonSesRecV4->ReqIO);
if (version <MONVERSION5)
return;
/* MonVerId 5 fields */
printf("ReqNo:%d
WlcId: %d
DontReclassifyFlag: %d\n",
MonSesRecV5->ReqNo,
MonSesRecV5->WlcId,MonSesRecV5->DontReclassifyFlag);
}
static void CheckSuccess(int ActivityType,
int ActivityCount,
int StatementNo)
{
switch (ActivityType)
{
case PCLSTMTNULL:
printf("Null statement successful. \n\n");
break;
}
return;
}
static void CheckData(int ActivtyType, int StatementNo)
{
DataInfo_t * DataInfo;
int
i;
DataInfo = (DataInfo_t *) (dbc.fet_data_ptr);
printf("\nCheckData called for Indicator mode data info parcel.\n");
printf("Field Count: %d \n", DataInfo->field_count);
IndicFieldCount
= DataInfo->field_count;
if (DataInfo->field_count > MAXFIELDS)
DataInfo->field_count = MAXFIELDS;
for (i = 0; i < DataInfo->field_count; i++)
{
printf("Field %d: Type = %d Size = %d\n", i + 1,
DataInfo->FieldData[i].FType,
DataInfo->FieldData[i].FSize);
}
Application Programming Reference
417
Appendix A: Sample PM/API Application
Sample Application
return;
}
static void CheckRecord(int ActivtyType, int StatementNo, int ActivityCount)
{
switch (ActivtyType)
{
case PCLMONSESS:
if (StatementNo == 1)
PrtSes1(dbc.fet_data_ptr);
else if (StatementNo == 2)
{
int IndLen=0;
if (IndicatorMode)
{
switch (TargetVersion)
{
case MONVERSION3:
case MONVERSION4:
IndLen = 10;
break;
case MONVERSION5:
case MONVERSION6:
default:
IndLen = 11;
break;
}
PrintPresenceBits(dbc.fet_data_ptr,IndicFieldCount,MonSesRec2fieldnamelist);
dbc.fet_data_ptr = (char *)dbc.fet_data_ptr + IndLen;
}
PrtSes2(dbc.fet_data_ptr,TargetVersion);
printf("\n");
printf("----------------------------------------------------\n\n");
}
break;
default:
printf("\nFound a funny parcel number: %d\n",ActivtyType);
break;
}
}
/***************************************************************/
/* SET_OPTIONS -- sets cli options (record,field,indicator
*/
/*
mode; etc..)
*/
/*
Sets size of buffers (request and response) */
/***************************************************************/
set_options()
{
dbc.change_opts = 'Y';
dbc.resp_mode = 'R';
dbc.use_presence_bits = 'Y';
dbc.keep_resp = 'N';
dbc.wait_across_crash = 'N';
418
Application Programming Reference
Appendix A: Sample PM/API Application
Sample Application
dbc.tell_about_crash = 'Y';
dbc.loc_mode = 'Y';
dbc.var_len_req = 'N';
dbc.var_len_fetch = 'N';
dbc.save_resp_buf = 'N';
dbc.two_resp_bufs = 'N';
dbc.ret_time = 'N';
dbc.parcel_mode = 'Y';
dbc.wait_for_resp = 'Y';
dbc.req_proc_opt = 'E';
dbc.req_buf_len = 256;
dbc.resp_buf_len = 32000;
return(0);
} /**end set_options**/
/***************************************************************/
/* EXITOUT -- If connected logs off session. Cleans up
*/
/*
any used memory.
*/
/***************************************************************/
void exitout(int status)
{
Int32 result;
if (status == CONNECTED)
{
printf ("Logging off.\n");
dbc.func = DBFDSC;
DBCHCL (&result,cnta,&dbc);
if (result != EM_OK)
printf("disconnect failed -- %s\n", dbc.msg_text);
}
DBCHCLN(&result,cnta);
if (result != EM_OK)
printf("cleanup failed -- %s\n", dbc.msg_text);
exit(0);
} /**end exitout**/
/***************************************************************/
/* INITIALIZE_DBCAREA -- Sets default options (clispb.dat) in */
/*
dbcarea by calling DBCHINI()
*/
/***************************************************************/
initialize_dbcarea()
{
Int32 result;
dbc.total_len = sizeof(struct DBCAREA);
DBCHINI(&result,cnta,&dbc);
if (result != EM_OK)
{ /* if we can't initialize, we can't go on, so exit */
printf("init failed -- %s\n", dbc.msg_text);
exitout(NOT_CONNECTED);
}
return(0);
Application Programming Reference
419
Appendix A: Sample PM/API Application
Sample Application
}
/**end initialize_dbcarea**/
/***************************************************************/
/* LOGON_TO_DBC -- Connects session and logs on to DBC
*/
/*
Fetches result of connection to check if
*/
/*
successful
*/
/***************************************************************/
logon_to_dbc(char * logonstr)
{
struct CliCONNECTType connectstr;
Int32
result, i;
char
TempString[30];
for (i = 0; i < 30; i++)
TempString[i] = ' ';
for (i = 0; i < 30; i++)
{
if (logonstr[i] == '/')
{
TempString[i] = '\0';
break;
}
TempString[i] = logonstr[i];
}
printf("Logging on to %s ...\n", TempString);
dbc.logon_ptr = logonstr;
dbc.logon_len = strlen(logonstr);
dbc.func = DBFCON;
dbc.run_ptr = (char *) &connectstr;
strncpy(connectstr.PartitionName, "MONITOR
connectstr.Function = 0;
dbc.run_len = sizeof(struct CliCONNECTType);
", 16);
DBCHCL(&result,cnta,&dbc);
if (result != EM_OK) /*if connect fails exit*/
{
printf("connect failed -- %s\n",dbc.msg_text);
exitout(NOT_CONNECTED);
}
printf("Logon successful.\n");
return(0);
} /**end logon_to_dbc**/
/***************************************************************/
/* CLOSE_REQUEST -- Terminates and cleans up specified request */
/***************************************************************/
close_request(Int32 req_id, Int32 sess_id)
{
Int32 result;
dbc.i_sess_id = sess_id;
dbc.i_req_id = req_id;
dbc.func=DBFERQ;
DBCHCL(&result,cnta,&dbc);
420
Application Programming Reference
Appendix A: Sample PM/API Application
Sample Application
if (result !=EM_OK)
{
printf("end request failed -- %s\n", dbc.msg_text);
exitout(CONNECTED);
}
return(0);
} /**end close_request**/
/***************************************************************/
/* OPEN_REQUEST -- Sends request to DBC
*/
/***************************************************************/
open_request (int InReqType,
void *UsingPtr)
{
Int32
result;
char
CurrRequestText[32];
/* set up for a new request */
dbc.func = DBFIRQ;
dbc.using_data_ptr = (char *) UsingPtr;
switch (InReqType)
{
case MON_SESS_REQ:
strcpy(CurrRequestText,"MONITOR SESSION;");
dbc.using_data_len = sizeof(monsess_t);
break;
default:
printf("Internal error\n");
exitout(CONNECTED);
}
dbc.req_ptr = &CurrRequestText[0];
dbc.req_len = strlen (CurrRequestText);
printf ("\nSubmitting request %s ...\n", dbc.req_ptr);
/* Submit request */
DBCHCL (&result,cnta,&dbc);
if (result != EM_OK)
{
printf ("result = %d \n", result);
printf ("initiate request failed -- %s \n", dbc.msg_text);
exitout(CONNECTED);
}
return(EM_OK);
} /**end open_request**/
int fetch_request(Int32 request, Int32 session)
{
int
status;
int
StatementNo = 0;
int
ActivityType = 0;
int
ActivityCount = 0;
Application Programming Reference
421
Appendix A: Sample PM/API Application
Sample Application
Int32
int
result;
ReturnCode;
dbc.i_sess_id = session;
dbc.i_req_id = request;
dbc.func = DBFFET;
status = OK;
ReturnCode = OK;
/* fetch one parcel at a time until all parcels are used up
/* or an error occurs */
*/
while (status == OK)
{
DBCHCL(&result,cnta,&dbc);
if (result == REQEXHAUST)
status = STOP;
else if (result != EM_OK)
status = NOT_OK;
else
{
switch ((Int16) (dbc.fet_parcel_flavor))
{
case PCLSUCCESS :
/*Success Parcel */
{
struct PclSUCCESSType
succ;
memcpy(&succ,dbc.fet_data_ptr-4,4);
memcpy(&succ,dbc.fet_data_ptr-4,succ.Length+4);
StatementNo = succ.StatementNo;
ActivityCount = *(int *)(&succ.ActivityCount[0]);
ActivityType = succ.ActivityType;
if ( succ.WarningLength > 0 )
printf("%s \n", succ.WarningMsg);
CheckSuccess(ActivityType, ActivityCount, StatementNo);
}
break;
case PclDATAINFO :
CheckData(ActivityType, StatementNo);
break;
case PclRECORD :
/*Returned data */
CheckRecord(ActivityType, StatementNo, ActivityCount);
break;
case PclFAILURE :
/*Failure parcel*/
case PclERROR :
/*Error parcel */
status = STOP;
Write_error(dbc.fet_data_ptr);
ReturnCode = PclERROR;
break;
} /*switch*/
}
} /*while*/
if (status == NOT_OK)
{
printf("fetch failed -- %s \n", dbc.msg_text);
exitout(CONNECTED);
} /*if*/
422
Application Programming Reference
Appendix A: Sample PM/API Application
Sample Application
return(ReturnCode);
} /**end fetch_request**/
static Boolean MonSession()
{
monsess_t
MonSess;
int
i;
char
InString[MAXNAME];
/* Initializations */
MonSess.monheader.version = TargetVersion;
MonSess.monheader.indicbyte = '\0';
for (i = 0; i < MAXNAME; i++)
monsess.user[i] = ' ';
printf("Enter logical hostid (* for all hosts) or Q)uit: ");
gets(InString);
if (!strcmp(InString, "*") || (strlen(InString) == 0))
MonSess.hostid = (Int16) 65535;
else if (!strcmp(InString, "Q") || !strcmp(InString, "q"))
return (TRUE);
else
MonSess.hostid = atoi(InString);
printf("Enter user name (* for all users): ");
gets(InString);
if (!strcmp(InString, "*") || (strlen(InString) == 0))
{
for (i = 0; i < MAXNAME; i++)
{
if (InString[i] == '\0')
break;
MonSess.user[i] = InString[i];
}
}
printf("Enter session
gets(InString);
if (!strcmp(InString,
MonSess.session =
else
MonSess.session =
if (RespMode == 'I'
{
dbc.resp_mode =
IndicatorMode =
}
else
{
dbc.resp_mode =
IndicatorMode =
}
number (* for all sessions): ");
"*") || (strlen(InString) == 0))
0;
atoi(InString);
|| RespMode == 'i')
'I';
TRUE;
'R';
FALSE;
open_request( MON_SESS_REQ,&MonSess);
fetch_request(dbc.o_req_id, dbc.o_sess_id);
close_request(dbc.o_req_id, dbc.o_sess_id);
Application Programming Reference
423
Appendix A: Sample PM/API Application
Sample Application
return (FALSE);
}
main (int argc, char **argv)
{
char
LogonString[MAXLOGONSIZE];
Boolean stop = FALSE;
initialize_dbcarea();
set_options();
//6: Teradata 12.x;
TargetVersion = 6;
5: Teradata 6.x
4: Teradata 5.x
// 'R' no presence bits returned; 'I' presence bits returned
RespMode = 'I';
IndicatorMode = TRUE;
printf ("TargetVersion(argv1) = %d, RespMode(argv2) = %c \n\n",
TargetVersion, RespMode);
/* Establish session */
printf ("Enter logon string (tdpid/user,password): ");
gets (LogonString);
if (strlen(LogonString) == 0)
{
printf ("NULL logon string not accepted.\n");
return (1);
}
logon_to_dbc(LogonString);
if (fetch_request(dbc.o_req_id,dbc.o_sess_id) != OK)
exitout(NOT_CONNECTED);
close_request(dbc.o_req_id,dbc.o_sess_id);
while (stop == FALSE)
stop = MonSession();
/* Logoff and cleanup */
exitout(CONNECTED);
return 0;
} /**end main**/
424
Application Programming Reference
Appendix A: Sample PM/API Application
Header File for Sample PMPC Application
Header File for Sample PMPC Application
This section defines the contents for all parcel flavors. Each parcel is defined in the Notes
section under the definition of each parcel.
#ifndef PMPC_H
#define PMPC_H
/* These
#include
#include
#include
#include
are standard CLI include files */
"coptypes.h"
"coperr.h"
"dbcarea.h"
"parcel.h"
/*****************************************************************/
/*
Purpose To define the data type for kinds of activities
returned in the Ok and Success parcels. */
typedef unsigned short pclstmt_t;
/* Purpose
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
To express the kind of activity within Ok and Success parcels.
PCLSTMTNUL
PCLRETSTMT
PCLINSSTMT
PCLUPDSTMT
PCLUPDRETSTMT
PCLDELSTMT
PCLCTSTMT
PCLMODTABSTMT
PCLCVSTMT
PCLCMSTMT
PCLDROPTABSTMT
PCLDROPVIEWSTMT
PCLDROPMACSTMT
PCLDROPINDSTMT
PCLRENTABSTMTT
PCLRENVIEWSTMT
PCLRENMACSTMT
PCLCREINDSTMT
PCLCDSTMTT
PCLCREUSERSTMT
PCLGRANTSTMT
PCLREVOKESTMT
PCLGIVESTMT
PCLDROPDBSTMT
PCLMODDBSTMT
PCLDATABASESTMT
PCLBTSTMT
PCLETSTMT
PCLABORTSTMT
PCLNULLSTMT
PCLEXECSTMT
PCLCMNTSETSTMT
PCLCMNTGETSTMT
PCLECHOSTMT
Application Programming Reference
*/
(0)
(1)
(2)
(3) /* UPDATE
*/
(4) /* UPDATE ... RETRIEVING
*/
(5)
(6)
(7)
(8)
(9)
(10)
(11)
(12)
(13)
(14)
(15)
(16)
(17)
(18)
(19)
(20)
(21)
(22)
(23)
(24)
(25)
(26)
(27)
(28)
(29)
(30)
(31) /* COMMENT set statement
*/
(32) /* COMMENT returning statement */
(33)
425
Appendix A: Sample PM/API Application
Header File for Sample PMPC Application
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
426
PCLREPVIEWSTMT
PCLREPMACSTMT
PCLCHECKPTSTMT
PCLDELJRNLSTMT
PCLROLLBACKSTMT
PCLRELLOCKSTMT
PCLHUTCONFIGSTMT
PCLVCHECKPTSTMT
PCLDUMPJRNLSTMT
PCLDUMPDBSTMT
PCLRESTORESTMT
PCLROLLFORWSTMT
PCLDELDBSTMT
PCLCLEARDUMPST
PCLSAVEDUMPSTMT
PCLSHOWSTMT
PCLHELPSTMT
PCLBEGINLOADSTMT
PCLCHKPTLOADSTMT
PCLENDLOADSTMT
PCLLINSTMT
PCLGRANTLOGONSTMT
PCLREVOKELOGONSTMT
PCLBEGACCLOGSTMT
PCLENDACCLOGSTMT
PCLCOLLSTATSTMT
PCLDROPSTATSTMT
PCLSESSETSTMT
PCLBEGEDITSTMT
PCLEDITSTMT
PCLEXECEDITSTM
PCLENDEDITSTMT
PCLRELEDITSTMT
PCLEDITDELSTMT
PCLEDITINSSTMT
PCLEDITUPDSTMT
PCLBEGDELMLSTMT
PCLDATASTATUS
PCLBEGEXPORTSTMT
PCLENDEXPORTSTMT
PCL2PCVOTEREQ
PCL2PCVOTETERM
PCL2PCCMMT
PCL2PCABRT
PCL2PCFORGET
PCLSETSESSR
PCLMONSESS
PCLIDENTIFY
PCLABTSESS
PCLSETRESSR
PCLREVALIDATERISTMT
PCLCOMMITSTMT
PCLMONVCONFIG
PCLMONPCONFIG
PCLMONVSUMMARY
PCLMONPSUMMARY
PCLMONVRES
PCLMONPRES
PCLCTRIGSTMT
(34)
(35)
(36)
(37)
(38)
(39)
(40)
(41)
(42)
(43)
(44)
(45)
(46)
(47)
(48)
(49)
(50)
(51)
(52)
(53)
(54)
(55)
(56)
(57)
(58)
(59)
(60)
(61)
(62)
(63)
(64)
(65)
(66)
(67)
(68)
(69)
(70)
(71)
(74)
(75)
(76)
(77)
(78)
(79)
(80)
(83)
(84)
(85)
(86)
(87)
(89)
(90)
(91)
(92)
(93)
(94)
(95)
(96)
(97)
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
2PC vote request.
2PC vote and terminate.
2PC commit request.
2PC abort request.
Vote request yes/done
Set Session Rate
Monitor Session
Identify
Abort Session
Set Resource Rate
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
/*
/*
/*
/*
/*
/*
/*
Monitor Virtual Config
Monitor Physical Config
Monitor Virtual Summary
Monitor Physical Summary
Monitor Virtual Resource
Monitor Physical Resource
Create Trigger Statement
*/
*/
*/
*/
*/
*/
*/
Application Programming Reference
Appendix A: Sample PM/API Application
Header File for Sample PMPC Application
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
PCLDTRIGSTMT
PCLRENTRIGSTMT
PCLREPTRIGSTMT
PCLALTTRIGSTMT
PCLRDLSTMT
PCLDROPPROCSTMT
PCLCREATEPROCSTMT
PCLCALLSTMT
PCLRENPROCSTMT
PCLREPPROCSTMT
PCLSETACCT
PCLHULSTMT
PCLMONSQL
PCLMONVER
PCLBEGINDBQLSTMT
PCLENDDBQLSTMT
PCLCREROLESTMT
PCLDRPROLESTMT
PCLGRANTROLESTMT
PCLREVOKEROLESTMT
PCLCREPROFILESTMT
PCLMODPROFILESTMT
PCLDRPPROFILESTMT
PCLSETROLESTMT
PCLCREUDFSTMT
PCLRPLCUDFSTMT
PCLDROPUDFSTMT
PCLALTERUDFSTMT
PCLRENUDFSTMT
PCLMRGMIXEDSTMT
PCLMRGUPDSTMT
PCLMRGINSSTMT
PCLALTERPROCSTMT
PCLTWMSTATSSTMT
PCLTWMPERFGROUPSSTMT
PCLCREUDTSTMT
PCLDROPUDTSTMT
PCLALTERUDTSTMT
PCLRPLCUDTSTMT
PCLCREUDMSTMT
PCLALTERUDMSTMT
PCLRPLCUDMSTMT
PCLCRECASTSTMT
PCLRPLCCASTSTMT
PCLDROPCASTSTMT
PCLCREORDSTMT
PCLRPLCORDSTMT
PCLDROPORDSTMT
PCLCREXFORMSTMT
PCLRPLCXFORMSTMT
PCLDROPXFORMSTMT
PCLCREAUTHSTMT
PCLDRPAUTHSTMT
PCLCREREPGRPSTMT
PCLALTREPGRPSTMT
PCLDRPREPGRPSTMT
PCLTWMDELRQSTCHGSTM
PCLTWMSUMMARYSTMT
Application Programming Reference
(98)
(99)
(100)
(101)
(102)
(103)
(104)
(105)
(106)
(107)
(108)
(109)
(110)
(111)
(112)
(113)
(114)
(115)
(116)
(117)
(118)
(119)
(120)
(121)
(122)
(123)
(124)
(125)
(126)
(127)
(128)
(129)
(130)
(132)
(133)
(134)
(135)
(136)
(137)
(138)
(139)
(140)
(141)
(142)
(143)
(144)
(145)
(146)
(147)
(148)
(149)
(150)
(151)
(152)
(153)
(154)
(155)
(156)
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
Drop
Trigger Statement
Rename Trigger Statement
Rename Trigger Statement
Alter Trigger Statement
Replication statement
DROP PROCEDURE SQL
CREATE PROCEDURE SQL
CALL SQL
RENAME PROCEDURE SQL
REPLACE PROCEDURE SQL
Set Session Account
Arcmain Lock Request
MONITOR SQL
Monitor Version
Begin DBQL
End DBQL
Create Role SQL
Drop Role SQL
Grant Role SQL
Revoke Role SQL
Create Profile SQL
Modify Profile SQL
Drop Profile SQL
Set Role SQL
Create UDF stmt
Replace UDF stmt
Drop UDF stmt
Alter UDF stmt
Rename UDF stmt
Mixture of upd & ins
Upds and no ins
Ins and no upds
ALTER PROCEDURE SQL
TDQM Statistics
TDQM get Perf Groups
Create UDT stmt
Drop UDT stmt
Alter UDT stmt
Replace UDT stmt
Create UDM stmt
Alter UDM stmt
Replace UDM stmt
Create Cast stmt
Replace Cast stmt
Drop Cast stmt
Create Ordering stmt
Replace Ordering stmt
Drop Ordering stmt
Create Transform stmt
Replace Transform stmt
Drop Transform stmt
Create Auth stmt
Drop Auth Stmt
Create Replication Group
Alter Replication Group
Drop
Replication Group
TDQM Delay Request Change
TDQM get Summary
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
427
Appendix A: Sample PM/API Application
Header File for Sample PMPC Application
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
PCLTWMDYNBUILDSTMT
PCLTWMLISTWDSTMT
PCLSETSESISOLVLSTMT
PCLINITIDXANALYSIS
PCLRPLCAUTHSTMT
PCLSETQBANDSTMT
PCLLOGARCONSTMT
PCLLOGARCOFFSTMT
PCLMONQUERYBANDSTMT
PCLLOGARCONSTMT
PCLLOGARCOFFSTMT
PCLCRECORRSTMT
PCLREPCORRSTMT
PCLDRPCORRSTMT
PCLALTCORRSTMT
PCLUSEREVENTCONTROLSTMT
PCLEVENTSTATUSSTMT
PCLMONAWTRES
PCLSPDYNRESULTSET
(160)
(161)
(162)
(163)
(164)
(165)
(166)
(167)
(168)
(166)
(167)
(169)
(170)
(171)
(172)
(173)
(174)
(175)
(176)
#define MONVERSION3
#define MONVERSION4
3
4
#define MONVERSION
MONVERSION4
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
TDWM Dynamic Build
TDWM LIST WD
Set Session Isolation Level
Initiate Index Analysis
Replace Auth stmt
Set QUERY_BAND stmt
LOGGING ONLINE ARCHIVE ON
LOGGING ONLINE ARCHIVE OFF
MONITOR QUERYBAND
LOGGING ONLINE ARCHIVE ON
LOGGING ONLINE ARCHIVE OFF
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
/*
/*
/*
/*
USER EVENT CONTROL
EVENT STATUS
MONITOR AWT RESOURCE
SP Dynamic Result Set
*/
*/
*/
*/
#define
#define
#define
#define
#define
#define
#define
#define
#define
CONNECTED
0
NOT_CONNECTED 1
OK
0
STOP
1
NOT_OK
-1
MAXLOGONSIZE 100
MAXCOMMANDSIZE 50
MAXNAME 30
SYSMAXRECSIZE
64000
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
ABORTSESTXT "ABORT SESSION;"
SETSESSACCTTXT "SET SESSION ACCOUNT;"
MONSESSTXT "MONITOR SESSION;"
MONSQLTXT "MONITOR SQL;"
TDWMPERFGROUPSTXT "TDWM PERFGROUPS;"
TDWMSTATISTICSTXT "TDWM STATISTICS;"
MONVERTXT "MONITOR VERSION;"
SETSESSTXT "SET SESSION RATE;"
SETRESTXT "SET RESOURCE RATE;"
MONPHYSUMTXT "MONITOR PHYSICAL SUMMARY;"
MONVIRSUMTXT "MONITOR VIRTUAL SUMMARY;"
MONVIRRESTXT "MONITOR VIRTUAL RESOURCE;"
MONPHYRESTXT "MONITOR PHYSICAL RESOURCE;"
MONVIRCONTXT "MONITOR VIRTUAL CONFIG;"
MONPHYCONTXT "MONITOR PHYSICAL CONFIG;"
IDENTSESTXT "IDENTIFY SESSION;"
IDENTDBTXT "IDENTIFY DATABASE;"
IDENTTABLETXT "IDENTIFY TABLE;"
IDENTUSERTXT "IDENTIFY USER;"
HELPTXT "HELP;"
428
Application Programming Reference
Appendix A: Sample PM/API Application
Header File for Sample PMPC Application
typedef
typedef
typedef
typedef
short SysInt32[2];
double fltreal64_t;
unsigned short tosprocnum_t;
short Integer;
typedef enum Request_t
{
ABORTSESSREQ,
SETSESSACCTREQ,
MONSESSREQ,
MONSQLREQ,
TDWMPERFGROUPSREQ,
TDWMSTATISTICSREQ,
MONVERREQ,
MONPHYSUM,
MONVIRSUM,
MONVIRRES,
MONPHYRES,
MONVIRCON,
MONPHYCON,
SETSESSREQ,
SETRESREQ,
IDENTSESREQ,
IDENTDBREQ,
IDENTTABLEREQ,
IDENTUSERREQ
} Request_t;
#pragma pack(1)
/* Input parcel structure for PMPC requests */
typedef struct
{
char indicbyte;
Int16 version;
} monheader_t;
typedef struct
{
monheader_t monheader;
Int16 hostid;
Int32 session;
char user[30];
char listsess;
char logoffsess;
char override;
} abortsess_t;
typedef struct
{
monheader_t monheader;
Int16 hostid;
Int32 session;
char acct[30];
char entiresess;
} setsessacct_t;
Application Programming Reference
429
Appendix A: Sample PM/API Application
Header File for Sample PMPC Application
typedef struct
{
monheader_t monheader;
Int16 hostid;
Int32 session;
char user[30];
} monsess_t;
typedef struct
{
monheader_t monheader;
Int16 hostid;
Int32 session;
} monsql_t;
typedef struct
{
monheader_t monheader;
Int16 samplerate;
char LocalChange;
char VirtualChange;
} setrate_t;
typedef struct
{
Int16 hostid;
Int32 sessionno;
} identses_t;
typedef struct
{
monheader_t monheader;
union
{
Int32 objid;
identses_t identses;
} UU;
} identify_t;
/* Output record parcel structures */
typedef struct
{
Int16
HostId;
/* Logical Host Identifier */
char
UserName[30]; /* User (database) Name of this session */
SysInt32 SessionNo;
/* Session Number of session */
char
AbortStatus; /* Status of aborted session */
} MonAbtSes_t;
typedef struct
{
Int16 HostId; /* Logical Host Identifier */
Int16 LogonProcId; /* Processor number session logged on to */
Int16 RunProcId; /* Procnum the session initiates requests to */
Int32 SessionNo; /* Session Number of session */
char UserName[30]; /* User (database) Name of this session */
char UserAccount[30]; /* Acct name that this User logged in with */
Int32 UserID; /* User (database) Identifier for this session */
Int32 LSN; /* Logon Sequence Number */
double LogonTime; /* Logon Time for this session */
430
Application Programming Reference
Appendix A: Sample PM/API Application
Header File for Sample PMPC Application
Int32 LogonDate; /* Logon Date */
char PartName[16]; /* Session Partition Name this session is associated with */
char Priority[2]; /* DBC run priority (Low, Medium, High, Rush) */
char PEState[18]; /* Current state of this session in the PE */
double PECPUSec; /* Current elapsed cpu usage in PE for sess */
double XactCount; /* Number of transactions processed by a DBC SQL session */
double ReqCount; /* Number of requests processed by a session */
double ReqCacheHits; /* Number of Request Cache uses inDBC/SQL sess */
char AMPState[18]; /* Current state of associated session in AMP processors */
double AMPCPUSec; /* Current elapsed cpu usage in AMP ( TOTAL ) */
double AMPIO; /* Current Total Logical I/O count for associated session */
double Delta_AMPSpool; /* Total Spool space change for the associated session */
Int16 Blk_1_HostId; /* Logical HostId of a session causing block */
Int32 Blk_1_SessNo; /* Session Number of a session causing block */
Int32 Blk_1_UserID; /* User Identifier of a Host Utility Job causing block */
char Blk_1_LMode; /* Mode (Severity) of lock involved in causing a block */
char Blk_1_OType; /* Type (Database/Table/Row Hash) of object being locked */
Int32 Blk_1_ObjDBId; /* DB Identifier of object being locked */
Int32 Blk_1_ObjTId; /* TBID (If applicable) of object being locked */
char Blk_1_Status;
Int16 Blk_2_HostId;
Int32 Blk_2_SessNo;
Int32 Blk_2_UserID;
char Blk_2_LMode;
char Blk_2_OType;
Int32 Blk_2_ObjDBId;
Int32 Blk_2_ObjTId;
char Blk_2_Status;
Int16 Blk_3_HostId;
Int32 Blk_3_SessNo;
Int32 Blk_3_UserID;
char Blk_3_LMode;
char Blk_3_OType;
Int32 Blk_3_ObjDBId;
Int32 Blk_3_ObjTId;
char Blk_3_Status;
char MoreBlockers; /* Indicates there are more lock conflicts */
Int16 LogonSourceLen; /* Logon source length (Variable Length) */
char LogonSource[128];/* Logon source info (Variable Length) */
} MonSesRec2_t;
typedef struct
{
double TempSpaceUsage; /* Temporary space usage for the associated session */
fltreal64_t HotAmp1CPU;
fltreal64_t HotAmp2CPU;
fltreal64_t HotAmp3CPU;
fltreal64_t HotAmp1IO;
fltreal64_t HotAmp2IO;
fltreal64_t HotAmp3IO;
Word HotAmp1CPUId;
Word HotAmp2CPUId;
Word HotAmp3CPUId;
Word HotAmp1IOId;
Word HotAmp2IOId;
Word HotAmp3IOId;
fltreal64_t LowAmp1CPU;
fltreal64_t LowAmp2CPU;
fltreal64_t LowAmp3CPU;
Application Programming Reference
431
Appendix A: Sample PM/API Application
Header File for Sample PMPC Application
fltreal64_t LowAmp1IO;
fltreal64_t LowAmp2IO;
fltreal64_t LowAmp3IO;
Word LowAmp1CPUId;
Word LowAmp2CPUId;
Word LowAmp3CPUId;
Word LowAmp1IOId;
Word LowAmp2IOId;
Word LowAmp3IOId;
Word AmpCount;
fltreal64_t AvgAmpCPUSec;
fltreal64_t AvgAmpIOCnt;
} MonSesRecV3_t;
typedef struct
{
double ReqStartTime;
Int32 ReqStartDate;
fltreal64_t ReqCPU;
fltreal64_t ReqIO;
} MonSesRecV4_t;
typedef struct
{
Int32 ReqNo;
Int32 WlcId;
Int16 DontReclassifyFlag;
} MonSesRecV5_t;
typedef struct
{
fltreal64_t
fltreal64_t
fltreal64_t
fltreal64_t
tosprocnum_t
fltreal64_t
tosprocnum_t
fltreal64_t
tosprocnum_t
fltreal64_t
tosprocnum_t
fltreal64_t
tosprocnum_t
fltreal64_t
tosprocnum_t
fltreal64_t
char
char
Integer
Integer
char
char
} MonPhySum_t;
typedef struct
{
fltreal64_t
432
AvgCPU;
AvgDisk;
AvgDiskIO;
HighCPUUse;
HighCPUProcId;
LowCPUUse;
LowCPUProcId;
HighDisk;
HighDiskProcId;
LowDisk;
LowDiskProcId;
HighDiskIO;
HighDiskIOProcId;
LowDiskIO;
LowDiskIOProcId;
NetUse;
NetAUp;
NetBUp;
ResLogging;
ResMonitor;
Release[29];
Version[32];
AMPAvgCPU;
Application Programming Reference
Appendix A: Sample PM/API Application
Header File for Sample PMPC Application
fltreal64_t
fltreal64_t
fltreal64_t
tosprocnum_t
tosprocnum_t
fltreal64_t
tosprocnum_t
tosprocnum_t
fltreal64_t
tosprocnum_t
tosprocnum_t
fltreal64_t
tosprocnum_t
tosprocnum_t
fltreal64_t
tosprocnum_t
tosprocnum_t
fltreal64_t
tosprocnum_t
tosprocnum_t
fltreal64_t
fltreal64_t
tosprocnum_t
tosprocnum_t
fltreal64_t
tosprocnum_t
tosprocnum_t
fltreal64_t
Integer
Integer
Integer
Integer
char
char
} MonVirSum_t;
typedef struct
{
char
char
Int16
} MonVirRes1_t;
typedef struct
{
char
char
char
} MonConfig_t;
typedef struct
{
Integer
Integer
char
Int16
char
Int16
} MonVirConfig_t;
AMPAvgDisk;
AMPAvgDiskIO;
HiCPUAMPUse;
HiCPUAMPNo;
HiCPUAMPProc;
LoCPUAMPUse;
LoCPUAMPNo;
LoCPUAMPProc;
HiDiskAMP;
HiDiskAMPNo;
HiDiskAMPProc;
LoDiskAMP;
LoDiskAMPNo;
LoDiskAMPProc;
HiDiskAMPIO;
HiDiskAMPIONo;
HiDiskAMPIOProc;
LoDiskAMPIO;
LoDiskAMPIONo;
LoDiskAMPIOProc;
PEAvgCPU;
HiCPUPEUse;
HiCPUPENo;
HiCPUPEProc;
LoCPUPEUse;
LoCPUPENo;
LoCPUPEProc;
SessionCount;
SesMonitorSys;
SesMonitorLoc;
ResLogging;
ResMonitor;
Release[29];
Version[32];
NetAUp;
NetBUp;
SampleRate;
NetAUp;
NetBUp;
SystemType[7];
ProcId;
VProcNo;
VprocType[3];
HostId;
Status;
DiskSlice;
Application Programming Reference
433
Appendix A: Sample PM/API Application
Header File for Sample PMPC Application
typedef struct
{
Integer
char
char
Integer
} MonPhyConfig_t;
typedef struct
{
char
Integer
Integer
Integer
fltreal64_t
char
Integer
Integer
fltreal64_t
fltreal64_t
fltreal64_t
fltreal64_t
fltreal64_t
fltreal64_t
fltreal64_t
fltreal64_t
fltreal64_t
fltreal64_t
fltreal64_t
fltreal64_t
fltreal64_t
fltreal64_t
fltreal64_t
} MonVirRes2_t;
typedef struct
{
Integer
Integer
Integer
fltreal64_t
fltreal64_t
fltreal64_t
fltreal64_t
char
fltreal64_t
fltreal64_t
fltreal64_t
fltreal64_t
fltreal64_t
fltreal64_t
fltreal64_t
fltreal64_t
fltreal64_t
fltreal64_t
fltreal64_t
fltreal64_t
fltreal64_t
434
ProcId;
Status;
CpuType[7];
CpuCount;
VprocType[3];
ProcId;
VProcNo;
ClusterNo;
CPUUse;
Status;
SessLogCount;
SessRunCount;
DiskUse;
DiskReads;
DiskWrites;
DiskOutReqAvg;
HostBlockReads;
HostBlockWrites;
MemAllocates;
MemAllocateKB;
PctService;
PctAMPWT;
PctParser;
PctDispatcher;
NetReads;
NetWrites;
NVMemAllocSegs;
ProcId;
AmpCount;
PECount;
CPUUse;
PercentKernel;
PercentService;
PercentUser;
Status;
NetAUse;
NetBUse;
DiskUse;
CICUse;
DiskReads;
DiskWrites;
DiskOutReqAvg;
HostBlockReads;
HostBlockWrites;
SwapReads;
SwapWrites;
SwapDrops;
MemAllocates;
Application Programming Reference
Appendix A: Sample PM/API Application
Header File for Sample PMPC Application
fltreal64_t
fltreal64_t
fltreal64_t
fltreal64_t
fltreal64_t
} MonPhyRes2_t;
MemAllocateKB;
MemFailures;
MemAgings;
NetReads;
NetWrites;
typedef struct
{
Integer
NumOfSteps;
Integer
CurStepBegNum;
Integer
CurStepEndNum;
} MonSqlStepInfo_t;
typedef struct
{
fltreal64_t
EstRowCount;
fltreal64_t
ActRowCount;
fltreal64_t
EstElapTime;
fltreal64_t
ActElapTime;
} MonSqlStepStats_t;
typedef struct
{
char
Int16
} SetSessAcct_t;
OldAcct[MAXNAME] ;
ErrorCode;
typedef struct ERROR_FAIL_Type {
Word
StatementNo;
Word
Info;
Word
Code;
Word
Length;
char
Msg[255];
} Error_Fail_t;
#define MAXFIELDS 100
typedef struct InfoPairs
{
short FType;
short FSize;
} InfoPairs;
typedef struct DataInfo_t
{
short field_count;
InfoPairs FieldData[MAXFIELDS];
} DataInfo_t;
#pragma pack()
#endif
Application Programming Reference
435
Appendix A: Sample PM/API Application
Header File for Sample PMPC Application
436
Application Programming Reference
Combination PEState and
AMPState Response
Values for MONITOR SESSION
APPENDIX B
This appendix lists all the possible combinations of the PEState and AMPState response values
returned from a MONITOR SESSION request and the resulting effect of each combination on
session states. For a detailed description of each of these response values, see “MONITOR
SESSION” on page 101.
Sample MONITOR SESSION Responses
As described in the table below, the MONITOR SESSION request returns both the PEState
(A) and AMPState (B) response values. A client performance monitoring application (C)
interprets the meaning of the PEState and AMPState combination, which is displayed as the
session state in the client application.
You can view different session states in Teradata Viewpoint and filter for the types of sessions
you wish to view.
Note: The session state is not returned by any PM/API CLIv2 request. It is interpreted by the
client application.
IF A is…
AND B is…
THEN C displays…
HOST-RESTART
any AMP state
HOST-RESTART
ABORTING
ABORTING
ABORTING
ABORTING
ACTIVE
ABORTING
ABORTING
BLOCKED
ABORTING
ABORTING
IDLE
ABORTING
ABORTING
UNKNOWN
ABORTING
PARSING-WAIT
ABORTING
ABORTING
PARSING-WAIT
BLOCKED
BLOCKED
PARSING-WAIT
ACTIVE
PARSING
PARSING-WAIT
IDLE
PARSING
PARSING-WAIT
UNKNOWN
PARSING
Application Programming Reference
437
Appendix B: Combination PEState and AMPState Response Values for MONITOR SESSION
Sample MONITOR SESSION Responses
438
IF A is…
AND B is…
THEN C displays…
PARSING
ABORTING
ABORTING
PARSING
BLOCKED
BLOCKED
PARSING
ACTIVE
PARSING
PARSING
IDLE
PARSING
PARSING
UNKNOWN
PARSING
DISPATCHING
ABORTING
ABORTING
DISPATCHING
BLOCKED
BLOCKED
DISPATCHING
ACTIVE
ACTIVE
DISPATCHING
IDLE
ACTIVE
DISPATCHING
UNKNOWN
ACTIVE
ELICIT CLIENT DATA
ABORTING
ABORTING
ELICIT CLIENT DATA
BLOCKED
BLOCKED
ELICIT CLIENT DATA
ACTIVE
ACTIVE
ELICIT CLIENT DATA
IDLE
ACTIVE
ELICIT CLIENT DATA
UNKNOWN
ACTIVE
RESPONSE
ABORTING
ABORTING
RESPONSE
BLOCKED
BLOCKED
RESPONSE
ACTIVE
RESPONSE
RESPONSE
IDLE
RESPONSE
RESPONSE
UNKNOWN
RESPONSE
ACTIVE
ABORTING
ABORTING
ACTIVE
BLOCKED
BLOCKED
ACTIVE
ACTIVE
ACTIVE
ACTIVE
IDLE
ACTIVE
ACTIVE
UNKNOWN
ACTIVE
IDLE: IN-DOUBT
ABORTING
UNKNOWN
IDLE: IN-DOUBT
BLOCKED
UNKNOWN
IDLE: IN-DOUBT
ACTIVE
UNKNOWN
IDLE: IN-DOUBT
IDLE
UNKNOWN
IDLE: IN-DOUBT
UNKNOWN
UNKNOWN
IDLE
ABORTING
IDLE
Application Programming Reference
Appendix B: Combination PEState and AMPState Response Values for MONITOR SESSION
Sample MONITOR SESSION Responses
IF A is…
AND B is…
THEN C displays…
IDLE
BLOCKED
IDLE
IDLE
ACTIVE
IDLE
IDLE
IDLE
IDLE
IDLE
UNKNOWN
IDLE
DELAYED
any AMP state
DELAYED
SESDELAYED
any AMP state
SESDELAYED
QTDELAYED
any AMP state
QTDELAYED
BLOCKED
IDLE
BLOCKED
Note: A BLOCKED session state
in monitor partition session
means some background activity
is in progress and the last request
is on hold until this background
activity is completed. Database
locks are not directly involved in
BLOCKED monitor partition
sessions. One example of
background activity that could
place a request on hold is when
the monitor partition session is
aborted externally and the
session is processing this
asynchronous abort request that
came in internally.
Application Programming Reference
439
Appendix B: Combination PEState and AMPState Response Values for MONITOR SESSION
Sample MONITOR SESSION Responses
440
Application Programming Reference
Glossary
2PC
Two-Phase Commit
AMP
Access Module Processor
API Application Program Interface
ARC
Teradata Archive/Recovery Utility
BTEQ Basic Teradata Query
CLI Call Level Interface
CLIv2
Call Level Interface, Version 2
DBW
Database Window
DSS
FE
HSI
Decision Support System
Field Engineer
Host System Interface
HUT
Host Utility
I/O Input/Output
LAN
Local Area Network
LSN Logon Sequence Number
MPP Massively Parallel Processing
OLTP Online Transaction Processing
PDE
PE
Parallel Database Extensions
Parsing Engine
PMPC
Performance Monitor and Production Control
ResUsage Resource Usage
RSS Resource Sampling Subsystem. The RSS provides a method to gather statistics from
across the Teradata Database system, and provides the ability to access the statistics through
an API. Resource usage uses the RSS data from the RSS API to log data to the selected resource
usage tables.
SLES
SLG
SUSE Linux Enterprise Server
Service Level Goals
Application Programming Reference
441
Glossary
SMF
System Management Facility
SMP
Symmetric Multi-Processing
Tactical Workload Management Method This workload yields the fastest available response
time and executes at the highest tier, preempting all resource needs of other tiers. This method
is well suited for critical, short-running queries that require fast response times. For more
information, see Teradata Viewpoint User Guide.
TDP
Teradata Director Program
TDWM
Teradata Dynamic Workload Management
Teradata ASM Teradata Active System Management. Teradata ASM is a set of products,
including system tables and logs, that interact with each other and a common data source. It
helps manage the system automatically and reduces the effort required by database
administrators, application developers, and support personnel. Teradata ASM can improve
and optimize your workload management and performance. It can also improve response
times and ensure more consistent response times for critical work.
Timeshare Workload Management Method This workload can be assigned to one of four
stepped access levels, Top, High, Medium, or Low. The higher access levels are given larger
access rates than the lower levels. For example, an SQL request assigned to a Timeshare WD
with a Top access level, which has an access rate of 8, would receive eight times the amount of
resources than an SQL request assigned to a Low access level.
Timeshare workloads are assigned resources remaining after all allocations have been made
for tactical and workload share workloads. For more information, see Teradata Viewpoint User
Guide.
TSR
vproc
Tequel Start Request
Virtual Processor
Workload Share Management Method This workload is assigned a proportion of the
resources that are available after allocations have been made for tactical workloads. The
percentage of resources is divided equally between all requests running in the WD. For
example, if the WD share is 5% and there are 5 SQL requests, each SQL request will get 1% of
the share resources. For more information, see Teradata Viewpoint User Guide.
WQM
442
Workload Query Manager
Application Programming Reference
Index
A
Abort Count response value 338
Abort processing, PM/APIs 38
ABORT SESSION request, PM/API 42, 50
2PC 51
and how it is different 52
and MONITOR PHYSICAL RESOURCE 92
and MONITOR SESSION 58, 126
BTEQ sessions, aborting 54
DBC.SW_Event_Log table 53
privileges 53
sample input 57
sample output 58
statement type 2 57
utility jobs, aborting 55
AbortCnt result row 386
Aborted sessions 59
AbortListSessions function 195
example of 197
AbortSessions function 198
examples of 199
AbortStatus response value 57
AbortStatus result row 197
ActElapsedTime result row 261
ActElapTime response value 132
Active Date response value 303
Active Delayed Count response value 338
Active Query Count response value 338
Active result row 390
Active Time response value 303
ActiveQueryCnt result row 385, 386
ActRowCount response value 132
ActRowCount result row 261
AGId response value 171
AGId result row 282
ALTER TABLE statement, SQL 53
AMPAvgCPU response value 161
AMPAvgCPU result row 276
AMPAvgDisk response value 161
AMPAvgDisk result row 276
AMPAvgDiskIO response value 161
AMPAvgDiskIO result row 276
AMPCount response value 87
AmpCount result row 223, 231, 252
AMPCPUSec response value 113
AMPCPUSec result row 216, 245
Application Programming Reference
AMPIO response value 113
AMPIO result row 216, 245
AMPNodes response value 170
AMPState response value 113
AMPState result row 216, 245
APIs
categories of 15
query band 393
System PMPC 47
Teradata Dynamic Workload Management 297
Application Programming Interfaces. See APIs
Application, PM/API sample 411
Arrivals response value 337
Arrivals result row 385
AvailableAWTs response value 74
AvailableAWTs result row 205
Average CPU Time response value 337
Average Delay Time response value 337
Average Response Time response value 337
AvgAmpCPUSec response value 122
AvgAmpCPUSec result row 223, 252
AvgAmpIOCnt response value 122
AvgAmpIOCnt result row 223, 252
AvgCPU response value 95
AvgCPU result row 236
AvgCPUTime result row 385
AvgDelayTime result row 385
AvgDisk response value 95
AvgDisk result row 236
AvgDiskIO response value 95
AvgDiskIO result row 236
AvgRespTime result row 385
B
Blk_x_HostId response value 114
Blk_x_LMode response value 116
Blk_x_OType response value 4, 116
Blk_x_SessNo response value 115
Blk_x_Status response value 117
Blk_x_UserID response value 115
BlkxHostId result row 217, 246
BlkxLmode result row 218, 247
BlkxObjDBID result row 219, 248
BlkxObjTID result row 219, 248
BlkxOtype result row 219, 248
BlkxSessNo result row 217, 246
443
Index
BlkxStatus result row 220, 249
BlkxUserId result row 218, 247
Blocked sessions 59
BlockingCnt result row 370
BTEQ sessions, aborting 54
Buffer allocation 38
C
Call-Level Interface version 2. See CLIv2 requests
Category result row 409
Classification Mode response value 123
CLIv2 requests, requirements for 18
ClusterNo result row 270
Collection rate 43, 45
CollectionDate response value 72, 86, 98, 108, 149, 165, 170
CollectionInterval response value 107
CollectionSeqNum response value 107
CollectionTime response value 72, 86, 98, 108, 149, 165, 170
Completions response value 337
Completions result row 385
Confidence response value 132
Confidence result row 261
Config ID response value 300
Config Name response value 301
Configuration ID response value 322
CPUCount response value 80
CPUCount result row 228
CPUDecayLevel response value 123
CPURunDelay response value 175
CPURunDelay result row 286
CPUType response value 80
CPUType result row 228
CPUUse response value 87
CPUUse result row 150, 231, 271
CPUUserPct response value 172
CPUUserPct result row 284
CurLev1StepNum response value 131
CurLev2StepNum response value 131
CurLvl1StepNo result row 259
CurLvl2StepNo result row 259
CurrentRedriveParticipation response value 124
D
Date response value 301, 305
DBC.Dbase table 63
DBC.ResUsage table 179, 290
DBC.SessionTbl table 63, 184, 292
DBC.Software_Event_LogV view 40, 53, 78, 140, 180, 188
184
DBC.TVM table 63
DBCAREA
response mode options 37
DBQLFlushRate response value 108
444
DecayLevel1CPU response value 176
DecayLevel1CPU result row 287
DecayLevel1IO response value 176
DecayLevel1IO result row 286
DecayLevel2CPU response value 176
DecayLevel2CPU result row 287
DecayLevel2IO response value 176
DecayLevel2IO result row 286
Default_Value result row 409
Delayed Count response value 337
Delayed result row 390
DelayedCnt result row 385
Description result row 409
DiskOutReqAvg response value 89
DiskOutReqAvg result row 152, 232, 272
DiskReads response value 88
DiskReads result row 151, 232, 272
DiskSlice response value 142
DiskSlice result row 268
DiskUse response value 88
DiskUse result row 151, 232, 272
DiskWrites response value 89
DiskWrites result row 152, 232, 272
DontReclassifyFlag result row 224, 253
DQMsgCount response value 75
DQMsgCount result row 205
Due To Duration response value 303
DueToDuration result row 362
Dynamic data 43
E
Enabled Flag response value 322
EnabledFlag result row 376
Error Count response value 338
Error messages 42, 48
ErrorCnt result row 386
EstElapsedTime result row 261
EstElapTime response value 132
EstRowCount response value 132
EstRowCount result row 261
Event Active Time response value 302
EVENT STATUS request, PM/API 299
statement type 1 300
statement type 2 301
statement type 3 304
Event_Category result row 375
EventActiveDate response value 301
EventActiveDate result row 361
EventActiveTime result row 361
EventId response value 301
EventId result row 361
EventKind result row 359
EventStatus response value 301
Application Programming Reference
Index
EventStatus result row 361
Examples of PMPC applications 24
Exception Count response value 337
ExceptionCnt result row 385
ExceptionInterval response value 108
ExpActiveDate result row 361
ExpActiveTime result row 361
Expression Active Date response value 302
Expression Active Time response value 302
Expression Status response value 302
ExpressionId response value 302
ExpressionId result row 361
ExpressionStatus result row 361
External stored procedures
GetQueryBandSP 402
GetQueryBandValue 403
GetQueryBandValueSp 404
TDWMApply 352
TDWMEventControl 356
TDWMRuleControl 382
TDWMSetLimits 383
ExtraField1 result row 285
ExtraField2 result row 285
ExtraField3 result row 286
ExtraField4 result row 286
F
FCVprocIdx result row 210
Filter_Category result row 375
Flow Control response value 73
Flow Control x VprocId response value 74
FlowControl result row 208
FunctionBitmap response value 137
G
GetPSFVersion function 349
example of 349
GetQueryBand function 399
example of 399
GetQueryBandPairs function 400
examples of 401
GetQueryBandSP procedure 402
example of 402
GetQueryBandValue procedure 403
examples of 404
GetQueryBandValueSP procedure 404
example of 405
Global session. See SesMonitorSys
GRANT MONTOR command, SQL 42
Group data fields 109
Application Programming Reference
H
HiCPUAMPNo response value 161
HiCPUAMPNo result row 277
HiCPUAMPProc response value 161
HiCPUAMPProc result row 277
HiCPUAMPUse response value 161
HiCPUAMPUse result row 276
HiCPUPENo response value 163
HiCPUPENo result row 278
HiCPUPEProc response value 163
HiCPUPEProc result row 278
HiCPUPEUse response value 163
HiCPUPEUse result row 278
HiDiskAMP response value 162
HiDiskAMP result row 276
HiDiskAMPIO response value 162
HiDiskAMPIO result row 276
HiDiskAMPIONo response value 163
HiDiskAMPIONo result row 277
HiDiskAMPIOProc response value 163
HiDiskAMPIOProc result row 277
HiDiskAMPNo response value 162
HiDiskAMPNo result row 277
HiDiskAMPProc response value 162
HiDiskAMPProc result row 277
High AMP 1 In-Use Count response value 73
High AMP 1 VprocId response value 73
High AMP 2 In-Use Count response value 73
High AMP 2 VprocId response value 73
High AMP 3 In-Use Count response value 73
High AMP 3 VprocId response value 73
High AMP 4 In-Use Count response value 73
High AMP 4 VprocId response value 73
High AMP 5 In-Use Count response value 73
High AMP 5 VprocId response value 73
HighAMP1InUseCount result row 208
HighAMP1VprocId result row 208
HighAMP2InUseCount result row 209
HighAMP2VprocId result row 209
HighAMP3InUseCount result row 209
HighAMP3VprocId result row 209
HighAMP4InUseCount result row 209
HighAMP4VprocId result row 209
HighAMP5InUseCount result row 209
HighAMP5VprocId result row 209
HighCPUProcId response value 95
HighCPUProcId result row 236
HighCPUUse response value 95
HighCPUUse result row 236
HighDisk response value 96
HighDisk result row 236
HighDiskIO response value 96
HighDiskIO result row 236
445
Index
HighDiskIOProcId response value 96
HighDiskIOProcId result row 237
HighDiskProcId response value 96
HighDiskProcId result row 236
HostBlockReads response value 89
HostBlockWrites response value 89
HostId response value 57, 109, 142
HostId result row 196, 213, 243, 259, 261, 264, 268, 370, 373
HostId/ClusterNo result row 150
HotAmp1CPU response value 118
HotAmp1CPU result row 220, 249
HotAmp1CPUId response value 119
HotAmp1CPUId result row 221, 250
HotAMP1IO response value 119
HotAmp1IO result row 221, 250
HotAmp1IOId response value 120
HotAmp1IOId result row 221, 250
HotAmp2CPU response value 119
HotAmp2CPU result row 221, 250
HotAmp2CPUId response value 119
HotAmp2CPUId result row 221, 250
HotAMP2IO response value 119
HotAmp2IO result row 221, 250
HotAmp2IOId response value 120
HotAmp2IOId result row 222, 250
HotAmp3CPU response value 119
HotAmp3CPU result row 221, 250
HotAmp3CPUId response value 119
HotAmp3CPUId result row 221, 250
HotAMP3IO response value 119
HotAmp3IO result row 221, 250
HotAmp3IOId response value 120
HotAmp3IOId result row 222, 251
HstBlkRds result row 152, 233, 273
HstBlkWrts result row 152, 233, 273
example of 204
Idle Session Logoff 25
Indicator mode 37
Interfaces
CLIv2 47, 297, 393
SQL 47, 297, 393
Internal session, handling 105
Interval 1 Count response value 72
Interval 2 Count response value 72
Interval 3 Count response value 72
Interval 4 Count response value 73
IntervalCount1 result row 208
IntervalCount2 result row 208
IntervalCount3 result row 208
IntervalCount4 result row 208
InUseAWTs response value 74
InUseAWTs result row 205
IOCompleted response value 176
IOCompleted result row 286
IOCompletedKB response value 176
IOCompletedKB result row 286
IOCriticalSubmitted response value 176
IOCriticalSubmitted result row 286
IOCriticalSubmittedKB response value 176
IOCriticalSubmittedKB result row 286
IODecayLevel response value 123
IODelay response value 173
IODelay result row 284, 285
IODelayTime response value 174
IOSubmitted response value 175
IOSubmitted result row 286
IOSubmittedKB response value 175
IOSubmittedKB result row 286
J
I
Job control support application examples 24
Id response value 303
IDENTIFY request, PM/API 36, 61
and MONITOR SESSION 66, 126
IDENTIFY DATABASE 62
IDENTIFY SESSION 62
IDENTIFY TABLE 63
IDENTIFY USER 63
sample input 64
sample output 65
IdentifyDatabase function 201
example of 201
IdentifySession function 202
example of 202
IdentifyTable function 203
example of 203
IdentifyUser function 204
K
446
Keywords/reserved words 42
L
Local session. See SesMonitorLoc
Locks, monitoring 66, 126
LoCPUAMPNo response value 162
LoCPUAMPNo result row 277
LoCPUAMPProc response value 162
LoCPUAMPProc result row 278
LoCPUAMPUse response value 162
LoCPUAMPUse result row 277
LoCPUPENo response value 164
LoCPUPENo result row 278
LoCPUPEProc response value 164
Application Programming Reference
Index
LoCPUPEProc result row 279
LoCPUPEUse response value 163
LoCPUPEUse result row 278
LoDiskAMP response value 162
LoDiskAMP result row 277
LoDiskAMPIO response value 163
LoDiskAMPIO result row 277
LoDiskAMPIONo response value 163
LoDiskAMPIONo result row 278
LoDiskAMPIOProc response value 163
LoDiskAMPIOProc result row 278
LoDiskAMPNo response value 162
LoDiskAMPNo result row 278
LoDiskAMPProc response value 162
LoDiskAMPProc result row 278
Logging rate 45
LogicalRead response value 174
LogicalRead result row 285
LogicalReadKB response value 174
LogicalReadKB result row 285
LogicalWrite response value 175
LogicalWrite result row 285
LogicalWriteKB response value 175
LogicalWriteKB result row 285
LogonDate response value 110
LogonPENo response value 109
LogonPENo result row 213, 243
LogonSource response value 118
LogonSource result row 220, 249
LogonTime response value 110
LogonTime result row 214, 243
Low AMP 1 In-Use Count response value 73
Low AMP 1 VprocId response value 73
Low AMP 2 In-Use Count response value 73
Low AMP 2 VprocId response value 73
Low AMP 3 In-Use Count, response value 74
Low AMP 3 VprocId response value 74
Low AMP 4 In-Use Count response value 74
Low AMP 4 VprocId, response value 74
Low AMP 5 In-Use Count, response value 74
Low AMP 5 VprocId response value 74
LowAmp1CPU response value 120
LowAmp1CPU result row 222, 251
LowAmp1CPUId response value 121
LowAmp1CPUId result row 222, 251
LowAMP1InUseCount result row 209
LowAmp1IO response value 120
LowAmp1IO result row 222, 251
LowAmp1IOId response value 121
LowAmp1IOId result row 223, 252
LowAMP1VprocId result row 209
LowAmp2CPU response value 120
LowAmp2CPU result row 222, 251
LowAmp2CPUId response value 121
Application Programming Reference
LowAmp2CPUId result row 222, 251
LowAMP2InUseCount result row 209
LowAmp2IO response value 120
LowAmp2IO result row 223, 251
LowAmp2IOId response value 121
LowAmp2IOId result row 223, 252
LowAMP2VprocId result row 209
LowAmp3CPU response value 120
LowAmp3CPU result row 222, 251
LowAmp3CPUId response value 121
LowAmp3CPUId result row 222, 251
LowAMP3InUseCount result row 209
LowAmp3IO response value 120
LowAmp3IO result row 223, 251
LowAmp3IOId response value 121
LowAmp3IOId result row 223, 252
LowAMP3VprocId result row 209
LowAMP4InUseCount result row 209
LowAMP4VprocId result row 209
LowAMP5InUseCount result row 209
LowAMP5VprocId result row 209
LowCPUProcId response value 96
LowCPUProcId result row 237
LowCPUUse response value 96
LowCPUUse result row 237
LowDisk response value 96
LowDisk result row 237
LowDiskIO response value 96
LowDiskIO result row 237
LowDiskIOProcId response value 97
LowDiskIOProocId result row 237
LowDiskProcId response value 96
LowDiskProcId result row 237
LSN response value 110
LSN result row 214, 244
M
Max_Len result row 409
MaxCPUTime result row 385
Maximum CPU Time response value 337
Maximum Response Time response value 337
MaxRespTime result row 385
MemAgings response value 90
MemAgings result row 233
MemAllocateKB result row 233
MemAllocates response value 90
MemAllocates result row 233
MemAllocatesKB response value 90
MemFailures response value 90
MemFailures result row 233
Messages, common warning and error 48
Met SLG Count response value 338
MetSLGCnt result row 385
447
Index
MinCPUTime result row 385
Minimum CPU Time response value 337
Minimum Response Time response value 337
MinRespTime result row 385
Mode
indicator or record, setting 36
MONITOR AWT RESOURCE request, PM/API 69
monitor privileges 70
sample input 75
sample output 75
statement type 1 72
statement type 2 72
statement type 3 74
MONITOR PHYSICAL CONFIG request, PM/API 77
monitor privileges 77
sample input 80
sample output 81
MONITOR PHYSICAL RESOURCE request, PM/API 83
monitor privileges 83
sample input 91
sample output 91
versus resource usage data 84
MONITOR PHYSICAL SUMMARY request, PM/API 93
and MONITOR PHYSICAL CONFIG 81, 99
and SET RESOURCE RATE 99
and SET SESSION RATE 99, 166, 193
monitor privileges 93
sample input 98
sample output 98
warning and error messages 99
Monitor privileges
ABORTSESSION 159
MONRESOURCE 159
MONSESSION 159
SETRESRATE 159
SETSESSRATE 159
MONITOR QUERYBAND request, PM/API 395
sample input 397
sample output 397
MONITOR SESSION request, PM/API 101
and ABORT SESSION 58, 126
and IDENTIFY 66, 103, 126
handling internal session blocks 105
monitor privileges 102
processor down 105
response parcel groups 108
sample input 124
sample output 124
session data collection 104
setting up a request 411
unreported session partitions 105
writing a Resource Supervisor 25
writing an Idle Session Logoff 26
MONITOR SQL request, PM/API 128
448
monitor privileges 129
sample input 132
sample output 133
MONITOR VERSION request, PM/API 136
monitor privileges 136
sample input 137
sample output 138
MONITOR VIRTUAL CONFIG request, PM/API 139, 140
monitor privileges 139
sample input 142
sample output 133
MONITOR VIRTUAL RESOURCE request, PM/API 146
and SET RESOURCE RATE 44
monitor privileges 146
sample input 154
sample output 155
warning and error messages 157
MONITOR VIRTUAL SUMMARY request, PM/API 159
monitor privileges 159
sample input 165
sample output 165
warning and error messages 166
MONITOR WD request, PM/API 168
sample input 177
sample output 177
statement type 1 170
statement type 2 170
MonitorAMPLoad function 205
example of 205
MonitorAWTResource function 207
example of 210
MonitorMySessions function 211
example of 225
MonitorPhysicalConfig function 227
example of 228
MonitorPhysicalResource function 230
example of 234
MonitorPhysicalSummary function 235
example of 238
MonitorQueryBand function 406
example of 406
MonitorSession function 240
example of 253
MonitorSessionRate function 256
example of 257
MonitorSQLCurrentStep function 258
example of 259
MonitorSQLSteps function 260
example of 261
MonitorSQLText function 263
example of 264
MonitorSystemPhysicalConfig function 265
example of 266
MonitorVirtualConfig function 267
Application Programming Reference
Index
example of 268
MonitorVirtualResource function 269
example of 274
MonitorVirtualSummary function 275
example of 279
MonitorWD function 281
example of 287
MonitorWDRate function 289
example of 289
MoreBlockers result row 220, 249
MsgCount response value 74
MsgCount result row 205
MSGWORKNEW work type 72
MSGWORKONE work type 72
N
NetAUp response value 86, 90, 97, 141, 149
NetAUp result row 238
NetAUse response value 88
NetAUse result row 232
NetBUp response value 79, 86, 91, 97, 141, 149
NetBUp result row 238
NetReads response value 90
NetReads result row 154, 232, 273
NetUse response value 97
NetUse result row 237
NetWrites response value 90
NetWrites result row 154, 233, 273
NewStatus result row 357
NumOfSteps response value 131
NumOfSteps result row 259
NumProcs result row 283
NumTasks response value 171
NVMemAllocSegs result row 154, 274
O
Object Id response value 305
Object Name response value 305
Object Status response value 305
Object Type response value 305
ObjectId result row 358
ObjectName result row 358, 390
ObjectStatus result row 358
ObjectType result row 358, 390
Open API routines. See UDFs, external stored procedures
Open APIs
examples 17
overview 17
versus PM/APIs 17
Open Application Programming Interfaces. See Open APIs
OpEnv 356
Other Count response value 338
OverRidable result row 370, 374
Application Programming Reference
P
Parcels
data 36
error 38
failure 38
IndicData 36
IndicReq 35
response 37
PartName response value 110
PartName result row 214, 243
PctAMPWT result row 153, 271
PctDispatcher result row 154, 273
PctParser result row 153, 272
PctService result row 153, 271
PEAvgCPU response value 163
PEAvgCPU result row 278
PECount response value 87
PECount result row 231
PECPUsec response value 112
PECPUsec result row 215, 244
PEPNodes response value 170
PercntKernel response value 87
PercntService response value 87
PercntUser response value 87
PERFGROUPS request, PM/API 308
examples of 311
sample input 310
sample output 311
Performance Group Name response value 310
Performance Group. See PGs, types of
PEState response value 111
PEstate result row 214, 243
PGId response value 170
PGId result row 282
PGs, types of 309
Physical resource, system-level monitoring 23
PhysicalRead response value 174
PhysicalRead result row 285
PhysicalReadKB response value 174
PhysicalReadKB result row 285
PhysicalWrite response value 174
PhysicalWrite result row 285
PhysicalWriteKB response value 174
PhysicalWriteKB result row 285
PM/API requests
ABORT SESSION 42, 50, 126
EVENT STATUS 299
IDENTIFY 36, 61, 66, 126
IDENTIFY DATABASE 36
IDENTIFY TABLE 36
IDENTIFY USER 36
MONITOR AWT RESOURCE 69
MONITOR PHYSICAL CONFIG 77
449
Index
MONITOR PHYSICAL RESOURCE 83
MONITOR PHYSICAL SUMMARY 93
MONITOR QUERYBAND 395
MONITOR SESSION 101, 126
MONITOR SQL 128
MONITOR VERSION 136
MONITOR VIRTUAL CONFIG 139
MONITOR VIRTUAL RESOURCE 146
MONITOR VIRTUAL SUMMARY 159
MONITOR WD 168
PERFGROUPS 308
SET RESOURCE RATE 179
SET SESSION ACCOUNT 183
SET SESSION RATE 187
TDWM DELAY REQUEST CHANGE 313
TDWM EXCEPTIONS 316
TDWM LIST WD 321
TDWM STATISTICS 324
TDWM WD ASSIGNMENT 341
USER EVENT CONTROL 345
PM/API sample application 411
PM/APIs
abort processing 38
and Teradata SQL 40
applications, logging off 40
applications, logging on 39
buffer allocation 38
collection rate 45
dynamic data 43
error messages 42
keywords/reserved words 42
logging rate 45
monitoring rates 43
request buffer, allocation 38
request processing 35
resource usage data 44
response buffer, allocation 38
response processing 37, 38
See also CLIv2 requests
warning and error messages 40, 48
PPId response value 170
PPId result row 282
PrcntKernel result row 231
PrcntService result row 231
PrcntUser result row 231
Precedence result row 358
Precedence/Severity response value 305
Previous User-Defined Event Status response value 347
PriorStatus result row 357
ProcId response value 87, 142
ProcId result row 150, 227, 231, 267, 270
ProxyUser response value 123
450
Q
QBName result row 401
QBValue result row 401
Query band
CLIv2 requests 394
examples of 33
features 32
SQL interfaces 398
Query band session 396
Query band transaction 396
Queryband_Name result row 408
Queryband_Type result row 409
QWaitTime response value 172
QWaitTime result row 283
QWaitTimeMax response value 172
QWaitTimeMax result row 283
R
Rates
collection 43, 45
logging 45
Record mode 37
Record Type response value 302
RecordId result row 361
RecordStatus result row 362
RecordType result row 361
RedriveProtection response value 108
Release response value 97, 164
Release_Dropped result row 409
Release_Introduced result row 409
ReleaseNum result row 238, 279
RelWgt response value 171
RelWgt result row 283
ReqCacheHits response value 112
ReqCacheHits result row 215, 245
ReqCount response value 112
ReqCount result row 215, 244
ReqCPU result row 224, 252
ReqIO result row 224, 253
ReqIOKB response value 124
ReqNo result row 224, 253
ReqPersistentSpoolSpace response value 124
ReqPhysIO response value 124
ReqPhysIOKB response value 124
ReqStartTime result row 224, 252
ReqStepsCompletedCnt response value 124
Request Number response value 123
Request parcel 35
Request_AMPSpool response value 113
Request, creating
IndicReq parcel 35
USING Data String 35
RequestAmpCPU response value 122
Application Programming Reference
Index
RequestAmpI/O response value 122
RequestNo result row 370
RequestStartDate response value 122
RequestStartTime response value 122
Requirements
for CLIv2 requests 18
for SQL interfaces 18
Reserved2 response value 110
ResLogging rate 22
ResLogging response value 97
ResLogging result row 238
ResMonitor response value 97, 164
ResMonitor result row 238, 279
Resource Logging response value 164
Resource logging. See ResLogging rate
Resource monitoring rate. See ResMonitor
Resource Partition Index response value 310
Resource Partition. See RPs, types of 308
Resource Supervisor 24
Resource usage data
logging 22
monitoring 22
Resource usage tables
versus MONITOR PHYSICAL RESOURCE request 84
versus MONITOR VIRTUAL RESOURCE request 147
Response parcel groups, PM/API MONITOR SESSION
request 108, 109
Response processing
error parcel 38
failure parcel 38
parcel ordering 37
Response values
Abort Count 338
AbortStatus 57
ActElapTime 132
Active Date 303
Active Delayed Count 338
Active Query Count 338
Active Time 303
ActRowCount 132
AGId 171
AMPAvgCPU 161
AMPAvgDisk 161
AMPAvgDiskIO 161
AmpCount 87
AMPCPUSec 113
AMPIO 113
AMPNodes 170
AMPState 113
Arrivals 337
AvailableAWTs 74
Average CPU Time 337
Average Delay Time 337
Average Response Time 337
Application Programming Reference
AvgAmpCPUSec 122
AvgAmpIOCnt 122
AvgCPU 95
AvgDisk 95
AvgDiskIO 95
Blk_x_HostId 114
Blk_x_LMode 116
Blk_x_OType 4, 116
Blk_x_SessNo 115
Blk_x_Status 117
Blk_x_UserID 115
Classification Mode 123
CollectionDate 72, 86, 98, 108, 149, 165, 170
CollectionInterval 107
CollectionSeqNum 107
CollectionTime 72, 86, 98, 108, 149, 165, 170
Completions 337
Confidence 132
Config ID 300
Config Name 301
Configuration ID 322
CPUCount 80
CPUDecayLevel 123
CPURunDelay 175
CPUType 80
CPUUse 87
CPUUserPct 172
CurLev1StepNum 131
CurLev2StepNum 131
CurrentRedriveParticipationt 124
Date 301, 305
DBQLFlushRate 108
Decayevel1CPU 176
Decayevel1IO 176
Decayevel2CPU 176
Decayevel2IO 176
Delayed Count 337
DiskOutReqAvg 89
DiskReads 88
DiskSlice 142
DiskUse 88
DiskWrites 89
DQMsgCount 75
Due To Duration 303
Enabled Flag 322
Error Count 338
EstElapTime 132
EstRowCount 132
Event Active Time 302
EventActiveDate 301
EventId 301
EventStatus 301
Exception Count 337
ExceptionInterval 108
451
Index
Expression Active Date 302
Expression Active Time 302
Expression Status 302
ExpressionId 302
Flow Control 73
Flow Control x VprocId 74
FunctionBitmap 137
HiCPUAMPNo 161
HiCPUAMPProc 161
HiCPUAMPUse 161
HiCPUPENo 163
HiCPUPEProc 163
HiCPUPEUse 163
HiDiskAMP 162
HiDiskAMPIO 162
HiDiskAMPIONo 163
HiDiskAMPIOProc 163
HiDiskAMPNo 162
HiDiskAMPProc 162
High AMP 1 In-Use Count 73
High AMP 1 VprocId 73
High AMP 2 In-Use Count 73
High AMP 2 VprocId 73
High AMP 3 In-Use Count 73
High AMP 3 VprocId 73
High AMP 4 In-Use Count 73
High AMP 4 VprocId 73
High AMP 5 In-Use Count 73
High AMP 5 VprocId 73
HighCPUProcId 95
HighCPUUse 95
HighDisk 96
HighDiskIO 96
HighDiskIOProcId 96
HighDiskProcId 96
HostBlockReads 89
HostBlockWrites 89
HostId 57, 109, 142
HotAmp1CPU 118
HotAmp1CPUId 119
HotAMP1IO 119
HotAmp1IOId 120
HotAmp2CPU 119
HotAmp2CPUId 119
HotAMP2IO 119
HotAmp2IOId 120
HotAmp3CPU 119
HotAmp3CPUId 119
HotAMP3IO 119
HotAmp3IOId 120
Id 303
Interval 1 Count 72
Interval 2 Count 72
Interval 3 Count 72
452
Interval 4 Count 73
InUseAWTs 74
IOCompleted 176
IOCompletedKB 176
IOCriticalSubmitted 176
IOCriticalSubmittedKB 176
IODecayLevel 123
IODelay 173
IODelayTime 174
IOSubmitted 175
IOSubmittedKB 175
LoCPUAMPNo 162
LoCPUAMPProc 162
LoCPUAMPUse 162
LoCPUPENo 164
LoCPUPEProc 164
LoCPUPEUse 163
LoDiskAMP 162
LoDiskAMPIO 163
LoDiskAMPIONo 163
LoDiskAMPIOProc 163
LoDiskAMPNo 162
LoDiskAMPProc 162
LogicalRead 174
LogicalReadKB 174
LogicalWrite 175
LogicalWriteKB 175
LogonDate 110
LogonPENo 109
LogonSource 118
LogonTime 110
Low AMP 1 In-Use Count 73
Low AMP 1 VprocId 73
Low AMP 2 In-Use Count 73
Low AMP 2 VprocId 73
Low AMP 3 In-Use Count 74
Low AMP 3 VprocId 74
Low AMP 4 In-Use Count 74
Low AMP 4 VprocId 74
Low AMP 5 In-Use Count 74
Low AMP 5 VprocId 74
LowAmp1CPU 120
LowAmp1CPUId 121
LowAmp1IO 120
LowAmp1IOId 121
LowAmp2CPU 120
LowAmp2CPUId 121
LowAmp2IO 120
LowAmp2IOId 121
LowAmp3CPU 120
LowAmp3CPUId 121
LowAmp3IO 120
LowAmp3IOId 121
LowCPUProcId 96
Application Programming Reference
Index
LowCPUUse 96
LowDisk 96
LowDiskIO 96
LowDiskIOProcId 97
LowDiskProcId 96
LSN 110
Maximum CPU Time 337
Maximum Response Time 337
MemAgings 90
MemAllocates 90
MemAllocatesKB 90
MemFailures 90
Met SLG Count 338
Minimum CPU Time 337
Minimum Response Time 337
MsgCount 74
NetAUp 86, 90, 97, 141, 149
NetAUse 88
NetBUp 79, 86, 91, 97, 141, 149
NetReads 90
NetUse 97
NetWrites 90
NumOfSteps 131
NumTasks 171
Object Id 305
Object Name 305
Object Status 305
Object Type 305
Other Count 338
PartName 110
PEAvgCPU 163
PECount 87
PECPUsec 112
PENodes 170
PercntKernel 87
PercntService 87
PercntUser 87
Performance Group Name 310
PEState 111
PGId 170
PhysicalRead 174
PhysicalReadKB 174
PhysicalWrite 174
PhysicalWriteKB 174
PPId 170
Precedence/Severity 305
Previous User-Defined Event Status 347
ProcId 87, 142
ProxyUser 123
QWaitTime 172
QWaitTimeMax 172
Record Type 302
RedriveProtection 108
Release 97, 164
Application Programming Reference
RelWgt 171
ReqCacheHits 112
ReqCount 112
ReqIOKB 124
ReqPersistentSpoolSpace 124
ReqPhysIO 124
ReqPhysIOKB 124
ReqStepsCompletedCnt 124
Request Number 123
Request_AMPSpool 113
RequestAmpCPU 122
RequestAmpI/O 122
RequestStartDate 122
RequestStartTime 122
Reserved2 110
ResLogging 97, 164
ResMonitor 97, 164
Resource Partition Index 310
RunVprocNo 109
SampleSec 72, 86, 149, 170, 336
SesMonitorLoc 164
SesMonitorSys 164
SessionNo 57, 109
SessionRate 108
SessionRateThreshold 108
Status 80, 88, 142, 303
StepNum 131
StepText 131, 132
SwapDrops 90
SwapReads 89
SwapWrites 90
SystemType 79, 141
TacticalCPUException 124
TacticalExceptionCPU 176
TacticalExceptionIO 176
TacticalIOException 124
TempSpace 118
Time 301, 305
UpAMPCount 121
UserAccount 110
User-Defined Event Status 347
UserId 110
UserName 57, 109
Version 98, 165
VPId 175
VProcNo 142
VprocNo 74
VProcType 142
VprType 171
WaitIO 175
WaitOther 175
WD ID 337
WDId 123, 171
WLC ID 322
453
Index
WLC Name 322
WorkMsgMaxDelay 173
WorkTypeInuseAvg 173
WorkTypeInuseMax 173
XActCount 112
Result rows
AbortCnt 386
AbortStatus 197
ActElapsedTime 261
Active 390
ActiveQueryCnt 385, 386
ActRowCount 261
AGId 282
AMPAvgCPU 276
AMPAvgDisk 276
AMPAvgDiskIO 276
AmpCount 223, 231, 252
AMPCPUSec 216, 245
AMPIO 216, 245
AMPNodes 289
AMPState 216, 245
Arrivals 385
AvailableAWTs 205
AvgAmpCPUSec 223, 252
AvgAmpIOCnt 223, 252
AvgCPU 236
AvgCPUTime 385
AvgDelayTime 385
AvgDisk 236
AvgDiskIO 236
AvgRespTime 385
BlkxHostId 217, 246
BlkxLmode 218, 247
BlkxObjDBID 219, 248
BlkxObjTID 219, 248
BlkxOtype 219, 248
BlkxSessNo 217, 246
BlkxStatus 220, 249
BlkxUserId 218, 247
BlockingCnt 370
Category 409
ClusterNo 270
Completions 385
Confidence 261
CPUCount 228
CPURunDelay 286
CPUType 228
CPUUse 150, 231, 271
CPUUserPct 284
CurLvl1StepNo 259
CurLvl2StepNo 259
DecayLevel11CPU 287
DecayLevel12CPU 287
DecayLevel1IO 286
454
DecayLevel2IO 286
Default_Value 409
Delayed 390
DelayedCnt 385
Description 409
DiskOutReqAvg 152, 232, 272
DiskReads 151, 232, 272
DiskSlice 268
DiskUse 151, 232, 272
DiskWrites 152, 232, 272
DontReclassifyFlag 224, 253
DQMsgCount 205
DueToDuration 362
EnabledFlag 376
ErrorCnt 386
EstElapsedTime 261
EstRowCount 261
Event_Category 375
EventActiveDate 361
EventActiveTime 361
EventId 361
EventKind 359
EventStatus 361
ExceptionCnt 385
ExpActiveDate 361
ExpActiveTime 361
ExpressionId 361
ExpressionStatus 361
ExtraField1 285
ExtraField2 285
ExtraField3 286
ExtraField4 286
FCVprocIdx 210
Filter_Category 375
FlowControl 208
HiCPUAMPNo 277
HiCPUAMPProc 277
HiCPUAMPUse 276
HiCPUPENo 278
HiCPUPEProc 278
HiCPUPEUse 278
HiDiskAMP 276
HiDiskAMPIO 276
HiDiskAMPIONo 277
HiDiskAMPIOProc 277
HiDiskAMPNo 277
HiDiskAMPProc 277
HighAMP1InUseCount 208
HighAMP1VprocId 208
HighAMP2InUseCount 209
HighAMP2VprocId 209
HighAMP3InUseCount 209
HighAMP3VprocId 209
HighAMP4InUseCount 209
Application Programming Reference
Index
HighAMP4VprocId 209
HighAMP5InUseCount 209
HighAMP5VprocId 209
HighCPUProcId 236
HighCPUUse 236
HighDisk 236
HighDiskIO 236
HighDiskIOProcId 237
HighDiskProcId 236
HostId 196, 213, 243, 259, 261, 264, 268, 370, 373
HostId/ClusterNo 150
HotAmp1CPU 220, 249
HotAmp1CPUId 221, 250
HotAmp1IO 221, 250
HotAmp1IOId 221, 250
HotAmp2CPU 221, 250
HotAmp2CPUId 221, 250
HotAmp2IO 221, 250
HotAmp2IOId 222, 250
HotAmp3CPU 221, 250
HotAmp3CPUId 221, 250
HotAmp3IO 221, 250
HotAmp3IOId 222, 251
HstBlkRds 152, 233, 273
HstBlkWrts 152, 233, 273
IntervalCount1 208
IntervalCount2 208
IntervalCount3 208
IntervalCount4 208
InUseAWTs 205
IOCompleted 286
IOCompletedKB 286
IOCriticalSubmitted 286
IOCriticalSubmittedKB 286
IODelay 284, 285
IOSubmitted 286
IOSubmittedKB 286
LoCPUAMPNo 277
LoCPUAMPProc 278
LoCPUAMPUse 277
LoCPUPENo 278
LoCPUPEProc 279
LoCPUPEUse 278
LoDiskAMP 277
LoDiskAMPIO 277
LoDiskAMPIONo 278
LoDiskAMPIOProc 278
LoDiskAMPNo 278
LoDiskAMPProc 278
LogicalRead 285
LogicalReadKB 285
LogicalWrite 285
LogicalWriteKB 285
LogonPENo 213, 243
Application Programming Reference
LogonSource 220, 249
LogonTime 214, 243
LowAmp1CPU 222, 251
LowAmp1CPUId 222, 251
LowAMP1InUseCount 209
LowAmp1IO 222, 251
LowAmp1IOId 223, 252
LowAMP1VprocId 209
LowAmp2CPU 222, 251
LowAmp2CPUId 222, 251
LowAMP2InUseCount 209
LowAmp2IO 223, 251
LowAmp2IOId 223, 252
LowAMP2VprocId 209
LowAmp3CPU 222, 251
LowAmp3CPUId 222, 251
LowAMP3InUseCount 209
LowAmp3IO 223, 251
LowAmp3IOId 223, 252
LowAMP3VprocId 209
LowAMP4InUseCount 209
LowAMP4VprocId 209
LowAMP5InUseCount 209
LowAMP5VprocId 209
LowCPUProcId 237
LowCPUUse 237
LowDisk 237
LowDiskIO 237
LowDiskIOProocId 237
LowDiskProcId 237
LSN 214, 244
Max_Len 409
MaxCPUTime 385
MaxRespTime 385
MemAgings 233
MemAllocateKB 233
MemAllocates 233
MemFailures 233
MetSLGCnt 385
MinCPUTime 385
MinRespTime 385
MoreBlockers 220, 249
MsgCount 205
NetAUp 238
NetAUse 232
NetBUp 238
NetReads 154, 232, 273
NetUse 237
NetWrites 154, 233, 273
NewStatus 357
NumOfSteps 259
NumProcs 283
NVMemAllocSegs 154, 274
ObjectId 358
455
Index
ObjectName 358, 390
ObjectStatus 358
ObjectType 358, 390
OverRidable 370, 374
PartName 214, 243
PctAMPWT 153, 271
PctDispatcher 154, 273
PctParser 153, 272
PctService 153, 271
PEAvgCPU 278
PECount 231
PECPUsec 215, 244
PENodes 289
PEstate 214, 243
PGId 282
PhysicalRead 285
PhysicalReadKB 285
PhysicalWrite 285
PhysicalWriteKB 285
PPId 282
PrcntKernel 231
PrcntService 231
PrcntUser 231
Precedence 358
PriorStatus 357
ProcId 150, 227, 231, 267, 270
QBName 401
QBValue 401
Queryband_Name 408
Queryband_Type 409
QWaitTime 283
QWaitTimeMax 283
RecordId 361
RecordStatus 362
RecordType 361
Release_Dropped 409
Release_Introduced 409
ReleaseNum 238, 279
RelWgt 283
ReqCacheHits 215, 245
ReqCount 215, 244
ReqCPU 224, 252
ReqIO 224, 253
ReqNo 224, 253
ReqStartTime 224, 252
RequestNo 370
ResLogging 238
ResMonitor 238, 279
RuleSetId 375, 376
RunVprocNo 214, 243
SampleRate 289
SeqNum 264
SesMonitorLoc 279
SesMonitorSys 279
456
SessionCnt 279
SessionNo 196, 213, 243, 259, 261, 264, 370, 373
SessRunCount 151, 271
SQLStep 261
SQLText 264
StateActiveDate 362
StateActiveTime 362
Status 150, 228, 231, 268, 270
StepNum 261
TacticalExceptionCPU 287
TacticalExceptionIO 287
TDWMEventMapping 358
TDWMEventStatus 361
TDWMExceptions 366
TDWMGetDelayedQueries 370
TDWMGetDelayedUtilities 373
TDWMInquire 375
TDWMListWDs 376
TDWMThrottleStatistics 390
TempSpaceUsg 223, 252
Throttle_Category 375
ThrottleLimit 390
TimeHeld 370, 373
UserAccount 215, 244
UserId 214, 244
UserName 196, 214, 244
Username 370, 373
UtilityCount 378
UtilityLimit 378
UtilityType 378
Version 238, 279
VPId 286
VprocNo 150, 205, 267, 270
VprocType 149, 270
Vproctype 267
VprType 282
WaitIO 286
WaitOther 286
WDId 253, 282, 370, 376, 385
WDName 376
WlcId 224
Workload_Category 375
WorkMsgMaxDelay 284
WorkTypeInuseAvg 284
WorkTypeInuseMax 284
XActCount 215, 244
Return value
for AbortSessions 199
for concatenated session queryband 399
for concatenated transaction queryband 399
for GetPSFVersion 349
for GetQueryBand 399
for IdentifyDatabase 201
for IdentifySession 202
Application Programming Reference
Index
for IdentifyTable 203
for IdentifyUser 204
for MonitorQueryBand 406
for MonitorSessionRate 256
for SetResourceRate 291
for SetSessionAccount 292
for SetSessionRate 294
for TDWMAbortDelayedRequest 350
for TDWMAssignWD 355
for TDWMExceptionRate 364
for TDWMReleaseDelayedRequest 380
for TDWMSummaryRate 388
REVOKE MONITOR command, SQL 42
RPs, types of 309
Rules, Teradata ASM 28, 29
RuleSetId result row 375, 376
RunVprocNo response value 109
RunVprocNo result row 214, 243
S
Sample application, PM/API 411
SampleSec response value 72, 86, 149, 170, 336
SeqNum result row 264
SesMonitorLoc 22
SesMonitorLoc response value 164
SesMonitorLoc result row 279
SesMonitorSys 22
SesMonitorSys rate 294
SesMonitorSys response value 164
SesMonitorSys result row 279
Session level data 44
Session, query band 32
session, query band 396
SessionCnt result row 279
Session-level monitoring 23
SessionNo response value 57, 109
SessionNo result row 196, 213, 243, 259, 261, 264, 370, 373
SessionRate response value 108
SessionRateThreshold response value 108
Sessions
aborted 59
blocked 59
SessRunCount result row 151, 271
SET QUERY_BAND, SQL statement 32
SET RESOURCE RATE request, PM/API 179
and MONITOR PHYSICAL RESOURCE 44, 92
and MONITOR PHYSICAL SUMMARY 99
and MONITOR VIRTUAL RESOURCE 44
sample input 181
sample output 181
SET SESSION ACCOUNT request, PM/API 183
sample input 186
sample output 186
Application Programming Reference
SET SESSION ACCOUNT statement, SQL 342
SET SESSION RATE request, PM/API 187
and MONITOR PHYSICAL SUMMARY 99, 166, 193
sample output 193
scenarios 189, 190, 191
writing a Resource Supervisor 25
writing an Idle Session Logoff 25
SetResourceRate function 290
example of 291
SetSessionAccount function 292
examples of 293
SetSessionRate function 294
example of 295
SQL commands
GRANT 42
REVOKE MONITOR 42
SQL interfaces
examples of 17, 26
requirements for 18
types of 30, 34
SQL statements
ALTER TABLE 53
SET QUERY_BAND 32
SET SESSION ACCOUNT 342
SQLStep result row 261
SQLText result row 264
StateActiveDate result row 362
StateActiveTime result row 362
Status response value 80, 88, 142, 303
Status result row 150, 228, 231, 268, 270
StepNum response value 131
StepNum result row 261
StepText response value 131, 132
SwapDrops response value 90
SwapReads response value 89
SwapWrites response value 90
Syscon 356
System PMPC
API examples 26
CLIv2 requests 26, 48
features 21
setting collection rates 21
setting logging rates 21
SQL interfaces 26, 194
System tables
DBC.Dbase 63
DBC.ResUsage 179, 290
DBC.SessionTbl 63, 184, 292
DBC.Software_Event_LogV view 53, 78, 140, 180
DBC.SW_Event_Log 40, 188
DBC.TVM 63
System-level monitoring, types of 23
SystemType response value 79, 141
457
Index
T
TacticalCPUException response value 124
TacticalExceptionCPU 176
TacticalExceptionCPU result row 287
TacticalExceptionIO 176
TacticalExceptionIO result row 287
TacticalIOException response value 124
TDP internal sessions, identifying 51
TDWM DELAY REQUEST CHANGE request, PM/API 313
sample input 315
sample output 315
TDWM EXCEPTIONS request, PM/API 316
sample input 320
sample output 320
TDWM LIST WD request, PM/API 321
sample input 322
sample output 323
TDWM STATISTICS request, PM/API 324
examples of 329, 330, 332, 333
TDWM SUMMARY request, PM/API
sample input 339
sample output 340
TDWM WD ASSIGNMENT request, PM/API 341
sample input 343
sample output 343
TDWMAbortDelayedRequest function 350
example of 350
TDWMApply procedure 352
example of 353
TDWMAssignWD function 354
example of 355
TDWMEventControl procedure 356
activating SysCon or OpEnv 356
example of 357
TDWMEventMapping function 358
example of 359
TDWMEventStatus function 360
example of 362
TDWMExceptionRate function 364
example of 364
TDWMExceptions function 365
example of 367
TDWMGetDelayedQueries function 369
examples of 371
TDWMGetDelayedUtilities function 373
example of 374
TDWMInquire function 375
example of 375
TDWMListWDs function 376
example of 377
TDWMLoadUtilStatistics function 378
example of 379
TDWMReleaseDelayedRequest function 380
458
examples of 380
TDWMRuleControl procedure 382
example of 382
TDWMSetLimits procedure 383
example of 383
TDWMSummary function 384
example of 387
TDWMSummaryRate function 388
example of 388
TDWMThrottleStatistics function 389
examples of 390
TempSpace response value 118
TempSpaceUsg result row 223, 252
Teradata Active System Management. See Teradata ASM
Teradata ASM rules 28, 29, 321
Teradata dynamic workload management APIs
CLIv2 requests 30, 298
SQL interfaces 30, 348
Teradata dynamic workload management software
component of Teradata ASM 28
Teradata SQL
keywords/reserved words 42
versus PM/APIs 40
Throttle_Category result row 375
ThrottleLimit result row 390
Time response value 301, 305
TimeHeld result row 370, 373
Transaction, query band 32, 396
U
UDFs
AbortListSessions 195
AbortSession 198
GetPSFVersion 349
GetQueryBand 399
GetQueryBandPairs 400
IdentifyDatabase 201
IdentifySession 202
IdentifyTable 203
IdentifyUser 204
MonitorAMPLoad 205
MonitorAWTResource 207
MonitorMySessions 211
MonitorPhysicalConfig 227
MonitorPhysicalResource 230
MonitorPhysicalSummary 235
MonitorQueryBand 406
MonitorSession 240
MonitorSessionRate 256
MonitorSQLCurrentStep 258
MonitorSQLSteps 260
MonitorSQLText 263
MonitorSystemPhysicalConfig 265
Application Programming Reference
Index
MonitorVirtualConfig 267
MonitorVirtualResource 269
MonitorVirtualSummary 275
MonitorWD 281
MonitorWDRate 289
SetResourceRate 290
SetSessionAccount 292
SetSessionRate 294
TDWMAbortDelayedRequest 350
TDWMAssignWD 354
TDWMEventMapping 358
TDWMEventStatus 360
TDWMGetDelayedQueries 369
TDWMGetDelayedUtilities 373
TDWMInquire 375
TDWMListWDs 376
TDWMLoadUtilStatistics 378
TDWMReleaseDelayedRequest 380
TDWMSummary 384
TDWMSummaryRate 388
TDWMThrottleStatistics 389
UpAMPCount response value 121
USER EVENT CONTROL request, PM/API 345
UserAccount response value 110
UserAccount result row 215, 244
User-Defined Event Status response value 347
User-defined functions. See UDFs
UserId response value 110
UserId result row 214, 244
UserName response value 57, 109
UserName result row 196, 214, 244
Username result row 370, 373
USING Data String 35
UtilityCount result row 378
UtilityLimit result row 378
UtilityType result row 378
W
WaitIO response value 175
WaitIO result row 286
WaitOther response value 175
WaitOther result row 286
Warning messages, common 48
WD ID response value 337
WDId response value 123, 171
WDId result row 253, 282, 370, 376, 385
WDName result row 376
WLC ID response value 322
WLC Name response value 322
WlcId result row 224
Work types 72
Workload management API 15
Workload_Category result row 375
Workloads rule, Teradata ASM
WorkMsgMaxDelay response value 173
WorkMsgMaxDelay result row 284
WorkTypeInuseAvg response value 173
WorkTypeInuseAvg result row 284
WorkTypeInuseMax response value 173
WorkTypeInuseMax result row 284
X
XActCount response value 112
XActCount result row 215, 244
V
Version response value 98, 165
Version result row 238, 279
Virtual resource, system-level monitoring 23
VPId response value 175
VPId result row 286
VProcNo response value 142
VprocNo response value 74
VprocNo result row 150, 205, 267, 270
VProcType response value 142
VprocType result row 149, 270
Vproctype result row 267
VprType response value 171
VprType result row 282
Application Programming Reference
459
Index
460
Application Programming Reference
Was this manual useful for you? yes no
Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project

Download PDF

advertising