Workload management api

1,545 views

Published on

Teradata Workload management API

Published in: Technology, Business
0 Comments
0 Likes
Statistics
Notes
  • Be the first to comment

  • Be the first to like this

No Downloads
Views
Total views
1,545
On SlideShare
0
From Embeds
0
Number of Embeds
4
Actions
Shares
0
Downloads
32
Comments
0
Likes
0
Embeds 0
No embeds

No notes for slide

Workload management api

  1. 1. Teradata DatabaseWorkload Management API: PM/API and Open API Release 13.0 B035-1090-098A April 2009
  2. 2. The product or products described in this book are licensed products of Teradata Corporation or its affiliates.Teradata, BYNET, DBC/1012, DecisionCast, DecisionFlow, DecisionPoint, Eye logo design, InfoWise, Meta Warehouse, MyCommerce,SeeChain, SeeCommerce, SeeRisk, Teradata Decision Experts, Teradata Source Experts, WebAnalyst, and You’ve Never Seen Your Business LikeThis Before are trademarks or registered trademarks of Teradata Corporation or its affiliates.Adaptec and SCSISelect are trademarks or registered trademarks of Adaptec, Inc.AMD Opteron and Opteron are trademarks of Advanced Micro Devices, Inc.BakBone and NetVault are trademarks or registered trademarks of BakBone Software, Inc.EMC, PowerPath, SRDF, and Symmetrix are registered trademarks of EMC Corporation.GoldenGate is a trademark of GoldenGate Software, Inc.Hewlett-Packard and HP are registered trademarks of Hewlett-Packard Company.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 and Engenio are registered trademarks of LSI Corporation.Microsoft, Active Directory, Windows, Windows NT, and Windows Server are registered trademarks of Microsoft Corporation in the UnitedStates and other countries.Novell and SUSE are registered trademarks of Novell, Inc., in the United States and other countries.QLogic and SANbox are trademarks or registered trademarks of QLogic Corporation.SAS and SAS/C are trademarks or registered trademarks of SAS Institute Inc.SPARC is a registered trademark of SPARC International, Inc.Sun Microsystems, Solaris, Sun, and Sun Java are trademarks or registered trademarks of Sun Microsystems, Inc., in the United States and othercountries.Symantec, NetBackup, and VERITAS are trademarks or registered trademarks of Symantec Corporation or its affiliates in the United Statesand other countries.Unicode is a collective membership mark and a service mark of Unicode, Inc.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, EITHEREXPRESS OR IMPLIED, INCLUDING THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, ORNON-INFRINGEMENT. SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OF IMPLIED WARRANTIES, SO THE ABOVE EXCLUSIONMAY 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 OFSUCH DAMAGES.The information contained in this document may contain references or cross-references to features, functions, products, or services that arenot 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 updatedwithout notice. Teradata Corporation may also make improvements or changes in the products or services described in this information at anytime without notice.To maintain the quality of our products and services, we would like your comments on the accuracy, clarity, organization, and value of thisdocument. Please e-mail: teradata-books@lists.teradata.comAny comments or materials (collectively referred to as “Feedback”) sent to Teradata Corporation will be deemed non-confidential. TeradataCorporation 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, TeradataCorporation will be free to use any ideas, concepts, know-how, or techniques contained in such Feedback for any purpose whatsoever, includingdeveloping, manufacturing, or marketing products or services incorporating Feedback.Copyright © 2000 – 2009 by Teradata Corporation. All Rights Reserved.
  3. 3. PrefacePurpose This book, Workload Management API: PM/API and Open API, describes the workload management application programming interface (API), which consists of interfaces to System Performance Monitor and Production Control (PMPC), also called PM/APIs, and open APIs. Use the workload management APIs described in this book to interface with your own custom applications when performance monitoring tools such as Performance Monitor (PMON) or the Resource Usage (ResUsage) reports do not provide the information you need.Audience This book is intended for developers creating third-party applications, and end-users writing their own custom applications, requiring the acquisition and use of Teradata Database workload management and performance data.Supported Software Release This book supports Teradata® Database 13.0.Prerequisites Users of the PM/API should have some knowledge of Call-Level Interface version 2 (CLIv2), basic Teradata SQL terminology, and overall Teradata Database architectural concepts. Information on CLIv2 is available in the following books: • Teradata Call-Level Interface Version 2 Reference for Channel-Attached Systems • Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems • Database Design For sample programs using CLI, see Appendix A: “Sample PM/API Application.”Workload Management API: PM/API and Open API 3
  4. 4. PrefaceChanges to This BookChanges to This Book Release Description Teradata Database 13.0 • Added the ProxyUser field and examples to the MONITOR SESSION, MonitorSession, and MonitorMySessions sections. April 2009 • Changed the monitor software version ID value to 7 on all PM/API mon_ver_id fields. • Added Response Group V data fields to the MONITOR SESSION section. • Added the VSS vproc to the VprocType field and the SubPoolId to the SessLogCount field in the MONITOR VIRTUAL RESOURCE and MonitorVirtualResource sections. • Added to the NVMemAllocSegs field description how the value is computed for the vproc-level on Windows and Linux and a note stating that this field is called “Max I/O Time” in PMON and “Maximum I/O Time” in MONITOR VIRTUAL RESOURCE and MonitorVirtualResource. • Updated some of the field descriptions to include the VSS vproc for MONITOR VIRTUAL CONFIG and MonitorVirtualConfig. • Updated the TDWM STATISTICS, TDWMThrottleStatistics, and TDWMGetDelayedQueries sections with new fields and example outputs. Teradata Database 12.0 • Added a note to the MONITOR SESSION section, which lists the AMP CPU fields in the MONITOR SESSION response that are September 2007 normalized for the current release. • Renamed the DeltaAmpSpool field to “Request_AMPSpool” in MonitorSession and MonitorMySessions. • Added two PEState response values: SESDELAYED and QTDELAYED. • Added open APIs to the following chapters: “PMPC APIs,” “Teradata Dynamic Workload Management APIs,” and “Query Band APIs. • Added the following PM/APIs: EVENT STATUS, USER EVENT CONTROL, MONITOR AWT RESOURCE, and updated existing APIs in the “Teradata Dynamic Workload Management APIs” chapter.4 Workload Management API: PM/API and Open API
  5. 5. Preface Additional InformationAdditional Information URL Description http://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. http://www.teradata.com The Teradata home page provides links to numerous sources of information about Teradata. Links include: • Executive reports, case studies of customer experiences with Teradata, and thought leadership • Technical information, solutions, and expert advice • Press releases, mentions and media resources http://teradatauniversitynetwork.com Teradata University Network fosters education on data warehousing, business intelligence (BI) and database administration (DBA). 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 e-mail: teradata- books@lists.teradata.comReferences to Microsoft Windows and Linux This book refers to “Microsoft Windows” and “Linux.” For Teradata Database 13.0, these references mean: • “Windows” is Microsoft Windows Server 2003 64-bit. • “Linux” is SUSE Linux Enterprise Server 9 and SUSE Linux Enterprise Server 10.Workload Management API: PM/API and Open API 5
  6. 6. PrefaceReferences to Microsoft Windows and Linux6 Workload Management API: PM/API and Open API
  7. 7. Table of Contents Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3 Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3 Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3 Supported Software Release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3 Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3 Changes to This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4 Additional Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5 References to Microsoft Windows and Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5 Chapter 1: Workload Management Concepts and Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 What the Workload Management API Provides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 What PM/API Is . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Disadvantages of Using PM/API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 What the Open API Is. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 Differences Between Open API and PM/API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 System PMPC Features. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 Setting Sampling and Logging Intervals. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 System-Level Monitoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 Session-Level Monitoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 Monitoring Locks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Teradata Dynamic Workload Management Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Query Banding Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 System PMPC Applications Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 Resource Supervisor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 Idle Session Logoff . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 Workload Management API Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 Query Band API Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 API Categories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 System PMPC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 Teradata Dynamic Workload Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 Query Bands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30Workload Management API: PM/API and Open API 7
  8. 8. Table of Contents Requirements for Using the API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31 CLIv2 Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31 SQL Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31 Required Privileges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31 Chapter 2: MONITOR Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .33 PM/API Request Processing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .33 Creating a Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .33 Setting Indicator or Record Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34 Response Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35 Parcel Ordering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35 Buffer Allocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .36 Abort Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37 Logging On . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .38 Logging Off . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .39 Warning and Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .39 Comparisons Between PM/API and Teradata SQL Requests . . . . . . . . . . . . . . . . . . . . . . . . . . .39 Similarities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .39 Differences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .39 Keywords/Reserved Words . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40 Teradata SQL Users Can Issue GRANT and REVOKE . . . . . . . . . . . . . . . . . . . . . . . . . . . .40 PM/API Users Can Issue ABORT SESSION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41 PM/API Dynamic Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41 Monitoring Rates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42 Session-Level Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42 Resource Usage Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42 Logging Resource Usage Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43 Sampling and Logging Rates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45 Chapter 3: PMPC APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .49 CLIv2 Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50 Common Warning and Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50 ABORT SESSION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .54 IDENTIFY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .67 MONITOR AWT RESOURCE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .75 MONITOR PHYSICAL CONFIG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .82 MONITOR PHYSICAL RESOURCE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .888 Workload Management API: PM/API and Open API
  9. 9. Table of Contents MONITOR PHYSICAL SUMMARY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108 MONITOR SESSION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 How Session Data is Collected . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 Unreported Session Partitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 A Down Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 Internal Sessions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 Response Parcel Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 MONITOR SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147 MONITOR VERSION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156 MONITOR VIRTUAL CONFIG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159 MONITOR VIRTUAL RESOURCE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166 MONITOR VIRTUAL SUMMARY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188 SET RESOURCE RATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199 SET SESSION ACCOUNT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204 SET SESSION RATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209 SQL Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217 AbortSessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218 AbortListSessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220 IdentifyDatabase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223 IdentifySession . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224 IdentifyTable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225 IdentifyUser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226 MonitorAWTResource. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227 MonitorMySessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231 MonitorPhysicalConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245 MonitorPhysicalResource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247 MonitorPhysicalSummary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257 MonitorSession . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262 MonitorSessionRate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276 MonitorSQLCurrentStep . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278 MonitorSQLSteps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280 MonitorSQLText. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283 MonitorVirtualConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285 MonitorVirtualResource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287 MonitorVirtualSummary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297 SetResourceRate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305 SetSessionAccount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308 SetSessionRate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310Workload Management API: PM/API and Open API 9
  10. 10. Table of Contents Chapter 4: Teradata Dynamic Workload Management APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .311 CLIv2 Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .312 EVENT STATUS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .313 PERFGROUPS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .321 TDWM DELAY REQUEST CHANGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .325 TDWM LIST WD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .329 TDWM STATISTICS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .333 TDWM SUMMARY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .341 TDWM WD ASSIGNMENT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .345 USER EVENT CONTROL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .349 SQL Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .352 TDWMAbortDelayedRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .353 TDWMApply. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .355 TDWMAssignWD. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .357 TDWMEventControl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .359 TDWMEventMapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .361 TDWMEventStatus. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .363 TDWMGetDelayedQueries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .367 TDWMGetDelayedUtilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .370 TDWMInquire . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .372 TDWMListWDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .373 TDWMLoadUtilStatistics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .375 TDWMObjectAssn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .376 TDWMReleaseDelayedRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .378 TDWMRuleControl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .380 TDWMSetLimits. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .381 TDWMSummary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .382 TDWMSummaryRate. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .384 TDWMThrottleStatistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .385 Chapter 5: Query Band APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .389 CLIv2 Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .390 MONITOR QUERYBAND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .391 SQL Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .39510 Workload Management API: PM/API and Open API
  11. 11. Table of Contents GetQueryBand. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396 GetQueryBandPairs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397 GetQueryBandSP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399 GetQueryBandValue. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400 GetQueryBandValueSP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402 MonitorQueryBand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403 Appendix A: Sample PM/API Application . . . . . . . . . . . . . . . . . . . . . . . 405 Sample Application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405 Header File for Sample PMPC Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419 Appendix B: Combination PEState and AMPState Response Values for MONITOR SESSION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431 Sample MONITOR SESSION Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431 Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437Workload Management API: PM/API and Open API 11
  12. 12. Table of Contents12 Workload Management API: PM/API and Open API
  13. 13. CHAPTER 1 Workload Management Concepts and Features This chapter provides an overview of the workload management application programming (API) interface. It describes the functionality and features of the System Performance Monitor and Production Control (PMPC), Teradata Dynamic Workload Management, and Query Band APIs.What the Workload Management API Provides The workload management API consists of interfaces to System PMPC and open APIs. These interfaces are used with client components (for example, Teradata Manager, Teradata Dynamic Workload Manager, and Performance Monitor [PMON]) to: • Monitor system and session-level activities. • Manage Teradata Dynamic Workload Management rules and update components stored in a custom database called TDWM. The TDWM database is shared by Teradata Dynamic Workload Manager and Teradata Query Scheduler. For more information about TDWM, see Teradata Dynamic Workload Manager User Guide. • Track system usage and manage task priorities. For a complete description of the programming interfaces used to perform these functions, see: • “Chapter 3 PMPC APIs” on page 49 • “Chapter 4 Teradata Dynamic Workload Management APIs” on page 311 • “Chapter 5 Query Band APIs” on page 389 For more information on the features of the workload management API, see: • “System PMPC Features” on page 16 • “Teradata Dynamic Workload Management Features” on page 19 • “Query Banding Features” on page 22What PM/API Is PM/API provides access to PMPC routines resident within Teradata Database. The PMPC subsystem is available through a logon partition called MONITOR, using a specialized PM/API subset of Call-Level Interface version 2 (CLIv2).Workload Management API: PM/API and Open API 13
  14. 14. Chapter 1: Workload Management Concepts and FeaturesWhat the Open API Is The PM/API, and applications built around it (such as PMON and Teradata Manager), have the following advantages: • CLIv2 data is acquired in near real time, with less overhead, and with minimal possibility of being blocked. These capabilities allow frequent in-process performance analysis. • A CLIv2 interface 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 interface 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. Use of the PM/API may not be the right choice for all performance monitoring requirements. Standard performance monitoring tools and reports (such as resource usage macros and tables) may be sufficient. For more information on how the PMPC subsytem manages CLIv2 interfaces, see: • “Teradata Dynamic Workload Management Features” on page 19 • “PM/API Request Processing” on page 33Disadvantages of Using PM/API Some of the disadvantages of using the PM/API include: • A custom CLI application in C or some other programming language must be written. • CLIv2 interface data is not as detailed as resource usage data. • CLIv2 interface data is not written to tables; therefore, whatever resource usage data is not examined at the end of a particular sample interval may be overwritten and lost. • Large amounts of CLIv2 interface data cannot be accumulated over a long period of time and, therefore, cannot 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 Note: CLIv2 interface trend data can be collected and saved into tables by Teradata Manager.What the Open API Is The open API provides an SQL interface to System PMPC through user-defined functions (UDFs) and external stored procedures. The following are examples of some of the UDFs and external stored procedures used:14 Workload Management API: PM/API and Open API
  15. 15. Chapter 1: Workload Management Concepts and Features What the Open API Is 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 System PMPC 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 Teradata Dynamic Workload Management 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 API and PM/API The following table describes the differences between the open API (that is, SQL interfaces consisting of UDFs or external stored procedures) and the PM/API. Open APIs ... WHERE PM/APIs ... are issued in the current SQL partition require logging on to the MONITOR partition. require EXECUTE privilege on the function require MONITOR privileges. or external stored procedure use SQL parsing, dispatching steps, and UDF require use of a custom CLI application in C or processing some other programming language. run in priority of account string or Teradata run in the system priority. Dynamic Workload Management classification can be placed on a Teradata Dynamic do not block. Workload Management delay queue and can block system resources use AMP Worker Tasks (AWTs) are not subject to running out of resources (AWTs).Workload Management API: PM/API and Open API 15
  16. 16. Chapter 1: Workload Management Concepts and FeaturesSystem PMPC FeaturesRelated Topics For more information on the SQL interfaces described in this section, see: • Chapter 3: “PMPC APIs” • Chapter 4: “Teradata Dynamic Workload Management APIs” • Chapter 5: “Query Band APIs”System PMPC Features The section explains the most important System PMPC features.Setting Sampling and Logging Intervals Performance monitoring tasks (except MONITOR VERSION and MONITOR SQL) are based on periodic data collection. The rates at which the data is gathered (sample rate) and written to tables (logging rate), are set separately. You can control two session-level sampling rates, two resource usage sampling rates, and two resource logging rates. You can set all sampling rates for any interval between 0 and 3600 seconds. For other rules governing the relationship between data collection and logging rates, see Resource Usage Macros and Tables. A single master resource sampling system within the Teradata Database collects all performance monitoring data. It can be accessed in a number of ways, such as using CLIv2 or SQL interfaces. Sampling rates that are set this way may be reset by way of other performance monitoring utilities, including PMON, RSSMON, and Database Window. If this happens, warning messages are returned in cases where parameters have been changed (external to the PMPC application) since the last sampling interval. Care should be taken to integrate the various performance monitoring tasks on your system to avoid potential conflicts. Note: Because system-wide AMP/PE and node resource usage data is collected in different memory repositories than session-level 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 SET RESOURCE RATE request or the SetResourceRate function.16 Workload Management API: PM/API and Open API
  17. 17. Chapter 1: Workload Management Concepts and Features System PMPC Features Rate Description Global session Sets the system-wide (across all sessions) frequency at which session-level (SesMonitorSys) data is updated. monitoring Local session Sets the frequency at which session-level data is updated with your (SesMonitorLoc) session. This rate is not saved on disk and is lost during a system outage. monitoring Note: A change to the local sampling 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 system 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. Virtual Resource Sets the frequency at which AMP and PE resource usage data is updated. (ResMonitor) monitoring Physical Resource Sets the frequency at which node resource usage data is updated. (ResMonitor) monitoring Virtual Resource Usage Sets the frequency at which AMP and PE resource usage data is written to (ResLogging) logging the ResUsage tables. Physical Resource Sets the frequency at which node resource usage data is written to the Usage (ResLogging) ResUsage tables. logging • Data sampling rates must be set to a nonzero value for all data fields called by a CLIv2 or SQL interface or the fields will not contain any data. • The logging rate should be set to one or more even multiples of the sample rate so that old data is not written to tables. • Resource logging rate capability allows you to set the logging rate for resource usage 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. • The Virtual and Physical Resource rates must be the same, but not for the Logging rates. Related Topics For comparative information on setting sample and logging rates among various performance monitoring alternatives, see: • “Database Window (xdbw)” in Utilities • Resource Usage Macros and Tables • SQL Data Definition Language • Teradata Dynamic Workload Manager User GuideWorkload Management API: PM/API and Open API 17
  18. 18. Chapter 1: Workload Management Concepts and FeaturesSystem PMPC FeaturesSystem-Level Monitoring System PMPC allows you to perform two types of system monitoring: • Physical resources • Nodes availability • BYNET availability • General system utilization • Virtual resources (vprocs) • Access Module Processor (AMP) status, performance and utilization • Parsing Engine (PE) status, performance and utilization The way that AMP/PE and node resource data is collected and reported is different from the way that session resource data is collected and reported. Both CLIv2 and SQL interfaces collect resource utilization data for a specific sample period and report the data for that sample period. For example, if you set the resource usage sampling 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 sampling interval. The AMP/PE and node 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 sampling period. All users share the data, which is used to generate responses to both queries and CONTINUE requests.Session-Level Monitoring Session-level monitoring tasks return the following information: • 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 As the number of sessions, nodes, AMPs, and PEs you monitor increases, system performance may start to decrease. Session-level utilization data is collected cumulatively. The sampling period is used to limit the frequency at which cumulative data is updated. For example, if you set the session usage sampling interval to 60 seconds and issue a MONITOR SESSION request, session-level usage18 Workload Management API: PM/API and Open API
  19. 19. Chapter 1: Workload Management Concepts and Features Teradata Dynamic Workload Management Features data is cumulatively totaled and updated every 60 seconds. The session-level data reported includes data for the beginning 60 seconds as well as for subsequent intervals.Monitoring 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 3: “PMPC APIs.”Teradata Dynamic Workload ManagementFeatures Teradata Dynamic Workload Management 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). 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. Teradata Dynamic Workload Management is implemented with two components related to Teradata DWM rules: • A client component that provides a graphical user-interface for rules configuration (for example, Teradata Manager and Teradata Dynamic Workload Manager [Teradata DWM]). • A server component within Teradata Database that enforces the rules. It provides database administrators the ability to regulate system events through an event/state methodology (where an event is any condition or indication that is pertinent to workload management and a state is a complete set of working values for a rule set). Teradata Dynamic Workload Management uses events to manage a system. These events are separated into two classes: system conditions (SysCon) and operating environments (OpEnv). Events are found under System Regulation in Teradata Dynamic Workload Manager (Teradata DWM) and provide the following functionality: • Detect various hardware failures • Monitor the system flow control and AWT thresholdsWorkload Management API: PM/API and Open API 19
  20. 20. Chapter 1: Workload Management Concepts and FeaturesTeradata Dynamic Workload Management Features • Change the state of the system that in turn can automatically adjust throttle values of rules • Declare user-defined events that can change the system state When event combinations (that is, one or more events) occur, the variable attributes of Teradata Dynamic Workload Management rules defined by the database administrator can be affected. The behavior of the rules can also be affected through interfaces to Teradata Dynamic Workload Management, or through Teradata Manager. The defined set of rules cause the database to classify and prioritize incoming requests. The database delays or denies the processing of some requests when system activity levels are too high to make the most efficient use of database resources and, therefore, enhance system performance. For more information about event classes, states, rule sets, and event combinations, see Teradata Dynamic Workload Manager User Guide. The following table describes the three categories of Teradata Dynamic Workload Management rules. Category Name Description 1 Filters Denies requests based on the following: • The database object the query is attempting to access • The database resources required to process the query Filters are state-based; that is, any change to the state of the system can cause the Category 1 rule to be enabled or disabled. For details, see Teradata Dynamic Workload Manager User Guide. When the request is restricted by a filter, it is rejected by the database and an error message is returned to the user. Note: Filter rules are checked first by the system. For example, if a query passes those rules defined, then it is permitted to run. 2 Throttles Limits the number of enabled: • Active sessions • Query requests • Group or global objects, where group is all users associated with an account or profile and global is the account or profile • Utilities, for example: FastLoad, MultiLoad, FastExport and Teradata Archive /Recovery (ARC) Throttles are state-based; that is, any change to the state of the system can cause the Category 2 rule to be enabled or disabled or cause it to adjust the limit itself. Throttles are checked after filters.20 Workload Management API: PM/API and Open API
  21. 21. Chapter 1: Workload Management Concepts and Features Teradata Dynamic Workload Management Features Category Name Description 3 Workload Classification Groups requests based on their operational properties. The (also called Workloads definition of workload class requires the specification of or Workload several groups of parameters, for classification, execution, Definitions [WDs]) exceptions, and logging aspects of the workload class, as well as any new Priority Scheduler parameters. Through interfaces to Teradata Dynamic Workload Management, database administrators can: • Apply updates to rule categories • 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 Dynamic Workload Management rules and rule sets • Review statistics on how Teradata Dynamic Workload Management rules are affecting request processing • Enable or disable filter or throttle rules, and update the 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 examples on performing these functions, see “Workload Management API Examples” on page 25. The information available to applications is collected and stored by the diswqm task. You can request this information at any time. However, depending on the API issued, some of the APIs may be restricted by what category of Teradata Dynamic Workload Management is currently enabled. For example, if the data requested by a specific interface is not available because the corresponding rule category is disabled, then an error is returned. For more information about the rules and detailed set-up and operation of Teradata DWM, see Teradata Dynamic Workload Manager User Guide. Most interfaces to Teradata Dynamic Workload Management require that Category 2 or 3 rules are enabled in Teradata DWM for the request to succeed. To determine if the required rules category is enabled, do the following: • Execute the TDWMInquire SQL interface. If the error code 3302 returns, then the required category is disabled. • If the category is disabled, you must use Teradata DWM to enable the category. To learn more about these interfaces, see Chapter 4: “Teradata Dynamic Workload Management APIs.”Workload Management API: PM/API and Open API 21
  22. 22. Chapter 1: Workload Management Concepts and FeaturesQuery Banding FeaturesQuery Banding 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 single quotation marks 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: • 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. • 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. For Teradata Dynamic Workload Management, query band name-value pairs can be associated with filter rules and defined as workload classification attributes. • 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.22 Workload Management API: PM/API and Open API
  23. 23. Chapter 1: Workload Management Concepts and Features System PMPC Applications Examples • The name and value pairs in the query band. • The value of the specified name in the current query band. For examples on performing these functions, see “Query Band API Examples” on page 26. To learn more about these interfaces and how to retrieve query bands, see Chapter 5: “Query Band APIs.”System PMPC Applications Examples This section explains two advanced examples of potential job control support applications that use the Performance Monitor: • 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 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 ResourceWorkload Management API: PM/API and Open API 23
  24. 24. Chapter 1: Workload Management Concepts and FeaturesSystem PMPC Applications Examples 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. 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.24 Workload Management API: PM/API and Open API
  25. 25. Chapter 1: Workload Management Concepts and Features Workload Management API Examples • 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.Workload Management API Examples The following examples show how the interfaces to System PMPC and Teradata Dynamic Workload Management are used.Examples Using System PMPC APIs The following table describes the different uses of the System PMPC APIs. You can ... To ... execute the MonitorMySessions and the display only your running queries. MonitorSQLText functions execute the MonitorSession and AbortSessions create a query that aborts queries submitted by a functions 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 change the Account string to $HReport of all SetSessionAccount functions active sessions with an account string of $MReport. execute the MonitorSession or MonitorSQLText display the SQL of all active sessions that have functions run over 20 minutes. select the blocked fields of the MonitorSession display the block information of all blocked function sessions.Examples Using Teradata Dynamic Workload Management PMPC APIs The following table describes the different uses of Teradata Dynamic Workload Management PMPC APIs. You can execute the .. To ... TDWMSummary function display the current workload summary statistics. TDWMThrottleStatistics function display the current delay queue statistics.Workload Management API: PM/API and Open API 25
  26. 26. Chapter 1: Workload Management Concepts and FeaturesQuery Band API Examples You can execute the .. To ... MonitorSession and TDWMGetDelayedQueries display all sessions, for example, on delay queue function 1011. TDWMEventStatus function display all active events. TDWMGetDelayedQueries and release all delayed queries for a specified TDWMReleaseDelayedRequest functions 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 system condition or operating environment on the system to adjust the throttles and Priority Scheduler Facility weights to handle the other dual active system being down. MonitorSession and TDWMAssignWD change the workload to WD-Report-High of all functions active requests with a workload of WD-Report- Low.Query Band API Examples The following table describes the different uses of the query band APIs. You can use .. To ... MONITOR QUERYBAND or return the concatenated query band for session MonitorQueryBand 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.26 Workload Management API: PM/API and Open API
  27. 27. Chapter 1: Workload Management Concepts and Features API CategoriesAPI Categories The workload management APIs are grouped into three categories: • System PMPC • Teradata Dynamic Workload Management • Query Bands These categories describe the different System PMPC, Teradata Dynamic Workload Management, and Query Banding functionality and the interfaces used to perform them.System PMPC 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. THEN use the following SQL OR use the following CLIv2 IF you want to ... interface... interface ... abort any outstanding “AbortSessions” on page 218 “ABORT SESSION” on page 54 requests or transactions of or one or more sessions, or optionally log those sessions “AbortListSessions” on off Teradata Database page 220 return the name of a user, by “IdentifySession” on page 224 “IDENTIFY” on page 67 session, who is causing a block return the name of the locked “IdentifyTable” on page 225 “IDENTIFY” on page 67 table return the name of the “IdentifyUser” on page 226 “IDENTIFY” on page 67 specified user ID who is causing a block. return information about “MonitorAWTResource” on “MONITOR AWT AMP Worker Task (AWT) page 227 RESOURCE” on page 75 usage return the session “MonitorMySessions” on — information for the current page 231 user on the current host collect overall information on “MonitorPhysicalConfig” on “MONITOR PHYSICAL node availability. Node status page 245 CONFIG” on page 82 information is returned for all nodes in the system collect node resource usage “MonitorPhysicalResource” on “MONITOR PHYSICAL data page 247 RESOURCE” on page 88Workload Management API: PM/API and Open API 27
  28. 28. Chapter 1: Workload Management Concepts and FeaturesAPI Categories THEN use the following SQL OR use the following CLIv2 IF you want to ... interface... interface ... collect global summary “MonitorPhysicalSummary” on “MONITOR PHYSICAL information, such as CPU, page 257 SUMMARY” on page 108 disk, and BYNET usage; rate information, and current software release and version number return current status and “MonitorSession” on page 262 “MONITOR SESSION” on activity information page 116 returns the duration of the “MonitorSessionRate” on “MONITOR SESSION” on sample period in seconds page 276 page 116 return data about the “MonitorSQLCurrentStep” on “MONITOR SQL” on page 147 currently running step page 278 return the step information “MonitorSQLSteps” on “MONITOR SQL” on page 147 for a particular session page 280 return the SQL text string of “MonitorSQLText” on page 283 “MONITOR SQL” on page 147 the running request collect information on virtual “MonitorVirtualConfig” on “MONITOR VIRTUAL processor (vproc) availability page 285 CONFIG” on page 159 return performance “MonitorVirtualResource” on “MONITOR VIRTUAL information for each AMP or page 287 RESOURCE” on page 166 PE, on a vproc by vproc basis return the summary “MonitorVirtualSummary” on “MONITOR VIRTUAL information on system page 297 SUMMARY” on page 188 utilization such as disk and CPU usage, AMP and PE usage, the number of logged on sessions, and rate information set the following rates: “SetResourceRate” on page 305 “SET RESOURCE RATE” on page 199 • VprocMonitor • VprocLogging • ResMonitor • ResLogging change the account string for “SetSessionAccount” on “SET SESSION ACCOUNT” on a session or for the next page 308 page 204 request. set the system-wide and local “SetSessionRate” on page 310 “SET SESSION RATE” on rates for updating session- page 209 level statistics within memory28 Workload Management API: PM/API and Open API
  29. 29. Chapter 1: Workload Management Concepts and Features API CategoriesTeradata Dynamic Workload Management The following table describes the interfaces of Teradata Dynamic Workload Management that are used to return workload definitions, delayed query lists, summary data, and statistics; and update the components stored in tdwm, a database shared by Teradata Dynamic Workload Manager and Teradata Query Scheduler. For more information about tdwm, see Teradata Dynamic Workload Manager User Guide. THEN use the following SQL OR use the following CLIv2 IF you want to ... interface... interface ... change the workload a session “TDWMAssignWD” on “TDWM WD ASSIGNMENT” or request is assigned to page 357 on page 345 activate updates to the rules “TDWMApply” on page 355 — in one or more Teradata Dynamic Workload Management categories abort a request or utility “TDWMAbortDelayedRequest” “TDWM DELAY REQUEST session on the Teradata on page 353 CHANGE” on page 325 Dynamic Workload Management delay queue activates or deactivates a user- “TDWMEventControl” on “USER EVENT CONTROL” defined event page 359 on page 349 list all objects that make up “TDWMEventMapping” on “EVENT STATUS” on the system state page 361 page 313 return the currently defined “TDWMEventStatus” on “EVENT STATUS” on events page 363 page 313 report if each category is “TDWMInquire” on page 372 — active or not release a request or utility “TDWMReleaseDelayedRequest “TDWM DELAY REQUEST session on the Teradata ” on page 378 CHANGE” on page 325 Dynamic Workload Management delay queue return a list of the workload “TDWMListWDs” on page 373 “TDWM LIST WD” on definitions page 329 return the object delay queue “TDWMGetDelayedQueries” on “TDWM STATISTICS” on and the workload delay queue page 367 page 333 return the utility delay queue “TDWMGetDelayedUtilities” on “TDWM STATISTICS” on page 370 page 333 display the statistics on the “TDWMLoadUtilStatistics” on “TDWM STATISTICS” on utilities that are active in the page 375 page 333 systemWorkload Management API: PM/API and Open API 29

×