Teradata Database. Utilities - Volume 2 G - S

Transcription

1 Teradata Database Utilities - Volume 2 G - S Release 12.0 B A March 2010

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 Like This 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 United States 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 other countries. 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 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, 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 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 by Teradata Corporation. All Rights Reserved.

3 Preface Purpose This book, Utilities, describes the utility programs that support the Teradata Database and consists of three volumes: Volume 1 includes utilities A-F. Volume 2 includes utilities G-S. Volume 3 includes utilities T-Z. Topics covered in this book include utilities G through S. Use this book in conjunction with the other volumes. Chapter names reflect the utility common name followed by the name of the executable utility program enclosed in parentheses, for example, Control GDO Editor (ctl). Use the executable program name to start the utility from the command line or Database Window. Some utilities are restricted to running on specific platforms. Refer to the User Interfaces section of each chapter to determine the platforms that support each utility. Audience The utilities described in this book are used primarily by Teradata Support Center field engineers, Teradata Database developers, System Test and Verification, and Teradata Database system administrators. For example, these utilities are used to display control parameters, display DBS control record fields, find and correct problems within the file system, initialize the Teradata Database, rebuild tables in the database, and manage the virtual processors (vprocs). These utilities are used to abort transactions and processes; monitor system performance, resources, and status, perform internal system checking, and perform system configuration, initialization, recovery, and tuning. Users should also be familiar with the Teradata Database console running the Database Window (DBW) and your client (host) system. For experienced utilities users please see the simplified command descriptions in the Utilities Quick Reference. This book provides the syntax diagrams and a brief description of the syntax variables for each Teradata Database utility. Supported Software Release This book supports Teradata Database Utilities 3

4 Preface Prerequisites Prerequisites You should be familiar with using the Database Window (DBW) to run the other utilities. In addition, you might want to review the following related books: Graphical User Interfaces: Database Window and Teradata MultiTool Performance Management Resource Usage Macros and Tables Platform-dependent Teradata Database Installation/Upgrade/Migration documents For detailed information about the Archive and Recovery, FastExport, FastLoad, MultiLoad, and Teradata Parallel Data Pump utilities, see the following client utilities books: Teradata Archive/Recovery Utility Reference Teradata FastExport Reference Teradata FastLoad Reference Teradata MultiLoad Reference Teradata Parallel Data Pump Reference Changes to This Book This volume includes the following changes to support the current release: Date Utility Description Teradata Database 12.0 September 2007 dbschk (part of the Resource Check Tools) Gateway Control (gtwcontrol) Locking Logger (dumplocklog) gdoviewer All dbschk options can be set from the command line. New command-line parameters are -job, -logfile, -n (iterations), -save, and -trigger. The dbschkrc file is no longer used to store custom settings. Instead, use the -save command-line option to save the current settings as custom default values. Defaults are in effect for dbschk run from any node of the system. dbschk no longer stores nor writes its current settings to a GDO. -logfile must be explicitly set to stdout to have dbschk send output to the screen. The -F and -b options are deprecated, and should not be used. Added information on new -o and -z options that allow users to define and apply custom default values for gtwcontrol settings. The DELAY column of a lock log report does not show value to nearest hundredth of a second. It shows to the nearest second. Removed chapter, older, obsolete utility. There are other tools, such as DBS Control, ctl, xctl, and Gateway Global, that allow access and modification of GDOs. 4 Utilities

5 Preface Changes to This Book Date Utility Description Teradata Database 12.0 September 2007 (continued) Priority Scheduler (schmon, xschmon) Query Session (qrysessn) Reconfiguration Utility (reconfig) Recovery Manager (rcvmanager) System Initializer (sysinit) Added documentation for new -d, -T, -P, and delay [reps] options. Rewrote some descriptions to clarify information and relationships. Removed documentation for the -X option, which is intended mainly for internal use, and the all option for -a, -b, and -p, which is potentially confusing and not particularly helpful. Noted that relative weights can be no less than one. Calculated relative weights less than one are converted to one. Consequently the sum of relative weights can be somewhat greater than 100. Noted that fractions are truncated as the final step in calculating relative weights, so the sum of relative weights can be somewhat less than 100. Noted that xschmon will be removed from subsequent releases of Teradata Database. Users are directed instead to Priority Scheduler Administrator, for a graphical user interface to Priority Scheduler. Added information on new SESDELAYED session state. Added information on new QTDELAYED session state. Updated documentation for DELAYED session state. Noted that reconfig will not run if online archive logging is enabled for any database object. Removed references to DBC.HW_Event_Log. Removed references to F7 help, which is not available. Updated Japanese language support information. Object names are stored in the Data Dictionary as UNICODE. Did some chapter reorganization. Updated examples. Utilities 5

6 Preface Changes to This Book Date Utility Description Teradata Database V2R6.2 September 2006 Gateway Control Gateway Global Lock Display Locking Logger modmpplist Priority Scheduler Recovery Manager Resource Check Tools Reorganized option table to separate out debugging options. Rewrote and reorganized some sections including information on hex formatting of non-ascii user names. Updated examples and reiterated information about hash mark (#)notation. Rewrote introduction. Rewrote some sections for clarity. New options: -m -L displays information related to the CPU usage limits imposed on Allocation Groups. -n shows node names for min/max resource usage -s shows resource usage statistics including median and standard deviation. Also shows frequency range table that shows number of nodes falling into different range groups -T sets or displays the time period over which delay statistics are collected. -V turns on verbose mode, showing inactive nodes (nodes that report zero usage), and takes those nodes into account when making usage statistic calculations. System information now displayed with allocation group portion of output under AG 200. Also shows more information for system work. I/O Concurrency feature removed from Windows and Linux versions (change to schmon -t and examples of other options that referred to it). Rewrote portions for clarity and to update information. Noted that rollback can only be cancelled on tables appearing in rollback table list (LIST ROLLBACK TABLES command). Updated information regarding use of dbschkrc file and job option. All utilities Added new User Interfaces section, with pointer to new appendix for information on starting the utilities on different platforms and interfaces. This reorganization replaces the Starting and Exiting on [platform] sections. Retitled chapters to reflect both common utility names and utility program name 6 Utilities

7 Preface Changes to This Book Date Utility Description Teradata Database V2R6.1 November 2005 Gateway Control Utility inittpa Lock Display Utility Priority Scheduler Recovery Manager Resource Check Tools The following information has been added: Two new options have been added to the gateway control utility, they are as follows: connectiontimeout, which controls the logon message timeout in seconds. keepalivetime, which controls the frequency in seconds of sending a keepalive message on an idle virtual circuit. Changed the gateway control utility External Authentication option to -a ExternalAuthentication. This option now supports all platforms. The inittpa utility is no longer available for starting and stopping the TPA on all nodes in an MPP system. You can use the following commands to start and stop the TPA in an MPP system: To start the TPA, enter: pcl -s /etc/init.d/ tpa start To stop the TPA on one node, enter: /etc/init.d/tpa stop To stop the TPA on all nodes, enter: tpareset -x <reason> The lock display output now shows the subtable ID and row hash (or row range) lock indication. The following information has been added: Added new procedure to the schmon - p -x option on how to delete and recreate the performance group (PG) if the following error is reported: Performance Group is in remove state The anti-starvation mechanism schmon -t option is enabled by default on MP-RAS. The LIST STATUS command with the <proc-id> option now displays all the tables that need to be rebuilt and the following information: Total rows Total bytes Rebuild speed in bytes per second Estimated rebuild time Added the trigger option to the dbschkrc file. This option allows you to set a trigger to be executed when the responsiveness of the Database System (DBS) goes above the expected time limit. Utilities 7

8 Preface Additional Information Additional Information Additional information that supports this product and Teradata Database is available at the following Web sites. Type of Information Description Source Overview of the release Information too late for the manuals Additional information related to this product CD-ROM images Ordering information for manuals General information about Teradata The Release Definition provides the following information: Overview of all the products in the release Information received too late to be included in the manuals Operating systems and Teradata Database versions that are certified to work with each product Version numbers of each product and the documentation for each product Information about available training and support center Use the Teradata Information Products web site to view or download the most recent versions of all manuals. Specific manuals that supply related or additional information to this manual are listed. This site contains a link to a downloadable CD-ROM image of all customer documentation for this release. Customers are authorized to create CD-ROMs for their use from this image. Use the Teradata Information Products web site to order printed versions of manuals. 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 Click General Search. In the Publication Product ID field, enter 1725 and click Search to bring up the following Release Definition: Base System Release Definition B K Click General Search, and do one of the following: In the Product Line field, select Software - Teradata Database for a list of all of the publications for this release, In the Publication Product ID field, enter the book number of the book for which you are searching: Click General Search. In the Title or Keyword field, enter CD-ROM, and click Search. Click How to Order under Print & CD Publications. Teradata.com 8 Utilities

9 Preface References to Microsoft Windows and Linux References to Microsoft Windows and Linux This book refers to Microsoft Windows and Linux. For Teradata Database 12.0, these references mean the following: Windows is Microsoft Windows Server bit and Microsoft Windows Server bit. Linux is SUSE Linux Enterprise Server 9 and SUSE Linux Enterprise Server 10. Teradata plans to release Teradata Database support for SUSE Linux Enterprise Server 10 before the next major or minor release of the database. Therefore, information about this SUSE release is included in this document. The announcement regarding availability of SUSE Linux Enterprise Server 10 will be made after Teradata Database 12.0 GCA. Please check with your account representative regarding SUSE Linux Enterprise Server 10 availability in your location. Utilities 9

10 Preface References to Microsoft Windows and Linux 10 Utilities

11 Table of Contents Preface Purpose Audience Supported Software Release Prerequisites Changes to This Book Additional Information References to Microsoft Windows and Linux Chapter 1: Gateway Control (gtwcontrol) Gateway Host Groups Gateway Log Files Gateway Control Options Changing Maximum Sessions Per Node Chapter 2: Gateway Global (gtwglobal, xgtwglobal) Gateway Global Commands Overview User Names and Hexadecimal Notation Specifying a Host Displaying Network and Session Information Administering Users and Sessions Performing Special Diagnostics Logging Sessions Off Using KILL Getting Help Gateway Global Commands DISABLE LOGONS DISABLE TRACE DISCONNECT SESSION DISCONNECT USER DISPLAY DISCONNECT Utilities 11

12 Table of Contents DISPLAY FORCE DISPLAY GTW DISPLAY NETWORK DISPLAY SESSION DISPLAY STATS DISPLAY TIMEOUT DISPLAY USER ENABLE LOGONS ENABLE TRACE FLUSH TRACE HELP KILL SESSION KILL USER SELECT HOST SET TIMEOUT Gateway Global Graphical User Interface Chapter 3: Lock Display (lokdisp) Lock Modes Lock Display Utility Commands BLOCKERS DB HELP QUIT ROWHASH ROWRANGE TABLE TRAN Chapter 4: Locking Logger (dumplocklog) Transaction Lock Log Information LockLogger DBS Control Fields Lock Logger Table Requirements Lock Log Tables Utilities

13 Table of Contents Hexadecimal and Non-Standard Names Support Quotation Marks in Object Names Producing a Lock Log Report Example Log Tables Reducing the Size of the Tables Reducing the Size of the Lock Log Table Reducing the Size of the DBC.EventLog Table Inserting Rows Determining the Blocked User Locking Logger Messages Chapter 5: Modify MPP List (modmpplist) modmpplist Commands DISPLAY LIST OFF id_list ON id_list QUIT WRITE Running External Commands Chapter 6: Priority Scheduler (schmon, xschmon) Overview Using Priority Scheduler Resource Partitions Performance Groups Performance Periods Allocation Groups Expedite Attribute Resource Accounting AMP Worker Task (AWT) Reservations and Limits schmon Utility schmon -a schmon -b Utilities 13

14 Table of Contents schmon -c schmon -d schmon -f schmon -h schmon -l schmon -m schmon -M schmon -p schmon -s schmon -t schmon -T schmon -w xschmon Utility Chapter 7: Query Configuration (qryconfig) About Query Configuration Vprocs and Physical Processors Display Options Query Configuration Options ALL Option Processors Option Online Processors or Offline Processors Options AMPs Option Online AMPS or Offline AMPs Options PEs Option Online PEs and Offline PEs Options Getting HELP Chapter 8: Query Session (qrysessn) Query Session States Parent and Child Sessions Query Session Displays Session State Display State Information Displays ABORTING State ACTIVE State Utilities

15 Table of Contents BLOCKED State DELAYED State IDLE State INDOUBT State INDOUBT PARSING State PARSING State QTDELAYED State QUIESCED ABORT State QUIESCED ABORT WITH LOGOFF State QUIESCED INDOUBT State RESPONSE State SESDELAYED State Archive and Recovery Sessions State Displays FastLoad Sessions State Displays MultiLoad Sessions State Displays FastExport Sessions State Displays Chapter 9: Reconfiguration Estimator (reconfig_estimator) Chapter 10: Reconfiguration Utility (reconfig) Before Starting Disabling Logons Enabling Logons About Reconfiguration Vprocs Physical Processors Configuration Utility Activities New Configuration Map Reconfiguration Utility Activities MOVE AMP Operation Fatal AMPs During a Move-AMP Operation Effects on Journal Tables Timestamps Reconfiguration Utility Process Reconfiguration Utility Commands RECONFIG STATUS Utilities 15

16 Table of Contents STOP Error Messages Reconfiguration Example Chapter 11: Recovery Manager (rcvmanager) Prerequisites Assigning Priority Levels Online Transaction Recovery Transaction Recovery Sequence Multiple Recovery Sessions Deferred Transaction Recovery Down AMP Recovery Startup/Restart Messages Restarts Cancelling Rollback on Tables Recovery Manager Commands CANCEL ROLLBACK ON TABLE DEFAULT PRIORITY HELP LIST CANCEL ROLLBACK TABLES LIST LOCKS LIST ROLLBACK TABLES LIST STATUS LIST STATUS proc-id QUIT REBUILD/RECOVERY PRIORITY ROLLBACK SESSION...PERFORMANCE GROUP Chapter 12: Resource Check Tools (dbschk, nodecheck, syscheck) Resource Check Tools Utilities dbschk nodecheck Creating a Log File syscheck Utilities

17 Table of Contents syscheckrc File Creating a syscheckrc File Chapter 13: RSS Monitor (rssmon) Monitoring Configuration File Standard Configuration Files Customized Configuration Files Displaying ResUsage Data Chapter 14: Show Locks (showlocks) Host Utility Locks Interpreting the Showlocks Display Conflicts Chapter 15: System Initializer (sysinit) Initializing Teradata Database with System Initializer Globally Distributed Objects Configuration Maps Running System Initializer Configuration and Reconfiguration Utilities Examples Appendix A: How to Read Syntax Diagrams Syntax Diagram Conventions Appendix B: Starting the Utilities MP-RAS Starting Utilities from Database Window Starting Utilities from the Command Line Utilities 17

18 Table of Contents Windows Starting Utilities from Teradata MultiTool Starting Utilities from Database Window Starting Utilities from the Teradata Command Prompt Linux Starting Utilities from Teradata MultiTool Starting Utilities from Database Window Starting Utilities from the Command Line MVS and VM Starting Utilities from HUTCNS Appendix C: Session States, Events, and Actions Session State Definitions MP-RAS Windows and Linux Session Event Definitions MP-RAS Windows and Linux Session Action Definitions MP-RAS Windows and Linux Glossary Index Utilities

19 CHAPTER 1 Gateway Control (gtwcontrol) The Gateway Control utility, gtwcontrol, is a tool that you use to modify default values in the fields of the gateway control Globally Distributed Object (GDO). On MP-RAS systems, gateways are limited to one per node. On Windows and Linux systems, multiple gateways per node are supported if the gateways belong to different host groups and listen on different IP addresses. Audience Users of Gateway Control include the following: Field Service engineers Network administrators Teradata Database system administrators Users should be familiar with the configuration of the Teradata Database and performance of the gateway. User Interfaces gtwcontrol runs on the following platforms and interfaces: Platform MP-RAS Windows Linux Interfaces Command line (gtwcontrol is located in the /tgtw/bin directory.) Database Window Command line ( Teradata Command Prompt ) Database Window Command line Database Window For general information on starting the utilities from different platforms and interfaces, see Appendix B: Starting the Utilities. Utilities 19

20 Chapter 1: Gateway Control (gtwcontrol) Syntax Syntax Use the following syntax to run Gateway Control: gtwcontrol option(s) Options are prefaced with hyphens. For convenience, multiple options that do not require values can be passed after a single hyphen: gtwcontrol -dacex Options that require values, however, should each have a hyphen: gtwcontrol -a off -k 20 For a list of options and their explanations, see Gateway Control Options on page 23. Typing: gtwcontrol -h causes Gateway Control to display a list of available options on screen. Gateway Host Groups The following table describes gateway host groups on MP-RAS, Windows, and Linux. On... The gateway... MP-RAS Windows Linux runs in the control vproc on that node. As a result, only one gateway can exist per node. runs in its own vproc. Therefore, multiple gateways can exist on a node. runs in its own vproc. Therefore, multiple gateways can exist on a node. All gateways that belong to the same host group (HG) defined in the vconfig file have a single Assign Task that manages a set of PEs. The set of PEs that the Assign Task manages is determined by using the host number (HN) in the vconfig file and mapping the HN to the HN defined by the Configuration utility. The Assign Task is responsible for assigning a new session to the Parsing Engine (PE) having the least number of sessions associated with that PE. For more information on the host group and host number, see the ADD HOST command in the Configuration utility. 20 Utilities

21 Chapter 1: Gateway Control (gtwcontrol) Gateway Host Groups Example 1 Example 1 represents an MP-RAS system. NODE 1 NODE 2 PE HN = 1 PE HN = 1 PE HN = 2 PE HN = 2 Gateway HGID 1 Gateway HGID 2 The gateway (assign task) on node 1 manages sessions for PEs and The gateway on node 2 manages sessions for PEs and In example 1, all sessions connected to node 1 are processed by PEs and The gateway looks for all connections which open to port 1025, or, in TCP/IP terms, * This configuration supports multiple LAN cards, which could be multihomed. The network administrator must make sure that a distinct name exists for node 1 and node 2 (such as, NODE1COP1 and NODE2COP1). Example 2 Example 2 represents a Windows system running multiple gateways on each node. NODE 1 NODE 2 PE HN = 1 PE HN = 1 PE HN = 2 PE HN = 2 Gateway (8192) HGID 1 Gateway (8191) HGID Gateway (8190) HGID 2 Gateway (8189) HGID In example 2, the same PE configuration exists as shown in Example 1. However, the configuration is extended to support multiple host groups per node. Each gateway must have a separate set of IP addresses. In example 2, the gateway running in vproc 8192 only looks for network connections on IP port The gateway in vproc 8190 only looks for network connections on IP port 3. Example 2 does not require separate LAN cards, but it does require that the IP addresses be unique. In example 2, the network administrator would create the following host names/ip entries: hgid1_cop hgid1_cop hgid2_cop hgid2_cop What are the advantages of the configuration in Example 2 over that in Example 1? In example 1, if node 2 is down, then a user cannot connect to PEs and In example 1, sufficient nodes must be available to support the configuration, even if it goes down. In example 2, the problem does not arise, since each node has a different host group. Utilities 21

22 Chapter 1: Gateway Control (gtwcontrol) Gateway Log Files Why would you want to define multiple host groups? If you submit very similar SQL requests and have a separate host group to process those requests, you would get a better cache hit rate. By controlling where the PEs and gateways for a host group are located and controlling which jobs go to which host groups, you might be able to balance the gateway and PE workload better. Gateway Log Files Function The gateway log files include the assign and connect files. Depending on the type of operating system running on your system, these files are located in a default directory as described in the table below. On... The Default Directory is... MP-RAS Windows Linux /tmp Note: The location of the log files on MP-RAS can be changed by using the -p option of gtwcontrol. the temporary directory you specified for PDE at installation time. Note: On Windows, the assign and connect files are combined into a single file. the temporary directory you specified for PDE at installation time. Note: On Linux, the assign and connect files are combined into a single file. Log File Naming Conventions Gateway Control uses the following conventions to generate log file names. MP-RAS g[a c]ydddhhmmsslog where: Name element g [a c] Y DDD hh Meaning Literal g character. All Gateway Control log files have names beginning with g. The second character of the log file name is a, for assign process logs, or c, for connect process logs. The last digit of the four-digit year. The day number within the year. Hour of the day (24-hour clock). 22 Utilities

23 Chapter 1: Gateway Control (gtwcontrol) Gateway Control Options Name element mm ss log Meaning Minute of the hour. Second of the minute. Literal log characters. All Gateway Control log files have names ending with log. Examples: ga log gc log Windows and Linux Gtw_vvvvv_YYYYMMDDhhmmss.log where: Name element Gtw vvvvv YYYY MM DD hh mm ss log Meaning Literal Gtw characters. All Gateway Control log files have names beginning with Gtw. Gateway vproc number. The four-digit year. Number of the month within the year. Number of the day within the month. Hour of the day (24-hour clock). Minute of the hour. Second of the minute. Literal log characters. All Gateway Control log files have names ending with file extension.log. Example: Gtw_08192_ log Gateway Control Options Gateway Control options are case sensitive and must include the hyphen prefix. The following example gives the syntax for the help option which lists the syntax for all other gateway control options: Utilities 23

24 Chapter 1: Gateway Control (gtwcontrol) Gateway Control Options gtwcontrol -h When a gateway option requires a field value, that option includes a field name where you define the value. For example, to select the host group number 1 on which to perform an action, use the option -g Hostnumber and type: gtwcontrol -g 1 where the Hostnumber for the option is 1. You can combine options by typing them, separated by a space. For example, to set the maximum number of sessions for host group 1 to 600, type: gtwcontrol -g 1 -s 600 The following table describes the options for the Gateway Control utility, and indicates the operating systems that support each option. Option Description Operating System -a ExternalAuthentication Enables or disables external authentication. The settings are as follows: All OFF rejects external authentication and accepts traditional logons. ON accepts both external authentication and traditional logons. ONLY accepts external authentication and rejects traditional logons. The factory default is ON. For additional information on External Authentication, see Security Administration. -b AllowDeprecatedLogons Note: This option is deprecated, and should not be used. Enables or disables encryption of the logon. The settings are as follows: NO allows only encrypted logons. YES allows both unencrypted (deprecated) and encrypted logons. The factory default is NO, only encrypted logons allowed. For additional information on encryption, see the following: Database Administration Introduction to Teradata Warehouse Messages Security Administration All 24 Utilities

25 Chapter 1: Gateway Control (gtwcontrol) Gateway Control Options Option Description Operating System -c connectiontimeout Controls the logon message timeout in seconds. The Gateway terminates any session for which the message in the logon sequence is not received in a timely manner. The turnaround time for any message during the logon should be less than the value in the connectiontimeout setting. All The value ranges from 5 to 3600 seconds. The factory default is 60 seconds. -d Displays current setting of the Gateway GDO. All -e Eventcnt Specifies the number of event trace entries. The factory default is 512 on MP-RAS, and 500 on Windows and Linux. -F Note: This option is deprecated, and should not be used. Toggles append domain names for authentication schemes in which domain names are required to define user identities uniquely. The factory default is OFF. For information about authentication methods, see Security Administration. -f Logfilesize Specifies the maximum log file size. On Windows and Linux, the valid range is 1000 through The factory default is g Hostnumber Specifies a host group to which the host-specific settings in this invocation of gtwcontrol will be applied. If you do not specify this option, the host settings are applied to all host groups. All All All All Hostnumber is an integer from 0 through 1023 that identifies a host group. The host-specific options are: -a, -b, -c, -i, -k, -m, -r, -s, -t, -A, -F, -C (on Windows and Linux only), -S (on MP-RAS only), and -T (on Windows and Linux only). -h Displays help on gtwcontrol options. All -i InitialIothreads Specifies the number of threads of each type that are started initially for the processing of LAN messages. When adjusting the number of threads to match the load, the number of threads of each type will never be reduced below this number. Windows and Linux Two types of threads exist: One handles traffic from the client (that is, TCP/IP connections). One handles traffic from the database (that is, the PDE msgsystem). The factory default is 5. Utilities 25

26 Chapter 1: Gateway Control (gtwcontrol) Gateway Control Options Option Description Operating System -k keepalivetimeout Specifies how long the connection between the gateway and a client remains idle before the operating system begins probing to see if the connection has been lost. All keepalivetimeout specifies the time in minutes, and can be any integer from 1 through 120. When a connection has been idle for the specified number of minutes, the gateway s operating system will send a keepalive message over the connection to see if there is a response from the client s operating system. If there is no response, the gateway s operating system repeats the probe several times. If there continues to be no response from the client s operating system, the gateway s operating system closes the connection, disconnecting the session using it. The specific number of probes and the time between probes vary by operating system type. Some systems allow these values to be changed when networking is configured. If these values have not been changed, it typically takes about 10 minutes from the first probe until a dead connection is closed. If the keepalivetimeout value is 5, the actual time until the connection is closed is approximately 15 minutes. The factory default is 10 minutes. -L Toggles enable logons. The factory default is ON. All -m MaximumIothreads Specifies the maximum number of threads per type. When adjusting the number of threads to match the load, the number of threads of each type will never be increased above this number. Windows and Linux Two types of threads exist: One handles traffic from the client (that is, TCP/IP connections). One handles traffic from the database (that is, the PDE msgsystem). The factory default is Utilities

27 Chapter 1: Gateway Control (gtwcontrol) Gateway Control Options Option Description Operating System -o default Indicates that the other options specified in this invocation of gtwglobal should be saved as a set of user-defined default values. These defaults take precedence over the factory-set gateway control defaults, and will be used for new host groups and gateway vprocs when the system is reconfigured. All Note: Host groups and vprocs that existed before the reconfiguration retain their previous settings. To apply the custom defaults to all existing host groups and vprocs, use the -z option. gtwcontrol -o default can be run several times to set individual default values or groups of values. Subsequent runs do not cancel previous runs. To clear the user-defined defaults and restore the factory defaults, use the -Z option together with -o default. Note: The -o option cannot be used together with the -g or -v options. -p Pathname Specifies path to gateway log files. The factory default is /tmp. MP-RAS -r IoThreadCheck Determines the frequency in minutes that the gateway checks to see if all the threads are busy. Windows and Linux If they are all busy, a new thread of the appropriate type is started unless it will exceed the maximum number of threads set by the -m option. If more than one thread has not run during the IoThreadCheck period, the gateway stops a thread, unless it will leave fewer threads than are specified by the -i option. Two types of threads exist: One handles traffic from the client (that is, TCP/IP connections). One handles traffic from the database (that is, the PDE msgsystem). The factory default is 10 minutes. -s Sessions Specifies maximum sessions for host group. Limited to Teradata Database system resources. Specifies maximum sessions per vproc. The valid range is 1 through The factory default is t Timeoutvalue Determines how long a disconnected session has to reconnect in minutes. If the client has not reconnected within the specified time period, the client is logged off automatically. MP-RAS Windows and Linux All Note: During this time period, the session still counts against the number of sessions allocated to a PE. The factory default is 20 minutes. Utilities 27

28 Chapter 1: Gateway Control (gtwcontrol) Gateway Control Options Option Description Operating System -v Vprocnumber Specifies a vproc to which the vproc-specific settings in this invocation of gtwcontrol will be applied. If you do not specify this option, the vproc-specific settings apply to all vprocs. Vprocnumber is an integer from 0 through that identifies a vproc. The vproc-specific options are: -C, -D, -E, -H, -J, -K, -M, -O, -R, - S (on Windows and Linux only), -T (on MP-RAS only), -W, and - Y. -z Sets gateway control to apply the user-defined defaults created with the -o option to all current host groups and vprocs. -Z Sets gateway control to apply the original factory defaults to all current host groups and vprocs. If a set of user-defined defaults, created with the -o option exist, they will still be applied to new host groups and vprocs after a reconfiguration. To reset these user-defined defaults to the original factory defaults, so new hosts and vprocs will use the original factory defaults, use the -Z option in conjunction with the -o default option: gtwcontrol -o default -Z All All All Caution: The following options should be used only for debugging the gateway under the direction of Teradata Support Center personnel. Option Description Operating System -l logonname For remote gateway global access. Windows and Linux -A Toggles assign tracing. The factory default is OFF. All -C Toggles connect wait. The factory default is OFF. MP-RAS Toggles connection tracing. The factory default is OFF. Windows and Linux -D Toggles no gtwdie. The factory default is OFF. All -E Toggles event trace. The factory default is OFF. The E event trace does not log the actions. Windows and Linux -H Toggles connect heap trace. The factory default is OFF. All -I Toggles interactive mode. The factory default is OFF. Windows and Linux -J Toggles log LAN errors. The factory default is OFF. Logs any LAN-related errors even when properly handled by the gateway. -K Toggles session ctx lock trace. The factory default is OFF. This option shows the session locking to make the session context multiprocessor safe. Windows and Linux Windows and Linux 28 Utilities

29 Chapter 1: Gateway Control (gtwcontrol) Changing Maximum Sessions Per Node Option Description Operating System -M Toggles message tracing. The factory default is OFF. All -O Toggles output LAN header on errors. The factory default is OFF. Causes an error message to be written to the gateway log file. Windows and Linux -P Toggles assign heap trace. The factory default is OFF. All -R Toggles xport log all. The factory default is OFF. By default, the xport trace does not log every LAN operation. The xport log all options causes all LAN operations to be logged. This option only takes effect if the Y trace is on. Windows and Linux -S Toggles assign wait. The factory default is OFF. MP-RAS Toggles the action log. The factory default is OFF. The S option turns on the action trace. The S option only takes effect if the E trace is on. Windows and Linux -T Toggles connect trace. The factory default is OFF. MP-RAS Toggles allow gateway testing. The factory default is OFF. -U Toggles tdgss trace. The factory default is OFF. Note: The -U option causes tdgss-related errors to be logged into the gateway log file in order to diagnose problems. Windows and Linux All -W Toggles connect and assign wait. The factory default is OFF. MP-RAS Toggles wait for debugger to attach. The factory default is OFF. Windows and Linux -X Toggles xport trace. The factory default is OFF. All -Y Toggles handle trace. The factory default is OFF. Windows and Linux Changing Maximum Sessions Per Node The number of supported sessions on MP-RAS, Windows, and Linux is based on the following: The number of allotted Parsing Engines (PEs) Usage (resources consumed) Number of streams when the Teradata Database system is built (MP-RAS only) If your site runs jobs that are CPU or I/O intensive, you might find that a lower session limit gives better performance. You cannot set the maximum sessions to a negative number. To view the current maximum sessions per node, type: gtwcontrol -d To set the maximum sessions to 1000, type: Utilities 29

30 Chapter 1: Gateway Control (gtwcontrol) Changing Maximum Sessions Per Node gtwcontrol -g 1 -s 1000 where 1 is the number of the host group, and 1000 is the maximum sessions you want. On Windows and Linux, the new limit is effective immediately. On MP-RAS, the following table describes when the new limit takes effect. IF the new maximum session limit is... THEN the new limit takes effect... less than 600 or less than the limit at the last Teradata Database restart (whichever is bigger) more than 600 and more than the limit at the last Teradata Database restart immediately. after the next Teradata Database restart. The current maximum session limit will default to the value at the last Teradata Database restart. gtwcontrol notifies you of the following: Whether a Teradata Database restart is required for the new maximum session limit to become effective The current maximum sessions limit and the new maximum sessions limit if you did not restart the Teradata Database after a change If more sessions are active than the new maximum sessions limit allows, then no new sessions are started. No new sessions can log on until the number of sessions is below the maximum sessions limit. 30 Utilities

31 CHAPTER 2 Gateway Global (gtwglobal, xgtwglobal) The Gateway Global utility, xgtwglobal (gtwglobal on Windows and Linux), allows you to monitor and control the sessions of Teradata Database LAN-connected users. The gateway software runs as a separate operating system task and is the interface between the network and the Teradata Database. Client programs that communicate through the gateway to the Teradata Database can be resident on the Teradata Database system, or they can be installed and running on networkattached workstations. Client programs that run on channel-attached hosts bypass the gateway completely. Teradata Database on MP-RAS supports one gateway per node. Teradata Database on Windows and Linux supports multiple gateways per node. The gateways must belong to different host groups and listen on different IP addresses. The number of supported sessions is based on the following: The number of allotted Parsing Engines (PEs) Usage (resources consumed) Number of streams available when the Teradata Database system is built (MP-RAS only) Each logical network attachment requires at least one PE. Each PE can support up to 120 sessions. When all the PEs in the DBS configuration are offline, Gateway Global exits, and the following message appears: xgtwglobal cannot proceed as no PEs are online. When all of the PEs in some of the host groups in the DBS configuration are offline, then Gateway Global displays the following notice and continues to process information for the host groups with at least one PE online: NOTICE: xgtwglobal cannot process all the host groups as all the PEs on one or more of the host groups are offline. The number of sessions per gateway is defined using the gtwcontrol utility. For information on configuring gateway options, see Chapter 1: Gateway Control (gtwcontrol). Note: Gateway errors are handled in the same manner as other Teradata Database system errors. Utilities 31

32 Chapter 2: Gateway Global (gtwglobal, xgtwglobal) Audience Audience Users of Gateway Global include the following: Field service representatives Network administrators Teradata Database system administrators Users should be familiar with the administration of their network environment and the Teradata Database software. User Interfaces Gateway Global runs on the following platforms and interfaces: Platform MP-RAS (xgtwglobal) Windows (gtwglobal) Linux (gtwglobal) Interfaces Command line (xgtwglobal is located in the /tgtw/bin directory.) Database Window Note: On MP-RAS Gateway Global includes an X11-based graphical user interface. To run the utility without the GUI, use the -nw command-line option. The -nw option is required for running Gateway Global from the Database Window under MP-RAS: start xgtwglobal -nw Command line ( Teradata Command Prompt ) Database Window Command line Database Window For general information on starting the utilities from different platforms and interfaces, see Appendix B: Starting the Utilities. On MP-RAS, Gateway Global can display a windowed graphical user interface (GUI), or can run as a command-line utility. GUI (available on MP-RAS only) In order for Gateway Global to display a GUI, there must be an X server running on the local machine. To run Gateway Global in windowing mode, use the X11 -display option to specify the name or IP address of the current workstation and display. For example: xgtwglobal -display displayspec & where displayspec is the name or IP address of the local machine, followed by a colon and the server number, usually 0 or 0.0. For example: 32 Utilities

33 Chapter 2: Gateway Global (gtwglobal, xgtwglobal) Gateway Global Commands Overview /tgtw/bin/xgtwglobal -display myworkstation.mycompany.com:0.0 & or /tgtw/bin/xgtwglobal -display :0.0 & For more information about using the Gateway Global GUI, see Gateway Global Graphical User Interface on page 70. Non-windowing mode In non-windowing (command-line) mode, Gateway Global presents its own command prompt. Interaction with the program is accomplished using individual commands typed at the prompt. Running Gateway Global in non-windowing mode does not require an X server on the local machine. To run Gateway Global in non-windowing mode on MP-RAS, or from Database Window (DBW) on any platform, use the -nw command-line option: /tgtw/bin/xgtwglobal -nw On Windows and Linux, Gateway Global runs only in non-windowing mode. It is not necessary to use the -nw option on these platforms. To start Gateway Global on Windows and Linux, at the command line type either gtwglobal or xgtwglobal. Gateway Global Commands Overview You use Gateway Global commands to perform the following functions: Display network and session information Administer users and sessions Perform routine and special diagnostics The following sections summarize the functions of each command, whether the command requires the use of SELECT HOST, and any platform restrictions if the command is not available on all platforms. Following this section, each command is discussed separately in detail in alphabetical order. User Names and Hexadecimal Notation The Gateway Global utility can display and accept hexadecimal (hex) notation to represent user names that are not representable in the ASCII or Latin-1 character sets: If a non-printing character appears in a user name, the name is automatically displayed as a single-quoted hexadecimal string representation of the Teradata Database internal encoding, followed by the special character combination xn, signifying that the preceding string represents a hex-format user name. You can enter names in hex format using the same convention of surrounding the hex name itself with single quotes, and following the closing quote with the xn character combination. Utilities 33

34 Chapter 2: Gateway Global (gtwglobal, xgtwglobal) Gateway Global Commands Overview Example This example shows how a hexadecimal format name would be entered as part of the DISPLAY USER command: di us '46d64c4b454e'xn User '46d64c4b454e'xn has 1 session Session PE User IP Adr '46d64c4b454e'xn Enter gateway command or enter h for Help: Specifying a Host Some commands require you to specify a host before you can initiate the command action. To specify a host, use the SELECT HOST command. Command Function Platform SELECT HOST Allows input of a specific host number to define the scope used by a subsequent command function. Note: Selecting host 0 resets the host selection. All Displaying Network and Session Information DISPLAY commands allow you to display your network configuration, sessions, and vprocs associated with the gateway, plus information about specific sessions. Command Function Platform DISPLAY DISCONNECT DISPLAY FORCE Displays a list of sessions that have disconnected. Requires using the SELECT HOST command. Displays sessions that have been successfully killed or aborted using Performance Monitoring and Production Control (PMPC) abort process. All Windows and Linux DISPLAY GTW Displays all sessions connected to the gateway. All DISPLAY NETWORK Displays network configuration information. All DISPLAY SESSION Displays the following information on a specific session: User name, IP address, TCP socket number, state, event, action, partition, and authentication method. Requires using the SELECT HOST command. All DISPLAY STATS Displays the RSS statistics for the gateway vproc. Windows and Linux 34 Utilities

35 Chapter 2: Gateway Global (gtwglobal, xgtwglobal) Gateway Global Commands Overview Command Function Platform DISPLAY TIMEOUT DISPLAY USER Displays the timeout value. Requires using the SELECT HOST command. Displays the session number, PE number, User name, IP address, and current connection status. Requires using the SELECT HOST command. All All Administering Users and Sessions These commands allow you to control gateway traffic and access to the Teradata Database. Command Function Platform DISABLE LOGONS ENABLE LOGONS DISCONNECT USER DISCONNECT SESSION KILL SESSION KILL USER SET TIMEOUT Disables all logons to the Teradata Database through the gateway. Requires using the SELECT HOST command. Enables logons to the Teradata Database through the gateway. Requires using the SELECT HOST command. Disconnects all sessions owned by a user. Requires using the SELECT HOST command. Disconnects a specific session. Requires using the SELECT HOST command. Terminates a specific session. Requires using the SELECT HOST command. Terminates all sessions of a specific user. Requires using the SELECT HOST command. Sets a timeout value. Requires using the SELECT HOST command. All All MP-RAS MP-RAS All All All Performing Special Diagnostics The TRACE commands allow you to debug internal gateway errors or anomalies. Command Function Platform ENABLE TRACE Records internal gateway events. Requires using the SELECT HOST command. All Utilities 35

36 Chapter 2: Gateway Global (gtwglobal, xgtwglobal) Gateway Global Commands Command Function Platform DISABLE TRACE FLUSH TRACE Turns off the recording of event tracing and writing to the gateway log files. Requires using the SELECT HOST command. Directs the gateway to write the contents of its internal trace buffers to the gateway log files. Requires using the SELECT HOST command. All All Logging Sessions Off Using KILL When you issue a KILL command, any outstanding requests are first aborted. The specified session is logged off. The following table describes the KILL command behavior. IF the session is currently... THEN... disconnected logged on the assign task attempts a log off by setting the KILL flag to indicate that an attempt has been made to log off. a kill message is sent to the connect task to abort any outstanding requests and then to log off. Note: Aborting an outstanding request could take a significant amount of time. Therefore, killing a specific session or all of a user s sessions does not necessarily free up the resources of those sessions immediately. For more information on KILL commands, see KILL SESSION on page 65 and KILL USER on page 66. Getting Help To list all the Gateway Global commands, type the following at the command line. help The following table describes the help command. Command Function Platform HELP Displays a menu of all the gtwglobal commands alphabetically, including the syntax for each command. Note: h can be used as a synonym for HELP on the command-line. All Gateway Global Commands The following sections describe the Gateway Global commands. 36 Utilities

37 Chapter 2: Gateway Global (gtwglobal, xgtwglobal) DISABLE LOGONS DISABLE LOGONS Purpose The DISABLE LOGON command prevents users from logging on to the Teradata Database on the network using the gateway for the selected host. Syntax DISABLE DISA LOGONS LOGO GT07B003 Usage Notes The default setting of the logon flag is enabled. However, after a Teradata Database system restart, all host groups that were disabled remain disabled. Any application that attempts to log on after DISABLE LOGONS results in the following error message: 8033: Logon is disabled. Note: Sessions already logged on are not affected by the DISABLE LOGONS command. Before using the DISABLE LOGONS command, you must select the host from which the session is running using the SELECT HOST command. For information, see SELECT HOST on page 68. For additional information, see ENABLE LOGONS on page 59. Example To prevent network users from logging on through the gateway to the Teradata Database, type: disa logo Utilities 37

38 Chapter 2: Gateway Global (gtwglobal, xgtwglobal) DISABLE TRACE DISABLE TRACE Purpose The DISABLE TRACE command turns off the recording of event tracing and writing to the gateway log files. Syntax DISABLE DISA TRACE TRAC GT07B004 Usage Notes Example The default setting of the trace flag is disabled. Note: If tracing has been enabled and you do not use the DISABLE TRACE command to turn it off, the file system may become full. Before using the DISABLE TRACE command, you must select the host from which the session is running using the SELECT HOST command. For information, see SELECT HOST on page 68. For additional information, see ENABLE TRACE on page 60. For information on the gateway log files, see Chapter 1: Gateway Control (gtwcontrol). To turn off the recording of event tracing and writing to the gateway log files, type: disa trac No report is generated. 38 Utilities

39 Chapter 2: Gateway Global (gtwglobal, xgtwglobal) DISCONNECT SESSION DISCONNECT SESSION Purpose The DISCONNECT SESSION command disconnects a specific session from the gateway. This command is available only on MP-RAS. Syntax DISCONNECT DISC SESSION SE ses_no GT07C006 where: Syntax element... Is the... ses_no session number (in decimal). Note: To list the possible values for ses_no, use the DISPLAY GTW or DISPLAY NETWORK command. Usage Notes Before using the DISCONNECT SESSION command, you must select the host from which the session is running using the SELECT HOST command. For information, see SELECT HOST on page 68. The DISCONNECT SESSION command disconnects only the session identified by ses_no. This command does not require the actual processor number containing the session to be entered. After 20 minutes, the session is logged off, if the client has not reconnected. Note: The 20-minute value is only a default. You can change the value using the gtwcontrol or gtwglobal command. The DISCONNECT SESSION command is useful for testing application recovery when reconnecting is required. Utilities 39

40 Chapter 2: Gateway Global (gtwglobal, xgtwglobal) DISCONNECT SESSION Example To disconnect session 1000, type the following from the gateway control utility: disc se 1000 The following statement appears: Session 1000 scheduled to be disconnected. 40 Utilities

41 Chapter 2: Gateway Global (gtwglobal, xgtwglobal) DISCONNECT USER DISCONNECT USER Purpose The DISCONNECT USER command disconnects all sessions owned by a specific user originating from a specific host. This command is available only on MP-RAS. Syntax DISCONNECT DISC where: USER US user_name GT07C007 Syntax element... Is the... user_name name of the user. Note: To list the valid users for user_name, use DISPLAY GTW on page 45 or DISPLAY SESSION on page 50. Usage Notes Before using the DISCONNECT USER command, you must select the host from which the sessions are running using the SELECT HOST command. For information, see SELECT HOST on page 68. The DISCONNECT USER command forces all sessions owned by the user_name to disconnect. This command does not require the actual processor number containing the sessions to be entered, just the user_name. After 20 minutes, the sessions are logged off, if the client has not reconnected. Note: The 20-minute value is only a default. You can change the value using the gtwcontrol or gtwglobal command. The DISCONNECT USER command is useful for testing application recovery when reconnecting is required. Utilities 41

42 Chapter 2: Gateway Global (gtwglobal, xgtwglobal) DISCONNECT USER Example To disconnect all sessions owned by user systemfe, first specify the host using the SELECT HOST command, then type: disc us systemfe The following report appears: User Systemfe has 2 sessions disconnected SessionNo Utilities

43 Chapter 2: Gateway Global (gtwglobal, xgtwglobal) DISPLAY DISCONNECT DISPLAY DISCONNECT Purpose The DISPLAY DISCONNECT command returns a list of sessions that have disconnected and not yet reconnected. Syntax DISPLAY DI DISCONNECT DISC GT07B022 Usage Notes Example The context for these sessions is maintained in the gateway control assign task. If the client associated with the session fails to reconnect in the time allotted, the session is logged off. Before using the DISPLAY DISCONNECT command, you must select the host from which the session is running using the SELECT HOST command. For information, see SELECT HOST on page 68. To display disconnected sessions, type: di disc The following report appears. Host Group 52 has 5 disconnected sessions: Session PE User TimeToLive DBC 1185 secs DBC 1185 secs DBC 1185 secs DBC 1185 secs DBC 1185 secs Utilities 43

44 Chapter 2: Gateway Global (gtwglobal, xgtwglobal) DISPLAY FORCE DISPLAY FORCE Purpose The DISPLAY FORCE command displays sessions that have been forced off because of a KILL command or a Performance Monitoring and Production Control (PMPC) ABORT SESSION command. This command is available only on Windows and Linux. Syntax DISPLAY DI FORCE FO FF07D356 Usage Notes The Teradata Database system displays this information: Host number Number of sessions Session ID number User name associated with the session The length of time before the session information is discarded The gateway retains the session information for the standard timeout period after the client has been logged off. The gateway returns an 8055 error when the client reconnects: Session forced off by PMPC or gtwglobal After the timeout period expires, the gateway discards the session information. Example To display a session that has been killed or aborted, type: DI FO Host Group 1 has 2 forced sessions Session User TimeToLive 1002 DBC 916 secs 1004 DBC 922 secs 44 Utilities

45 Chapter 2: Gateway Global (gtwglobal, xgtwglobal) DISPLAY GTW DISPLAY GTW Purpose The DISPLAY GTW command displays all sessions connected to the gateway. Syntax DISPLAY DI GTW gtwid ALL GT07C023 where: Syntax element... Is the... gtwid ALL number of the GTW processor containing the sessions you want to display. keyword that displays all sessions regardless of selected Host Group. Note: To list all possible values for gtwid, use DISPLAY NETWORK on page 47. Usage Notes For the selected gateway, the Teradata Database system displays this information: Host number Gateway vproc number Number of sessions on the gateway Session ID number Internet address User name associated with the session Status Utilities 45

46 Chapter 2: Gateway Global (gtwglobal, xgtwglobal) DISPLAY GTW Example 1 On Windows or Linux, to display a gateway (for example, gateway 8192), type. di gtw 8192 GTW 8192 has 18 sessions Session PE User IP Adr Status DBC CONNECTED DBC CONNECTED DBC CONNECTED DBC CONNECTED DBC CONNECTED DBC CONNECTED DBC CONNECTED DBC CONNECTED DBC CONNECTED DBC CONNECTED DBC CONNECTED DBC CONNECTED DBC CONNECTED DBC CONNECTED DBC CONNECTED DBC CONNECTED DBC CONNECTED DBC CONNECTED Example 2 To display all of the gateway sessions on host 1, type. di gtw all System WUSRH JEA has 1 connected session HG GTW Session PE User IP Adr Status PERM CONNECTED 46 Utilities

47 Chapter 2: Gateway Global (gtwglobal, xgtwglobal) DISPLAY NETWORK DISPLAY NETWORK Purpose The DISPLAY NETWORK command displays information about your network configuration and its associated gateway. Syntax DISPLAY NETWORK ; DI NE LONG LON host_no GT07C009 where: Syntax element... Is the... host_no LONG host number (in decimal). display of the gateway statistics for the particular network. The LONG option applies to NT only. Usage Notes The default setting for the DISPLAY NETWORK command is the short form report, which gives this information: Host number(s) Total number of PEs assigned to host Total number of gateways assigned to host Total number of active sessions on the host Total number of disconnected sessions Tracing information (either Enabled or Disabled) Logon event information (either Enabled or Disabled) The long form displays the following information in addition to the information displayed in the short form report for the network: Vproc number in a group (gateway) Total number of sessions connected to the listed vproc Total number of sessions connected to the listed PE If host_no is used to request a specific host number, the long form cannot be requested. Utilities 47

48 Chapter 2: Gateway Global (gtwglobal, xgtwglobal) DISPLAY NETWORK Example 1 To display information about your network configuration and its associated gateway in the short form on MP-RAS, type: di ne Host 1 has 0 session(s) over 2 GTW(s) and 4 PE(s) ( 0 Active / 0 Disconnected ) Gateway Sessions Logon Trace Enable Disable Enable Disable Example 2 To display information about your network configuration and its associated gateway in the short form on Windows or Linux, type: di ne Host 2 has 0 session(s) over 1 GTW(s) and 1 PE(s) ( 0 Active / 0 Disconnected / 0 Forced) Gateway Sessions Logon Trace Enable Disable Host 1 has 20 session(s) over 1 GTW(s) and 2 PE(s) ( 18 Active / 0 Disconnected / 2 Forced) Gateway Sessions Logon Trace Enable Disable Example 3 To display information about your network configuration and its associated gateway in the long form on MP-RAS, type: di ne long Host 1 has 0 session(s) over 2 GTW(s) and 4 PE(s) ( 0 Active / 0 Disconnected ) PE Sessions Gateway Sessions Logon Trace Enable Disable Enable Disable 48 Utilities

49 Chapter 2: Gateway Global (gtwglobal, xgtwglobal) DISPLAY NETWORK Example 4 To display information about your network configuration and its associated gateway in the long form on Windows or Linux, type: di ne long Host 52 has 10 session(s) over 1 GTW(s) and 2 PE(s) ( 10 Active / 0 Disconnected ) PE Sessions Gateway Sessions Logon Trace Enabled Enabled Utilities 49

50 Chapter 2: Gateway Global (gtwglobal, xgtwglobal) DISPLAY SESSION DISPLAY SESSION Purpose The DISPLAY SESSION command returns a complete list of connected sessions regardless of the selected host group. Syntax DISPLAY SESSION ses_no DI SE LONG LON GT07C024 where: Syntax element... Is the... ses_no LONG session number (in decimal). display of the gateway statistics for the particular session. Note: To list the possible values for ses_no, use DISPLAY GTW on page 45. Usage Notes Before using the DISPLAY SESSION command, you must select the host from which the session is running using the SELECT HOST command. For information, see SELECT HOST on page 68. The DISPLAY SESSION command displays only the session identified by ses_no. By default, the Teradata Database system displays the short-form report containing the following information: User Name IP address TCP socket number State Event Action Partition Authentication method 50 Utilities

51 Chapter 2: Gateway Global (gtwglobal, xgtwglobal) DISPLAY SESSION The Authentication field has the values shown in the following table. The value... Indicates... Database TDGSS-returned method that the database provided the authentication method. Note: This was the normal logon method before the implementation of single sign on. an authentication method returned by the Teradata Database Generic Security Service (TDGSS). For more information on TDGSS, see Security Administration. The long-form report gives a detailed connect display for a selected session. The following is provided: Teradata Database system mailbox information. The session number in the user information is shown in decimal. All other values are shown in hexadecimal. The long-form report is useful for field service personnel when diagnosing gateway problems. For information on the descriptions of the valid states, events, and actions for the DISPLAY SESSION command for MP-RAS Version 3.0, see Appendix C: Session States, Events, and Actions. Procedure for Displaying a Session To display a session, do the following: 1 To select a host (for example, host 52), type: se host 52 The Teradata Database system displays the following: 52> 2 To display a session (for example, session 1000), type: di se 1000 To display session 1005 in the default (or short) form, type: di se 1040 gtwglobal displays the following output: Session 1040 connected to GTW 8193 is assigned to PE of host 1 User Name IP Addr Port DBC State Event Action CS_CLIENTWAITNOTRAN CE_STARTMSGRSPNOTRAN CA_SENDDBSRSP Utilities 51

52 Chapter 2: Gateway Global (gtwglobal, xgtwglobal) DISPLAY SESSION Partition Authentication DBC/SQL DATABASE Example 1 To display session 1040 in the long form on Windows or Linux, type: di se 1040 long The following displays: Session 1040 connected to GTW 8193 is assigned to PE of host 1 User Name Account IP Addr Port DBC State Event Action CS_CLIENTWAITNOTRAN CE_STARTMSGRSPNOTRAN CA_SENDDBSRSP Partition Authentication DBC/SQL DATABASE StrMbx: fff CntMbx: fff d AbtMbx: fff d HostMessageReads : 10 HostBlockReads : 5 HostReadBytes : 699 DbsMessageReads : 2 HostMessageWrites : 5 HostBlockWrites : 5 HostWriteBytes : 1245 DbsMessageWrites : 2 Example 2 This example displays the user name on session 1242 in hexadecimal format. di se 1242 lon Session 1242 connected to GTW is assigned to PE of host 52 User Name Account IP Addr Socket '46d64c4b454e'xn State Event Action Partition CS_ESTABLISHED CE_TAKEOVERACK CA_NOP DBC/SQL Authentication Database StrMbx: ffe Utilities

53 Chapter 2: Gateway Global (gtwglobal, xgtwglobal) DISPLAY SESSION CntMbx: ffe d AbtMbx: ffe d Enter gateway command or enter h for Help: Utilities 53

54 Chapter 2: Gateway Global (gtwglobal, xgtwglobal) DISPLAY STATS DISPLAY STATS Purpose The DISPLAY STATS command allows you to display the statistics for the gateway vproc. This command is available only on Windows and Linux. Syntax DISPLAY STATS gtwid DI ST ALL GS02A013 where: Syntax element... Is the... gtwid ALL specified gateway vproc whose statistics are displayed. selected host group. If you select a host group, gtwglobal returns the statistics for all the gateway vprocs in the selected host group. If you do not select a host group, gtwglobal returns the statistics for all gateway vprocs. Example 1 di st all Gtw Vprocid: 8193 HostMessageReads: 382 HostBlockReads: 125 HostReadBytes: DbsMessageReads: 108 HostMessageWrites: 125 HostBlockWrites: 125 HostWriteBytes: 1167 DbsMessageWrites: 104 Gtw Vprocid: 8192 HostMessageReads: 2220 HostBlockReads: 1107 HostReadBytes: DbsMessageReads: 1103 HostMessageWrites: 1107 HostBlockWrites: 1107 HostWriteBytes: DbsMessageWrites: Utilities

55 Chapter 2: Gateway Global (gtwglobal, xgtwglobal) DISPLAY STATS Example 2 To display the statistics for gateway vproc 8192, type: di st 8192 Gtw Vprocid: 8192 HostMessageReads: 2220 HostBlockReads: 1107 HostReadBytes: DbsMessageReads: 1103 HostMessageWrites: 1107 HostBlockWrites: 1107 HostWriteBytes: DbsMessageWrites: 1103 Utilities 55

56 Chapter 2: Gateway Global (gtwglobal, xgtwglobal) DISPLAY TIMEOUT DISPLAY TIMEOUT Purpose The DISPLAY TIMEOUT command allows you to display the logoff delay in minutes for disconnected sessions. Syntax DISPLAY DI TIMEOUT TI GT07C028 Example Before using the DISPLAY TIMEOUT command, you must select the host from which the session is running using the SELECT HOST command. For information, see SELECT HOST on page 68. To display the timeout logoff delay, type: di ti Host 1 Timeout Value: 20 minutes 56 Utilities

57 Chapter 2: Gateway Global (gtwglobal, xgtwglobal) DISPLAY USER DISPLAY USER Purpose The DISPLAY USER command returns a list of connected sessions whose names match the user name. Syntax DISPLAY DI USER US user_name GT07C025 where: Syntax element... Is the... user_name name of the user. Usage Notes Before using the DISPLAY USER command, you must select the host from which the sessions are running using the SELECT HOST command. For information, see SELECT HOST on page 68. The DISPLAY USER command displays this information: Session number Parsing Engine that the session is assigned to User name IP address Status indicating the following (Windows and Linux only): Connected Forced Gone Killed Utilities 57

58 Chapter 2: Gateway Global (gtwglobal, xgtwglobal) DISPLAY USER Example 1 To display a user (for example, user DBC), type. di us dbc User DBC has 20 sessions Session PE User IP Adr Status DBC CONNECTED DBC FORCED DBC CONNECTED DBC FORCED DBC CONNECTED DBC GONE DBC CONNECTED DBC CONNECTED DBC CONNECTED DBC CONNECTED DBC CONNECTED DBC CONNECTED DBC CONNECTED DBC CONNECTED DBC CONNECTED DBC CONNECTED DBC CONNECTED DBC CONNECTED DBC CONNECTED DBC CONNECTED Example 2 To display a user name in hexadecimal format, type. di us '46d64c4b454e'xn User '46d64c4b454e'xn has 1 session Session PE User IP Adr '46d64c4b454e'xn Enter gateway command or enter h for Help: 58 Utilities

59 Chapter 2: Gateway Global (gtwglobal, xgtwglobal) ENABLE LOGONS ENABLE LOGONS Purpose The ENABLE LOGONS command allows users to log on to the Teradata Database using the network through the gateway for the selected host. Syntax ENABLE EN LOGONS LOGO GT07B012 Usage Notes Example The default setting of the logons flag is enabled. Before using the ENABLE LOGONS command, you must select the host from which the session is running using the SELECT HOST command. For additional information, see SELECT HOST on page 68 and DISABLE LOGONS on page 37. To allow users to log on to the Teradata Database using the network through the gateway, type: enable logons Utilities 59

60 Chapter 2: Gateway Global (gtwglobal, xgtwglobal) ENABLE TRACE ENABLE TRACE Purpose The ENABLE TRACE command turns on session tracing. The command records internal gateway events. Syntax ENABLE EN TRACE TRAC GT07B013 Usage Notes Caution: Session tracing may contain some of these elements: Note: Entries vary depending on the events and action taken. Session number (if available) Associated file description (if available) Event One or more of these events: Assigned Logged on Logged off Logoff forced (Teradata Database system killed session) Logon failed (usually caused by invalid password) Disconnected Reassigned Reconnected Network address of the originating network-attached host By default, tracing is disabled. After a Teradata Database system restart, tracing enabled earlier using the ENABLE TRACE command is continued. If tracing has been enabled and you do not use the DISABLE TRACE command to turn it off, the file system may become full. Before using the ENABLE TRACE command, you must select the host from which the session is running using the SELECT HOST command. For information, see SELECT HOST on page Utilities

61 Chapter 2: Gateway Global (gtwglobal, xgtwglobal) ENABLE TRACE The trace file is a text file, which can be viewed by any tool that displays text. The trace information is the same trace information controlled by Gateway Control. Therefore, the trace information is located by the path set in Gateway Control. The Gateway log files are the same as the event files. For additional information, see DISABLE TRACE on page 38. For information on the gateway log files, see Chapter 1: Gateway Control (gtwcontrol). Example To turn on session event tracing, type: enable trace Utilities 61

62 Chapter 2: Gateway Global (gtwglobal, xgtwglobal) FLUSH TRACE FLUSH TRACE Purpose The FLUSH TRACE command directs the gateway to write the contents of its internal trace buffers to the gateway log file. Usually, these transitions are buffered before being recorded in gateway log files. For the gateway log to accurately reflect all of the events processed by the gateway, you must issue a FLUSH TRACE command. Syntax FLUSH FL TRACE TRCE GT07B015 Usage Notes Example The FLUSH TRACE command can be used when diagnosing gateway anomalies. For additional information, see ENABLE TRACE on page 60 and DISABLE TRACE on page 38. Before using the FLUSH TRACE command, you must select the host from which the session is running using the SELECT HOST command. For information, see SELECT HOST on page 68. For information on the gateway log files, see Chapter 1: Gateway Control (gtwcontrol). To direct the gateway to write the contents of its internal trace buffers to the gateway log file, type: flush trace 62 Utilities

63 Chapter 2: Gateway Global (gtwglobal, xgtwglobal) HELP HELP Purpose The HELP command allows you to get help when using the xgtwglobal or gtwglobal commands. Syntax HELP H 1102A161 where: Syntax element... Is the... help displays syntax for all the gtwglobal or xgtwglobal commands. H and h are synonyms for HELP on the command line. Example The following is an example of the Help commands for Gateway Global on MP-RAS. DISAble LOGOns ( disa logo * host must be selected) DISAble TRACe ( disa trac * host must be selected) DISConnect SEssion ses_no ( disc se 1010 * host must be selected) DISConnect USer user_name ( disc us joe * host must be selected) DIsplay DISConnect ( di disc * host must be selected) DIsplay GTW gtwid ALL ( di gtw ALL ) DIsplay NEtwork LONg host_no ( di ne lon 52 ) DIsplay SEssion ses_no [LONg] ( di se 1020 lon ) DIsplay TImeout ( di ti * host must be selected) DIsplay USer user_name ( di us joe * host must be selected) ENable LOGOns ( en logo * host must be selected) ENable TRACe ( en trac * host must be selected) FLush TRACe ( fl trac * host must be selected) KIll SEssion ses_no ( ki se 1010 * host must be selected) KIll USer user_name ( ki us joe * host must be selected) Utilities 63

64 Chapter 2: Gateway Global (gtwglobal, xgtwglobal) HELP SElect HOst host_no ( se ho 52 (select ho 0 to reset) SET TImeout time_value ( set ti 30 * value in minutes ) QUIT Enter gateway command or type h for Help: 64 Utilities

65 Chapter 2: Gateway Global (gtwglobal, xgtwglobal) KILL SESSION KILL SESSION Purpose The KILL SESSION command terminates the specified session on the Teradata Database by aborting any active request on that session and logging the session off. Note: Aborting an outstanding request could take a significant amount of time. Therefore, killing a session or a user s sessions does not necessarily free up the resources of those sessions immediately. Syntax KILL KI SESSION SE ses_no GT07C016 where: Syntax element... Is the... ses_no session number (in decimal). Note: To list the possible values for ses_no, use the DISPLAY GTW on page 45 or DISPLAY NETWORK on page 47. Usage Notes Example Before using the KILL SESSION command, you must select the host from which the session is running using the SELECT HOST command. For information, see SELECT HOST on page 68. The KILL SESSION command specifies that the session identified by ses_no be terminated. This command leaves an audit trail in the error log. To terminate session 1000 on the network through the gateway, type: kill se 1000 Session 1000 scheduled to be killed. Utilities 65

66 Chapter 2: Gateway Global (gtwglobal, xgtwglobal) KILL USER KILL USER Purpose The KILL USER command terminates all sessions logged on to the Teradata Database for the specified user name restricted to the host group of the gateway. KILL USER aborts any active requests on those sessions and logs the sessions off. Note: Aborting an outstanding request could take a significant amount of time. Therefore, killing a session or a user s sessions does not necessarily free up the resources of those sessions immediately. Syntax KILL KI USER US user_name GT07C017 where: Syntax element... Is the... user_name name of the user. Note: To list the possible values for user_name, use the DISPLAY GTW on page 45 or DISPLAY SESSION on page 50. Usage Notes Before using the KILL USER command, you must select the host from which the session is running using the SELECT HOST command. For information, see SELECT HOST on page 68. The KILL USER command leaves an audit trail in the gateway log files, which shows the vproc that the kill was issued on and the session number of the user being killed. An example is shown below. Gtwglobal issued kill command: (867): Fri Apr 14 13:39: VprocId: 8193 Session Number: 1009 Note: Only the attempt to logoff the user is recorded, since the Teradata Database might deny the logoff attempt. 66 Utilities

67 Chapter 2: Gateway Global (gtwglobal, xgtwglobal) KILL USER Example To terminate all sessions logged on the network through the gateway by user perm01, type: kill us perm01 User PERM01 has 1 session killed 1005 Utilities 67

68 Chapter 2: Gateway Global (gtwglobal, xgtwglobal) SELECT HOST SELECT HOST Purpose The SELECT HOST command selects the host for subsequent Gateway Control command functions. Syntax SELECT SE HOST HO host_no GT07C026 where: Syntax element... Is the... host_no host number. Usage Notes Example The SELECT HOST command allows you to specify the host number of a network-attached host that will be affected by the subsequent Gateway Control command function that you type next. To select host 1, type: select host 1 IF the Host number is... THEN the following message appears... found not found Host 1 has been selected. Invalid Host 1 is entered. Please try again! To deselect a host, type: select host 0 68 Utilities

69 Chapter 2: Gateway Global (gtwglobal, xgtwglobal) SET TIMEOUT SET TIMEOUT Purpose The SET TIMEOUT command allows you to set the time in minutes to delay a logoff for disconnected sessions. Syntax SET TIMEOUT TI time_value GT07C027 where: Syntax element... Is the... time_value amount of time to delay logoff in minutes. Usage Notes Example The SET TIMEOUT command can be used to delay logoff for disconnected sessions when working on network or database problems. Before using the SET TIMEOUT command, you must select the host from which the sessions are running using the SELECT HOST command. For information, see SELECT HOST on page 68. To set a timeout delay for one hour, type: SET TI 60 Timeout value on host 1 set to 60 Utilities 69

70 Chapter 2: Gateway Global (gtwglobal, xgtwglobal) Gateway Global Graphical User Interface Gateway Global Graphical User Interface Main Window The X Windows based GUI for Gateway Global provides much the same functionality as the command-line version using various menus and Windows. Note: The Gateway Global graphical user interface (GUI) is available only on MP-RAS. An X server must be running on the local machine. For information on starting xgtwglobal in GUI mode, see User Interfaces on page 32 The Gateway Global Main window is shown below. Menu Bar Display Summary Session Mode Messages The Gateway Global Main window consists of six sections differentiated by function. The sections of the Main window are described in the following table. 70 Utilities

71 Chapter 2: Gateway Global (gtwglobal, xgtwglobal) Gateway Global Graphical User Interface Subsection Menu Bar Display Summary Session Mode Messages Function Displays the menu items. Displays information relating to the Teradata Database system configuration or current utilization. Shows the sessions grouping based on the Display mode toggle button setting. The button setting also changes the list column. Shows all sessions that are grouped under an item you select in the Summary list. Allows you to disconnect or kill specified sessions or users. Contains various information related to the xgtwglobal operations. Usually, the actions from the Mode buttons initiate these messages. Note: Press F1 with the cursor placed on a specific topic to display information about that topic. Menu Bar The following table explains the menu bar items available in the Display section of the main window. Menu bar item Submenu item Description File Save Messages Saves the capture buffer to a disk. Clear Messages Exit Deletes the contents of the capture buffer. Closes the main window display. Sort User Sorts the current display by user name. Filter IP Address Restricts the display to show only sessions that are connected from the selected IP address. A status message appears to indicate that filtering is enabled any time the display is updated. Note: Sessions connecting from other IP addresses will not be displayed in the Gateway Global window, but are otherwise unaffected. System Logon Toggles network-connected client (gateway) logons. Trace Toggles trace facilities in the gateway connect and assign tasks. Utilities 71

72 Chapter 2: Gateway Global (gtwglobal, xgtwglobal) Gateway Global Graphical User Interface Menu bar item Submenu item Description Timeout Autorefresh Indicates the time in minutes that the gateway delays logoff processing for a disconnected session because of network or database problems. Toggles autorefresh for xgtwglobal displays. When you set the autorefresh On, xgtwglobal polls the connect and assign tasks in the Teradata Database system for information related to session status changes. Display The box beneath the main menu bar contains display options. When you select one of the display options, information about that option appears in the box below and in the summary window. The following table explains the function of each of the options. Option HGID GTW PE Function Displays the active host group identifiers. When you select the HGID option, the Teradata Database system updates the summary window to reflect the current status of all the connected host groups. If you select a host group from the summary window, the Teradata Database system updates the session detail window with a list of sessions connecting to the select host group. By selecting one or more of the sessions listed in the detail window, you can issue an action command against a subset of the sessions. Displays the active gateway vprocs. If you select the GTW option, the Teradata Database system updates the summary window with the current active gateway vprocs. If you select a vproc in the summary window, the Teradata Database system updates the detail with a scrolling selection list of sessions connected to that vproc. Displays the active gateway parsing engines. Like the HGID and GTW options, the PE option shows only the Communications Processor (COP)-type parsing engines. 72 Utilities

73 Chapter 2: Gateway Global (gtwglobal, xgtwglobal) Gateway Global Graphical User Interface Option USER DISC FORC Function Displays the summary of the currently logged on users. If you select the User option, the Teradata Database system updates the summary window with a list of Users. The list is sorted by host group and then by user name. If you select an entry in the summary window, the Teradata Database system updates the detail window with a list of sessions. Note: When there is a non-printing character (or string) in a user name, the xgtwglobal USER option displays that user name in hexadecimal format as shown in the example below. '46d64c4b454e'xn For details on typing user names in hexadecimal format, see User Names and Hexadecimal Notation on page 33. Displays summary information for the currently disconnected users. Disconnected sessions refers to those sessions that were logged off of the database by a reset or a Teradata Database system panic. The Teradata Database system gives these sessions a fixed period of time to reconnect. If the reconnect time expires without the client reconnecting, the gateway simulates a logoff. Kills or Aborts using PMPC off sessions grouped by the Host Group. Summary and Session The Summary section shows the sessions grouping based on the Display mode toggle button setting. The Session section shows all sessions that are grouped under an item you select in the Summary list. The HGID display selection in the figure shows the following: The host groups The number of sessions connected The number of sessions forced off Other information about the sessions Utilities 73

74 Chapter 2: Gateway Global (gtwglobal, xgtwglobal) Gateway Global Graphical User Interface Mode The Mode options work in conjunction with the Session section of the Main window. The following table describes the Mode options. 74 Utilities

75 Chapter 2: Gateway Global (gtwglobal, xgtwglobal) Gateway Global Graphical User Interface Option Session Function Indicates that each session will have a KILL or DISCONNECT command issued. Session offers these options: Option Disc Kill Dsply Sess Sel/Clr All Function Sends a message to the gateway indicating the session or user is to be disconnected. A session disconnected using the Disconnect command is allowed to reconnect. If you choose the Disconnect command, a confirmation window appears, giving you a chance to cancel the command before the Teradata Database system proceeds. Sends a message to the gateway indicating the session or user to be acted upon. The Kill command immediately forces the user off the Teradata Database system. Unlike the Disconnect command, the Kill command removes the session information about the user from the database entirely, and if the client wants to reconnect, the gateway denies it If you choose the Kill command, a confirmation window appears, giving you the chance to cancel the command before the Teradata Database system proceeds. Sends a message to the gateway requesting detail information about the status of the selected sessions. For a sample of the Display session, see Session Window on page 76. Selects or deselects all of the sessions in the Session window. User Has the effect of sending a single command (per host group), forcing the gateway to determine which sessions should be killed. To use a Mode option, do the following: 1 Highlight a session in the Mode area of the Main window. 2 Select an option. Messages The Messages section is located at the bottom of the Main window. Messages generated by the Teradata Database system that are the result of a specified Mode option for a specific session display here. For example, if you initiate a kill or disconnect option in the Mode window, you might see the following messages: Utilities 75

76 Chapter 2: Gateway Global (gtwglobal, xgtwglobal) Gateway Global Graphical User Interface Session Window User DBC killed Session xxx not found The Session window provides detailed information about a selected session. To display the Session window, do the following: 1 In the Summary section of the Main window, select a session by clicking on it. The session is highlighted. 2 In the Mode section of the Main window, select the Session option. 3 In the Mode section of the Main window, select the Dsply Sess button. The Session window appears. The example session window below shows user and configuration information for session number The session window displays a list of the users that are connected to that particular session, plus detailed configuration information. 76 Utilities

77 CHAPTER 3 Lock Display (lokdisp) The Lock Display utility, lokdisp, provides a snapshot capture of all real-time database locks. The database software uses locks for concurrency control. lokdisp displays locks used for concurrency. A lock can be applied to a database object based on the following lock granularity: Database Table Rowhash Range Rowhash Optionally, you can specify the lock to be applied to a database object using the SQL Locking Modifier. lokdisp can obtain lock information from the following: A specific AMP A group of AMPs All AMPs Note: For a Teradata Database system with many AMPs and a heavy load, be careful when selecting the number of AMPs from which to obtain information. The fewer the AMPs selected, the lower the volume of lock information generated, and the more manageable the output. Teradata recommends obtaining information from all AMPs only when the lock information for a specific transaction is needed. For detailed examples of returned data, see DB on page 84 and TABLE on page 94. Audience Users of the Lock Display utility include the following: Support engineers Teradata Database engineers Teradata Database system administrators Teradata Database system programmers Utilities 77

78 Chapter 3: Lock Display (lokdisp) User Interfaces User Interfaces lokdisp runs on the following platforms and interfaces: Platform MP-RAS Windows Linux Interfaces Database Window Command line ( Teradata Command Prompt ) Database Window Command line Database Window For general information on starting the utilities from different platforms and interfaces, see Appendix B: Starting the Utilities. Lock Modes You can specify the following lock modes to a database object: Access Read Write Exclusive Lock-Mode Contention The lock-mode contention among all outstanding lock requests determines which lock requests can be applied concurrently against a database object. This is illustrated by the contention matrix shown below. Lock Mode Implicit Access Implicit Read Implicit Write Implicit Exclusive Access Read Write Exclusive Implicit Access X X X X X X X Implicit Read X X X X X X Implicit Write X X X X X Implicit Exclusive X X X X Access X X X X X X Read X X X X 78 Utilities

79 Chapter 3: Lock Display (lokdisp) Lock Display Utility Commands Lock Mode Implicit Access Implicit Read Implicit Write Implicit Exclusive Access Read Write Exclusive Write X X Exclusive Explicit and Implicit Lock Modes Lock Request Status Explicit lock modes are the actual locks that secure access to a database object. Usually, they are acquired at the onset of the actual transaction processing. Implicit lock modes are pre-emptive locks used by the Lock Manager in the process of acquiring an explicit lock. Use of pre-emptive locks suggests that an explicit lock is not acquired in a single step but rather in a sequence of steps. For example, consider acquiring an explicit table-level lock. Prior to acquiring the explicit table-level lock, an implicit database-level lock and an implicit table-level lock must be acquired first. Upon acquiring an explicit lock, any implicit lock acquired in the process is released. The lock mode is noted in the mode field of the lokdisp output. An implicit lock is identified by the appearance of an asterisk (*). An explicit lock is implied when an asterisk is absent. A lock request against a database object can be granted or blocked depending on the following: The lock mode contention of all outstanding lock requests The success of acquiring all locks implied by the lock granularity of the request lokdisp output shows separate sections for Granted and Blocked lock requests. In the case of a blocked request, the level of the database object is shown by marking the associated field in the output with the hash symbol (#). For example, if the blocked request involves a table, then the table field is marked with the # symbol. Lock Display Utility Commands The following table lists the lokdisp commands. Command BLOCKERS DB HELP QUIT Description Identifies the blocked transactions as well as their blocker transactions. Identifies the databases that have a database-level lock request. Provides general help for the Lock Display utility. Exits lokdisp. Utilities 79

80 Chapter 3: Lock Display (lokdisp) Lock Display Utility Commands Command ROWHASH ROWRANGE TABLE TRAN Description Identifies a rowhash-level lock request. Rowhash lock information is provided also. Identifies a rowrange-level lock request. Rowrange lock information is provided also. Identifies a table-level lock request. Identifies currently running transactions with locks being applied. The commands are discussed in detail in the following sections. Note: lokdisp displays a series of question mark (?) characters if it does not find user, database, or table names in the cache or, in the case of DDL statements, in the Data Dictionary. To view output examples, see DB on page 84 and TABLE on page Utilities

81 Chapter 3: Lock Display (lokdisp) BLOCKERS BLOCKERS Purpose The BLOCKERS command identifies blocked transactions and the transactions that are blocking them. Syntax BLOCKERS B TRAN ProcId ALL Uniq1 Uniq2 LIMIT NUMBER NONE KY01A098 where: Syntax element... Specifies... ProcId Uniq1 Uniq2 ALL LIMIT NUMBER NONE the virtual processor number of the parsing engine processor handling the transaction. Since virtual processor numbers are designated as integer numbers, the corresponding value for this option normally is specified in decimal notation. This number is the first component of a transaction ID. a value that is normally specified as four hexadecimal digits. This value is the second component of a transaction ID. a value that is normally specified as four hexadecimal digits. This value is the third component of a transaction ID. that all blocked transactions and their corresponding blocker transactions will be considered. ALL is the default if you do not specify a transaction ID. the number of blocker transactions to consider for a blocked transaction. the desired limiting value. that all blocker transactions for a blocked transaction are considered. Specifying NONE corresponds to specifying zero for Number. Note: Together, ProcId, Uniq1, and Uniq2 identify a transaction ID. Utilities 81

82 Chapter 3: Lock Display (lokdisp) BLOCKERS Usage Notes A transaction is an internal database concept. A transaction can have more than one blocking transaction. For example, a transaction can have five lock requests, and five transactions can block those same lock requests. In other words, if you have five tables, then conceivably, five other transactions can have the locks on those same five tables. The following table shows the components of BLOCKERS command output. Component... Includes the... Number of Blocked Trans displayed Blocked Trans total number of both blocked and blocker transactions. number of the blocked transaction and the following information: Component... Specifies... Number of blockers displays Number of blockers exists blocker entry count. actual blocker count. Blocker Trans number of blocking transactions and the following information: Component... Specifies... lock mode lock status lock objecttype a type of lock mode: Access Read Write Exclusive a type of status of the lock request: Granted a type of object that is locked: Database Table Rowrange Rowhash 82 Utilities

83 Chapter 3: Lock Display (lokdisp) BLOCKERS Component... Includes the... Blocker Trans (continued) Component... Specifies... lock objectid an ID of the locked object and might include the following: Database ID Database Name Table ID Table Name RowHashS RowHashE Note: If the lock objecttype is Rowhash, only RowHashS is displayed; if the Lock objecttype is RowRange, both RowHashS and RowHashE is displayed. RowHashS and RowHashE are the lower- and upper-bound levels of the RowHash range, respectively. Example The following example shows one lock entry on AMP 0: > blockers LIMIT 1 blockers LIMIT 1 - The following amps are available: Which amp(s) do you want to request on (S=Sampline/A=all/C=cancel/Q=quit): > AMP 0 REPORTS A LOCK ENTRIES Number of Blocked Trans displayed : 1 ========================================= Blocked Trans Number of blockers displays : 1 Number of blockers exists : 1 Blocker Trans : lock mode : Exclusive lock status : Granted lock objecttype : Table lock objectid : DBID : : DBNAME : STAFF : TableID : ,0000 : TableName : EMPLOYEE : RowHashS : : RowHashE : Utilities 83

84 Chapter 3: Lock Display (lokdisp) DB DB Purpose The DB command identifies the databases that have a database-level lock request. Syntax DB D DBname ALL KY01A096 where: Syntax element... Specifies... DBname ALL the name of a database. that all databases that have a database-level lock request will be considered. ALL is the default if you do not specify a database name. Usage Notes The following table shows the components of DB command output. Component... Specifies... Tran Host Session Mode User Database currently running transactions with locks being applied. the logical host ID (the origin of the transaction). the session number for the transaction. the lock mode: Access Read Write Exclusive the logon-id for whom the lock is being requested. the name of the database being locked. 84 Utilities

85 Chapter 3: Lock Display (lokdisp) DB Example 1 The following example shows locks on a sampling on all AMPs for the RECBDQTAC database: >lokdisp Amp Utility / / \ --- / / / / \ \ \ \ \ Release Version LOCK DISPLAY UTILITY (June 2000) LOCK DISPLAY UTILITY Command String Syntax: Help or? TRan [ProcId Uniq1 Uniq2] [ALL] Db [DBname] [ALL] TAble [DBname.Tablename] [ALL] ROWRange [DBname.Tablename TypeAndIndex] [ALL] ROWHash [DBname.Tablename TypeAndIndex, RowHash1 RowHash2] [ALL] Blockers [TRAN [ProcId Uniq1 Uniq2] [ALL]] [LIMIT [Number] [NONE]] Quit -> Please enter your selection from the list: db - The following amps are available: > Which amp(s) do you want to request on (S=Sampling/A=all/C=cancel/ Q=quit): a> a AMP 0 REPORTS 1 LOCK ENTRIES GRANTED LOCK REQUEST(S): Tran: Host: 2049 Session: Database: RECBDQTAC 0, 1000 Mode: WR* User: DBC AMP 2 REPORTS 1 LOCK ENTRIES Tran: GRANTED LOCK REQUEST(S): Utilities 85

86 Chapter 3: Lock Display (lokdisp) DB Host: 2049 Session: Database: RECBDQTAC 0, 1000 Mode: WR* User: DBC Example 2 The following example tries to display database-level locks while trying to create database USER1. The first lock is an Intentional Write Lock on database DBC (user DBC), and the second lock is an Intentional Exclusive Lock on database USER1 (user DBC). LOKDISP >> DB ALL - The following amps are available: 0 -> Which amp(s) do you want to request on (S=Sampling/A=all/C=cancel/Q=quit): A AMP 0 REPORTS 2 LOCK ENTRIES GRANTED LOCK REQUEST(S): Tran: B8 Host: 7169 Session: 0, 1010 Mode: WR* User:?????????????????????????????? Database:?????????????????????????????? Host: 7169 Session: 0, 1010 Mode: EX* User:?????????????????????????????? Database:?????????????????????????????? 86 Utilities

87 Chapter 3: Lock Display (lokdisp) HELP HELP Purpose The HELP command provides general help for Lock Display. Syntax HELP H? KY01A097 where: Syntax element... Specifies... Help, H, or? general help for the Lock Display utility. Example The following example shows basic Lock Display Help: -> Please enter your selection from the list: HELP LOCK DISPLAY UTILITY An optional command string may be used to limit the display to specific requests; otherwise, all requests are displayed except for BLOCKERS. Commands are case-insensitive and may be abbreviated. The default radix for numeric entries is hex, but may be forced to decimal by terminating with a period. For example, ten decimal must be entered as "10.", since an unmodified "10" is interpreted in hex as 0x10 or sixteen decimal. For the TRAN command, a set of lines displayed represents one lock request. Only object names relevant to a given lock request are displayed: for example, only database name is displayed for a database lock, whereas both database name and table name are displayed for a table lock. A "#" after an object name means the lock has not yet been granted for that level. For example, "Databasename Tablename# Rowhash1#" means the lock has been granted at database level, but not yet at table or rowhash level. --more-- Please press <enter> to continue. Utilities 87

88 Chapter 3: Lock Display (lokdisp) QUIT QUIT Purpose The QUIT command exits lokdisp. Syntax QUIT Q KY01A099 where: Syntax element... Specifies... QUIT or Q that lokdisp should exit. 88 Utilities

89 Chapter 3: Lock Display (lokdisp) ROWHASH ROWHASH Purpose The ROWHASH command identifies a rowhash-level lock request. Syntax ROWHASH ROWH DBname.Tablename ALL TypeAndIndex RowHash1 RowHash2 KY01A094 where: Syntax element... Specifies... DBname.Tablename TypeAndIndex RowHash1 RowHash2 ALL the name of a database and the name of a table separated by a required period (.). a subtable identifier. A table is composed logically of one or more subtables. For example: 0 is a table header is a primary subtable. 1028, 1032, 1036, and other +4 incremental values are secondary index subtables. 2048, 3072, 4096, and other multiples of 1024 are the fallback subtables. a Teradata Database system-assigned rowhash value used to acquire a rowhash lock. Normally, this value is specified in decimal notation. a Teradata Database system-assigned rowhash value used to acquire a rowhash lock. Normally, this value is specified in decimal notation. that all tables that have a rowhash-level lock applied are considered. ALL is the default if you do not specify an object name. Utilities 89

90 Chapter 3: Lock Display (lokdisp) ROWHASH Usage Notes The following table shows the components of ROWHASH command output. Component... Specifies... Tran Host Session Mode User Database Table Row Hash currently running transactions with locks being applied. the logical host ID (origin of the transaction). the session number for the transaction. the type of lock mode: Access Read Write Exclusive the logon-id for whom the lock is being requested. the name of the database being locked. the name of the locked table. the locked row hash. Note: The rowhash lock information is provided also. Example The following example shows locks on AMPs 0 and 2 on Database RECBDQTAC and Table T1. rowhash - The following amps are available: > Which amp(s) do you want to request on (S=Sampling/A=all/C=cancel/ Q=quit): > a a AMP 0 REPORTS 1 LOCK ENTRIES GRANTED LOCK REQUEST(S): Tran: Host: 2049 Session: 0, 1000 Mode: WR User: DBC Database: RECBDQTAC Table: T1 Row Hash Lock Subtable ID: 1536 Row Hash1: 62321, Utilities

91 Chapter 3: Lock Display (lokdisp) ROWHASH AMP 2 REPORTS 2 LOCK ENTRIES GRANTED LOCK REQUEST(S): Tran: Host: 2049 Session: 0, 1000 Mode: WR User: DBC Database: RECBDQTAC Table: T1 Row Hash Lock Subtable ID: 1024 Row Hash1: 31158,40503 Host: 2049 Session: 0, 1000 Mode: WR User: DBC Database: RECBDQTAC Table: T1 Row Hash Lock Subtable ID: 1536 Row Hash1: 59106,30941 Utilities 91

92 Chapter 3: Lock Display (lokdisp) ROWRANGE ROWRANGE Purpose The ROWRANGE command identifies a rowrange-level lock request. Syntax ROWRANGE ROWR DBname.Tablename ALL TypeAndIndex KY01A095 where: Syntax element... Specifies... DBname.Tablename TypeAndIndex ALL the name of a database and the name of a table separated by a required period (.). a subtable identifier. A table is composed logically of one or more subtables. For example: 0 is a table header is a primary subtable. 1028, 1032, 1036, and other +4 incremental values are secondary index subtables. 2048, 3072, 4096, and other multiples of 1024 are the fallback subtables. that all tables that have a rowrange-level lock request are considered. ALL is the default if you do not specify the command parameters. Usage Notes The following table shows the components of ROWRANGE command output. Component... Specifies... Tran Host Session the currently running transactions with locks being applied. the logical host ID (origin of the transaction). the session number for the transaction. 92 Utilities

93 Chapter 3: Lock Display (lokdisp) ROWRANGE Component... Specifies... Mode User Database Table Row Range the type of lock mode: Access Read Write Exclusive the logon-id for whom the lock is being requested. the name of the database being locked. the name of the table being locked. the range of rows being locked. Example The following example shows locks on AMP 0 on Database STAFF and Table MANAGEMENT. > rowrange staff.management 0 rowrange staff.management 0 - The following amps are available: > Which amp(s) do you want to request on (S=Sampling/A=all/C=cancel/ Q=quit): > a a AMP 0 REPORTS 1 LOCK ENTRIES BLOCKED LOCK REQUEST(S): Tran: Host: 0 Session: 0, 2053 Mode: Ac User: TD Database: STAFF Table: MANAGEMENT Row Range Lock Subtable ID: 0 Row Hash1: 0, 1 Row Hash2: 0, 2 # Utilities 93

94 Chapter 3: Lock Display (lokdisp) TABLE TABLE Purpose The TABLE command identifies a table-level lock request. Syntax TABLE TA DBname.Tablename ALL KY01A093 where: Syntax element... Specifies... DBname.Tablename ALL the name of a database and the name of a table separated by a required period (.). that all tables (from all databases) that have a table-level lock request are considered. ALL is the default if you do not specify an object name. Usage Notes The following table shows the components of TABLE command output. Component... Specifies... Tran Host Session Mode User the currently running transactions with locks being applied. the logical host ID (origin of the transaction). the session number for the transaction. the type of lock mode: Access Read Write Exclusive the logon-id for whom the lock is being requested. 94 Utilities

95 Chapter 3: Lock Display (lokdisp) TABLE Component... Specifies... Database Table the name of the database being locked. the name of the locked table. Example 1 The following example shows the locks on AMP 0 on the database RECBDQTAC and table T1: table - The following amps are available: > Which amp(s) do you want to request on (S=Sampling/A=all/C=cancel/ Q=quit): > a a AMP 0 REPORTS 1 LOCK ENTRIES GRANTED LOCK REQUEST(S): Tran: Host: 2049 Session: Database: RECBDQTAC 0, 1000 Mode: WR* User: DBC Table: T AMP 2 REPORTS 1 LOCK ENTRIES GRANTED LOCK REQUEST(S): Tran: Host: 2049 Session: 0, 1000 Mode: WR* User: DBC Database: RECBDQTAC Table: T1 Example 2 The following is an example of trying to display table-level locks on a table while trying to create the table. table all - The following amps are available: 0 -> Which amp(s) do you want to request on (S=Sampling/A=all/C=cancel/Q=quit): A Host: 7169 Session: 0, 1441 Mode: EX User: DBC Utilities 95

96 Chapter 3: Lock Display (lokdisp) TABLE Database: STAFF Table:?????????????????????????????? Table name is not printed. 96 Utilities

97 Chapter 3: Lock Display (lokdisp) TRAN TRAN Purpose The TRAN command identifies currently running transactions with locks being applied. Syntax TRAN TR ProcId ALL Uniq1 Uniq2 KY01A092 where: Syntax element... Specifies... ProcId Uniq1 Uniq2 ALL the virtual processor number of the parsing engine processor handling the transaction. Since virtual processor numbers are designated as integer numbers, the corresponding value for this option normally is specified in decimal notation. This number is the first component of a transaction ID. a value that is normally specified as four hexadecimal digits. This value is the second component of a transaction ID. a value that is normally specified as four hexadecimal digits. This value is the third component of a transaction ID. that all blocked transactions and their corresponding blocker transactions that will be considered. ALL is the default if you do not specify an ProcId. Note: Together, ProcId, Uniq1, and Uniq2 identify a transaction ID. Usage Notes A transaction is an internal database concept. A transaction can have more than one blocking transaction. For example, a transaction can have five lock requests, and five transactions can block those same lock requests. In other words, if you have five tables, then conceivably, five other transactions can have the locks on those same five tables. Each logically grouped display represents one lock request. Only object names relevant to a given lock request are displayed. Utilities 97

98 Chapter 3: Lock Display (lokdisp) TRAN For example, only the database name is displayed for a database lock, whereas both a database name and a table name are displayed for a table lock. The following table shows the components of TRAN command output. Component... Specifies... Tran Host Session Mode User Database Table DUMMY LOCK the currently running transactions with locks being applied. the logical host ID (origin of the transaction). the session number for the transaction. the type of lock mode: Access Read Write Exclusive the logon-id for whom the lock is being requested. the name of the database being locked. the name of the locked table. the specific row has lock applied on a distinct pseudo dictionary table when applicable to facilitate concurrency control. The pseudo dictionary table does not exist. The table ID is used as the value of the row hash. Example 1 The following example shows the transactions on all AMPs, with AMP 0 having four lock entries, and AMP1 having three lock entries. -> Please enter your selection from the list: tr - The following amps are available: > Which amp(s) do you want to request on (S=Sampling/A=all/C=cancel/ Q=quit): a -> Please enter your selection from the list: tr all - The following amps are available: 0 1 -> Which amp(s) do you want to request on (S=Sampling/A=all/C=cancel/ Q=quit): a AMP 0 REPORTS 4 LOCK ENTRIES Utilities

99 Chapter 3: Lock Display (lokdisp) TRAN GRANTED LOCK REQUEST(S): Tran: EE0 Host: 1025 Session: 0, 1001 Mode: Ac User: DBC Database: DBC Table: DBASE Host: 1025 Session: 0, 1001 Mode: Ac User: DBC Database: DBC Table: TVM Host: 1025 Session: 0, 1001 Mode: WR User: DBC Database: RKPMED Table: STORES DUMMY LOCK Host: 1025 Session: 0, 1001 Mode: WR User: DBC Database: RKPMED Table: STORES AMP 1 REPORTS 3 LOCK ENTRIES GRANTED LOCK REQUEST(S): Tran: EE0 Host: 1025 Session: 0, 1001 Mode: Ac User: DBC Database: DBC Table: DBASE Host: 1025 Session: 0, 1001 Mode: Ac User: DBC Database: DBC Table: TVM Host: 1025 Session: 0, 1001 Mode: WR User: DBC Database: RKPMED Table: STORES < END OF OUTPUT > Example 2 This example shows a blocked row hash lock request. Note the hash mark (#) that appears next to the blocked row hash, indicating that the lock was requested, but has not yet been granted. LOCK DISPLAY UTILITY Command String Syntax: Help or? TRan [ProcId Uniq1 Uniq2] [ALL] Db [DBname] [ALL] TAble [DBname.Tablename] [ALL] ROWRange [DBname.Tablename TypeAndIndex] [ALL] ROWHash [DBname.Tablename TypeAndIndex, RowHash1 RowHash2] [ALL] Blockers [TRAN [ProcId Uniq1 Uniq2] [ALL]] [LIMIT [Number] [NONE]] Quit -> Please enter your selection from the list: tr - The following amps are available: Utilities 99

100 Chapter 3: Lock Display (lokdisp) TRAN > Which amp(s) do you want to request on (S=Sampling/A=all/C=cancel/ Q=quit): a AMP 2 REPORTS 2 LOCK ENTRIES GRANTED LOCK REQUEST(S): Tran: AACE Host: 1076 Session: 0,2013 Mode: EX User: USER1 Database: DBASE1 Table: TBL_1A Row Hash1: 31158,40503 BLOCKED LOCK REQUEST(S): Tran: AAD2 Host: 1076 Session: 0,2012 Mode: EX User: USER2 Database: DBASE1 Table: TBL_1A Row Hash1: 31158,40503# 100 Utilities

101 CHAPTER 4 Locking Logger (dumplocklog) The Locking Logger utility, dumplocklog, creates a table of lock information extracted from Teradata Database transaction logs. You can use this table to determine whether Teradata Database system performance has been degraded by an inappropriate mix of SQL statements. To use the Locking Logger, you must first enable lock logging. Use the DBS Control utility, described in Utilities - Volume 1, to set the LockLogger field of the DBS Control Record to TRUE. When logging is enabled, Teradata Database maintains ongoing logs of the following: Transaction identifiers Session identifiers Lock object identifiers Lock levels associated with executing SQL statements that have been delayed because of database lock contention Global deadlocks Audience Users of Locking Logger include the following: Teradata Database engineers Teradata Database system administrators Teradata Database system programmers User Interfaces dumplocklog runs on the following platforms and interfaces: Platform MP-RAS Windows Linux Interfaces Database Window Command line ( Teradata Command Prompt ) Database Window Command line Database Window Utilities 101

102 Chapter 4: Locking Logger (dumplocklog) Transaction Lock Log Information For general information on starting the utilities from different platforms and interfaces, see Appendix B: Starting the Utilities. Transaction Lock Log Information When lock logging is enabled, each Teradata Database system AMP creates a circular memory buffer for saving transaction lock log information, including logging information for global deadlocks. Host Utility (HUT) locks are included in global deadlock detection. When the buffer is full, the next entry overwrites the first. This provides a continuously updated log of the transaction locks encountered by each AMP. The default size of the lock log buffers is 64 KB. You can change the size by changing the value of the LockLogSegmentSize field in the DBS Control record from 64 to 1024 KB. This value indicates the size of the locking logger segments. The lock log segment size is divided into two parts: main and partial. The last 32 KB of the lock log segment is the partial part and contains global deadlock information. Both parts contain information about the locks. For more information on the LockLogSegmentSize field, see the DBS Control utility in Utilities. When a transaction encounters a lock contention delay, the AMP writes an entry in the lock log buffer that includes object identifiers containing the following information concerning the delayed transaction: The date and time the transaction lock was requested The length of time the blocked transaction was blocked The database and table identifiers of the table upon which the lock was requested The host ID and session number of the transaction request that was locked The host ID and session number of the transaction that imposed the lock The processor ID of the AMP where the lock was requested The lock level (database, table, row, or range of rows), and mode (read, write, exclusive), of the lock request The type of executing statement associated with the transaction (INSERT, UPDATE, SELECT, and so forth) Whether the lock request caused a deadlock LockLogger DBS Control Fields The DBS Control record has the following fields related to Locking Logger. These field values can be changed using the DBS Control utility. 102 Utilities

103 Chapter 4: Locking Logger (dumplocklog) LockLogger DBS Control Fields The field... Allows you to... LockLogger LockLogger Delay Filter LockLogger Delay Filter Time LockLogSegmentSize log the delays caused by database locks to help identify lock conflicts. The default is FALSE. control whether or not to filter out blocked lock requests based on delay time. The default is FALSE. indicate the value at which blocked lock requests with a delay time greater than this value are logged. The default is 0 seconds. specify the size of the lock log segment. The LockLogger Delay field and the LockLogger Delay Filter Time field have dependencies on the LockLogger field, as shown in the following table. IF the LockLogger field is... And the LockLogger Delay Filter field is... THEN LockLogger Delay Filter Time field is... FALSE TRUE ineffective. FALSE FALSE ineffective. TRUE FALSE ineffective. TRUE TRUE effective. The following table shows when the setting for each field takes effect. The field... Becomes effective... LockLogger LockLogger Delay Filter LockLogger Delay Filter Time LockLogSegmentSize after the next Teradata Database system restart. after the DBS Control Record has been written or applied and only if the LockLogger field is set to TRUE. after the DBS Control Record has been written or applied and only if the LockLogger field and the LockLogger Delay Filter field are set to TRUE. after the next Teradata Database system restart. For more information, see DBS Control Utility in Utilities Volume 1. Utilities 103

104 Chapter 4: Locking Logger (dumplocklog) Lock Logger Table Requirements Lock Logger Table Requirements Lock log tables allow you to define the information that you want to retrieve from the lock log buffers. When using Locking Logger to create a lock log table, you must provide the following information. Required Information User name and password Description Since Locking Logger uses standard Teradata SQL statements to create the lock log table and insert the information from the lock log buffers, you must have appropriate database access privileges. IF the table is... THEN you must have... new existing CREATE TABLE privileges. table or database INSERT privileges. Number of SQL sessions Locking Logger will use to perform the INSERT operation The minimum is one session; the maximum is one session for each online AMP. The following restrictions affect the performance and ability of Locking Logger to run. IF Locking Logger runs in... THEN there... continuous mode snapshot mode should be at least one or more free console sessions per PE. If the ratio of AMPs to PEs is at least three to one, Locking Logger should have no problem running. But if the ratio is six to one or higher, Locking Logger cannot run in continuous mode. must be one or more free console session per PE (no matter what the ratio of AMPs to PEs) for Locking Logger to run. Note: The maximum number of sessions is limited by the number of PEs. 104 Utilities

105 Chapter 4: Locking Logger (dumplocklog) Lock Log Tables Required Information Type of mode of Locking Logger Description Locking Logger has the following types of modes. IF the type of mode is... THEN Locking Logger creates... single-snapshot continuous lock log table entries from a single copy of the current contents of the lock log buffer for each AMP. table entries from the first copy of the contents of the lock log buffer for each AMP, then gets additional buffer entries, as they are created, translating them into additional lock log table rows. Character set of the table name Name of the lock log table to be created Time constraints that you want to use for selecting entries from the lock log buffers Names of any specific database objects whose lock log entries you want to select. This parameter dictates how the input is to be interpreted internally by the Locking Logger and the Teradata Database system. You can specify either an existing table or a new table. For detailed information on naming a table, see Basic SQL Syntax and Lexicon in SQL Reference: Fundamentals. You can select lock log entries that were created for the following: Within a specified time range At or after a specified time At or before a specified time The default is no time constraint. You can select the following objects: A specific database and a specific table A specific database and all of the tables A specific table under the default database for your user name You can select up to 10 objects. If you do not specify any objects, the default specification selects all tables from all databases. Lock Log Tables Note: In order to create a lock log table, you must have CREATE TABLE privileges. Also, if you are updating an existing table, you must have INSERT privileges for the table or database. To create lock log tables after starting Locking Logger, do the following: 1 Enter your logon string: <username,password> (Q/q to quit) After entering your logon string, the following message appears. 2 Do you want this utility to run continuously? (Y/N): Utilities 105

106 Chapter 4: Locking Logger (dumplocklog) Lock Log Tables IF you answer... THEN you specify the... Y N continuous run mode whereby rows are added to your table as additional lock log buffer entries are created. This continues until you terminate the utility, or until the size of the table consumes all available Teradata Database system storage. If your username and password are validated, you go directly to Step 4. If the username and password cannot be validated, the utility terminates at this point. single-snapshot mode whereby the utility creates or updates your lock log table from a single copy of the lock log buffer for each Teradata Database system AMP. If you answer N, and specify the single-snapshot mode, the number of sessions prompt appears. 3 Enter number of sessions (? For Help, Q/q to Quit): Number of concurrent sessions Description Minimum The minimum number of sessions is equal to the number of AMPs + 1. Maximum Based on the following: Because of a limit of four console sessions per PE, the maximum number of sessions is whichever is lower: The number of online AMPs The number of PEs The default is the maximum: one session per online AMP: To select the default, type an asterisk (*). If you type an invalid number, the utility displays an error message and repeats the number of sessions prompt. 4 Enter the Character Set (? for Help, Q/q to Quit): STRING - Interpreted as a CHARACTERSET NAME. NUMBER - Interpreted as a CHARACTERSET CODE. Note: The first character of the input dictates this rule. Example: 123ascii is read as 123. * (asterisk) - The default character set, which is usually ASCII for a network-attached machine and EBCDIC for a channel-connected Teradata Database system.? (question mark)- Lists the character sets installed on your Teradata Database system. Note: Depending on the particular host connection of your machine, you might not be able to use all of the following available character sets: 106 Utilities

107 Chapter 4: Locking Logger (dumplocklog) Lock Log Tables Code Character Set Name 127 ASCII 64 EBCDIC User-defined 5 Enter the table name where the lock log entries will be written (? for Help, Q/q to Quit): Specify a new table or an existing table. You must have the appropriate database access privileges. Note: Table name entries on a Kanji machine must be in hex format, such as '82eb82ae'XN, an even number of hex characters contained in single quotes immediately followed by the letters XN. To specify a table... Type... for a database other than the default database of your logon username that is under the default database of your logon username both the database name and the table name as follows: <name1>.<name2> where: <name1> specifies the database name. <name2> specifies the table name. only the table name as follows: <name1> where: <name1> specifies the table name. 6 Do you want this utility to create table <tablename> (Y/N): Y - If you specified a new table name N - If you specified an existing table name 7 Enter the time constraint to control selection of lock log entries that were generated AT or LATER than this time YYYYMMDD HHMMSS (? For Help, Q/q to Quit): Note: This is the first of two time constraint prompts that ask you to specify a time period for selecting lock log entries. To specify all entries that were created within a range of times, specify both an AT or LATER and an AT or PRIOR time constraint. To select all entries from the lock log buffers, regardless of time, type an asterisk (*). Time constraints are specified using the following format: YYYYMMDD HHMMSS Utilities 107

108 Chapter 4: Locking Logger (dumplocklog) Lock Log Tables where: YYYY=Year Range = 1901 to 9999 MM = Month Range = 01 to 12 DD = Day Range = 01 to 31 HH = Hour Range = 00 to 23 MM = Minute Range = 00 to 59 SS = Second Range = 00 to 59 Note: If you answered Y at Step 2 to specify the continuous run mode, skip to Step 8 and specify the database object constraints for selecting lock log entries. If you entered N at Step 2 to specify the single-snapshot mode, you are prompted to type the latest time of the range of lock log entries that you want to select. 8 Enter the time constraint to control selection of lock log entries that were generated AT or PRIOR TO this time YYYYMMDD HHMMSS (? For Help, Q/q to quit): If entries were created for a specified range of times, type the AT or PRIOR time of the range using the same format as in Step 7. 9 Enter the object constraint to select lock log entries <database.table> (? For Help, Q/q to quit): You can specify up to 10 database objects for selecting lock log entries. If you do not want to specify any database objects, type an asterisk (*) and skip to Step 11. After you type the first object constraint, the utility prompts you to type another object. To specify a... Type... table for a database other than the default database of your logon username table that is under the default database of your logon username both the database name and the table name as follows: <name1>.<name2> where: <name1> specifies the database name. <name2> specifies the table name. only the table name as follows: <name1> where: <name1> specifies the table name. 108 Utilities

109 Chapter 4: Locking Logger (dumplocklog) Hexadecimal and Non-Standard Names Support To specify a... Type... database and all of the tables under it the database name and an asterisk (*) as follows: <name>.* where: <name> specifies the database name. * specifies all of the tables under the database. 10 more? <database.table> (? For Help, <Ret> for Done): The utility will redisplay the more? prompt until you have specified ten object constraints, or until you press the carriage return key without specifying another object. 11 After you specify the database object constraints, the utility initiates the table CREATE and INSERT tasks and displays the following statement and prompt: Writing lock log entries to table <tablename> Press <F2> anytime to stop the utility If you specified the single-snapshot mode in Step 2, or if you entered a prior-to time constraint in Step 7, the utility stops when it completes the single-snapshot operation. If you specified the continuous run mode in Step 1 with no prior-to time constraint in Step 7, the utility runs continuously until you stop it by pressing the F2 function key, or until the size of your table grows to consume all available Teradata Database system storage. 12 The final display indicates the total number of rows that were inserted in the table that you specified in Step 5: <positive integer> rows have been inserted to table <tablename> *** DumpLockLog is terminated *** For a description of the structure of the lock log table that Locking Logger creates and example SQL procedures for joining your table with the Teradata Database system DBase, TVM, and EventLog tables to produce a meaningful output report, see Producing a Lock Log Report on page 111. Hexadecimal and Non-Standard Names Support Hexadecimal Syntax For hexadecimal name support, Locking Logger allows you to type log table names and lock object names in hexadecimal format and in non-standard format (names are surrounded by double quotes). The hexadecimal format is as follows: '...'XN.'...'XN Utilities 109

110 Chapter 4: Locking Logger (dumplocklog) Hexadecimal and Non-Standard Names Support where: Syntax element... Is the string of a hexadecimal number. Digit 0-9. Char a - f or A- F. Quotation Marks in Object Names To input an object constraint in Locking Logger, an object name must be double quoted. Any embedded double quotes in the object name must have a single quote in front of the embedded double quote. Teradata Database Name Examples The following are examples of acceptable Teradata Database names: ABC'DB1.cjh'single JOSE"DB.table 'a XYZ'S DATA"BASE.tes't"3 "DB " 30' sl' dl' space' chars."tbl " 30' sl' dl' spce' chars 'employee''"database.'''employee""table The following are examples of the same database names modified to be accepted as object constraints by Locking Logger. The names are quoted, and a single quote is placed in front of any embedded double quote. "ABC'DB1"."cjh'single" "JOSE'"DB"."table 'a" "XYZ'S DATA'"BASE"."tes't'"3" "'"DB '" 30' sl' dl' space' chars"."'"tbl '" 30' sl' dl' spce' chars" "'employee'''"database"."'''employee'"'"table" To be accepted by Teradata Database, non-standard names must be quoted, and any embedded double quote is identified by a double quote placed in front of the embedded double quote. The following are the same Teradata Database names modified to be accepted in Teradata SQL statements. "ABC'DB1"."cjh'single" "JOSE""DB"."table 'a" "XYZ'S DATA""BASE"."tes't""3" """DB "" 30' sl' dl' space' chars"."""tbl "" 30' sl' dl' spce' chars" "'employee''""database"."'''employee""""table" For detailed information on naming objects, see Basic SQL Syntax and Lexicon in SQL Reference: Fundamentals. 110 Utilities

111 Chapter 4: Locking Logger (dumplocklog) Producing a Lock Log Report Producing a Lock Log Report The lock log table that is created by Locking Logger uses the following structure: CREATE SET TABLE DHV.LL,FALLBACK, NO BEFORE JOURNAL, NO AFTER JOURNAL ( BEGDATE DATE FORMAT 'YY/MM/DD' NOT NULL, BEGTIME FLOAT FORMAT '99:99:99.999' NOT NULL, DELAY FLOAT FORMAT '99:99:99.999' NOT NULL, DBID BYTE(4) NOT NULL, TID BYTE(6) NOT NULL, BLKDLOGHOST SMALLINT NOT NULL, BLKDSESSNO INTEGER NOT NULL, BLKDLEVEL CHAR(8) CHARACTER SET UNICODE NOT CASESPECIFIC NOT NULL, BLKDMODE CHAR(2) CHARACTER SET UNICODE NOT CASESPECIFIC NOT NULL, BLKINGLOGHOST SMALLINT NOT NULL, BLKINGSESSNO INTEGER NOT NULL, BLKINGLEVEL CHAR(8) CHARACTER SET UNICODE NOT CASESPECIFIC NOT NULL, BLKINGMODE CHAR(2) CHARACTER SET UNICODE NOT CASESPECIFIC NOT NULL, PROCESSOR SMALLINT FORMAT 'ZZZZ9' NOT NULL, DEADLOCK CHAR(1) CHARACTER SET UNICODE NOT CASESPECIFIC NOT NULL, MULTIPLEBLOCKER CHAR(1) CHARACTER SET UNICODE NOT CASESPECIFIC NOT NULL, STMTTYPE VARCHAR(20) CHARACTER SET UNICODE NOT CASESPECIFIC NOT NULL) PRIMARY INDEX ( BEGDATE,BEGTIME ); The following table describes the structure. Column Description Format and Data Type BEGDATE The date the transaction was blocked. DATE NOT NULL BEGTIME The time that the transaction became blocked. FLOAT '99:99:99.999' NOT NULL BLKDLEVEL BLKDLOGHOST BLKDMODE BLKDSESSNO The lock level of the transaction that was waiting for the lock LokDB, LokTable, LokRowRg, or LokRow. The logical host ID of the transaction that was waiting for the lock. The lock mode of the transaction that was waiting for the lock Access, Read, Write, or Excl. The session number of the transaction that was waiting for the lock. The following session numbers are used to indicate DBS internal sessions: 0 - System User 1 - System Accounting 2 - System Recovery CHAR(8) NOT NULL SMALLINT NOT NULL CHAR(2) NOT NULL INTEGER NOT NULL Utilities 111

112 Chapter 4: Locking Logger (dumplocklog) Producing a Lock Log Report Column Description Format and Data Type BLKINGLOGHOST BLKINGLEVEL BLKINGMODE BLKINGSESSNO DBID DEADLOCK DELAY MULTIPLEBLOCKER PROCESSOR STMTTYPE TID The logical host ID of the transaction that imposed the lock. The lock level of the transaction that imposed the lock LokDB, LokTable, LokRowRg, or LokRow. The lock mode of the transaction that imposed the lock. The session number of the transaction that imposed the lock. The following session numbers are used to indicate DBS internal sessions: 0 - System User 1 - System Accounting 2 - System Recovery 3 - Archive/Restore The database ID of the table on which the lock was requested. Indicates whether the lock contentions resulted in a deadlock. The following values are used to indicate the type of deadlock: N - No deadlock Y - Local deadlock G - Global deadlock The total time the transaction waited for the block. Indicates whether more than one transaction encountered the same lock contention. The identifier of the AMP where the lock was requested. The type of executing statement for the transaction that produced the lock. The table ID of the table on which the lock was requested Access, Read, Write, or Excl. SMALLINT NOT NULL CHAR(8) NOT NULL CHAR(2) NOT NULL INTEGER NOT NULL BYTE(4) NOT NULL CHAR(1) NOT NULL FLOAT '99:99:99.999' NOT NULL CHAR(1) NOT NULL SMALLINT 'ZZZZ9' NOT NULL) VARCHAR (20) NOT NULL BYTE(6) NOT NULL The rows in the table also contain the following information: Internal identifiers for the object on which the lock was requested Holder of the lock Requestor of the lock 112 Utilities

113 Chapter 4: Locking Logger (dumplocklog) Example Log Tables Example Log Tables The example lock log tables are similar in the following respects: Since the EventLog table usually is very large, the examples first try to reduce the size of this table to minimize the execution time of the join operation. Temporary tables are assigned names using non-alphabetic characters to avoid possible conflicts with existing permanent tables. MyLog represents the lock log table that was created by Locking Logger. Reducing the Size of the Tables When a lock log table is joined with DBC.EventLog, determining the blocked user from the blocking user can be difficult. Usually, this is because of a large number of rows in DBC.EventLog with the same session number, since the session number is reused whenever TDP restarts. To determine the blocked user from the blocking user, use the following: The begdate and begtime values from the lock log table The logondate and logontime values from DBC.EventLog For example, suppose that your lock log table (MyLog) and the DBC.EventLog table contain the following rows. MyLog Table DBC.EventLog Table begdatetime blkdsessno logondatetime sessionno user T2 S1 T1 S1 A T4 S2 T2 S2 B T10 S1 T3 S1 C T30 S2 T5 S1 D T9 S2 E T11 S1 F T20 S2 G To identify the user from DBC.EventLog for each row in MyLog, note the following: The first row of MyLog is <T2,S1> and there are four rows from DBC.EventLog with session number S1: Since S1 was blocked at time T2, S1 must have been logged on before T2. Therefore, user A was blocked at T2. Utilities 113

114 Chapter 4: Locking Logger (dumplocklog) Example Log Tables <T1,S1,A> <T3,S1,C> <T5,S1,D> <T11,S1,F> Similarly, the second row of MyLog, <T4,S2>, identifies user B. The third row of MyLog, <T10,S1>, has four rows from EventLog with session number S1, and three of them have a logondatetime before T10: <T1,S1,A> <T3,S1,C> <T5,S1,D> In this case, user D was blocked at T10, since the last logon time for S1 before T10 was at T5. Using the same process as before, the fourth row of MyLog identifies user G. Some of the following example SQL queries use three temporary tables: Table MYTEMPLOG_ONE to reduce the size of DBC.EventLog Table MYTEMPLOG_TWO to reduce the size of MyLog Table MYTEMPLOG_THREE to hold a join of MYTEMPLOG_TWO with fields from MYTEMPLOG_ONE, which identifies the blocked user Using unusual table names avoids conflicts with permanent tables. Reducing the Size of the Lock Log Table The following SQL statements create a temporary table that contains a portion of MyLog. The temporary table has databasename and tablename instead of internal IDs. In the following example, begtime is the combination of begdate and begtime from MyLog. This simplifies the comparison on date/time columns. drop table "MYTEMPLOG_TWO"; ct "MYTEMPLOG_TWO" (begdatetime float format 'zzz,zzz,zzz,zzz.zzz' not null, begdate date not null, begtime float format '99:99:99.999' not null, delay float format '99:99:99.999' not null, databasename char(30) not null, tablename char(30) not null, blkdloghost smallint not null, blkdsessno integer not null, blkdlevel char(8) not null, blkdmode char(2) not null, blkingloghost smallint not null, blkingsessno integer not null, blkinglevel char(8) not null, blkingmode char(2) not null, processor smallint format 'zzzz9' not null, deadlock char(1) not null, multipleblocker char(1) not null, stmttype varchar(20) not null) primary index (begdate,begtime); 114 Utilities

115 Chapter 4: Locking Logger (dumplocklog) Example Log Tables Reducing the Size of the DBC.EventLog Table Inserting Rows Similarly, the following SQL statements create a temporary table that contains a portion of DBC.EventLog: drop table "MYTEMPLOG_ONE"; ct "MYTEMPLOG_ONE" (datefld date not null, timefld float format '99:99:99.99' not null, logondatetime float format 'z,zzz,zzz,zzz,zzz.zzz' not null, sessionno integer not null, logicalhostid smallint format 'zzz9' not null, username char(30) not null, accountname char(30) not null, logonsource varchar(128)) primary index (datefld,timefld); The following SQL statements define a macro that inserts rows into the temporary tables. The macro uses four parameters: t1date, t1time specifies that only the users logged on AFTER this time should be selected from DBC.EventLog. t2date, t2time specifies that only the blockages occurring BEFORE this time should be selected from MyLog. This date and time should always be AFTER the date and time specified by t1date, t1time. Limiting the number of rows from DBC.EventLog before performing a join operation is very important because DBC.EventLog could contain millions of rows if it is not purged frequently. However, to ensure that you see all the rows from the lock log table, set the t1date, t1time parameters early enough to catch all the logons of sessions that were active at any time while Locking Logger was running (up until t2date, t2time). Therefore, if you have very long-lived sessions, select a t1date, t1time farther back in time from t2date, t2time than you would have selected if you knew all the sessions running were very short-lived. Also, you could add other parameters to this macro to further limit the analysis. If, for example, you are only interested in lock log table rows involving user Joe with account Joe1 in some time range, you could add the following: Parameters UserA Char(30) and AccountA Char(30) to the macro. Conditions (UserName = :UserA) and (AccountName = :AccountA) to the Insert-Select statement for table MYTEMPLOG_ONE. Macro for Inserting Rows into Temporary Tables replace macro LockBldTmp (t1date date, t1time float, t2date date, t2time float) as ( /*******************************************************/ /* To get all of the rows from MyLog whose blocked */ /* begin time is less than t2date/time, join with */ Utilities 115

116 Chapter 4: Locking Logger (dumplocklog) Example Log Tables /* DBC.TVM to get the table name from the table ID */ /* and with DBC.Dbase to get the database name from */ /* the database ID. A database level lock row has */ /* table name of ALL. */ /*******************************************************/ del from "MYTEMPLOG_TWO"; locking MyLog for access locking dbc.dbase for access locking dbc.tvm for access ins into "MYTEMPLOG_TWO" sel (begdate* begtime) As TS, begdate, begtime, delay, coalesce(dbase.databasename, Unknown ), coalesce(tvm.tvmname, Unknown ), blkdloghost, blkdsessno, blkdlevel, blkdmode, blkingloghost, blkingsessno, blkinglevel, blkingmode, processor, deadlock, multipleblocker, stmttype from MyLog L Left Join dbc.tvm T On L.tid = T.tvmid Left Join dbc.dbase D On L.dbid = D.databaseid where TS >= (:t1date* :t1time) And TS <= (:t2date* :t2time) /********************************************************/ /* Because DBC.EventLog may contain millions of rows, */ /* reduce it by getting only the rows that satisfy */ /* these conditions: */ /* */ /* 1. Event is logon. */ /* 2. Logon date/time is greater than t1date/time. */ /* 3. Logon date/time is less than or equal to time */ /* of last (newest) entry in MyLog. */ /* 4. The sessionno and logicalhostid of the logon */ /* is found in some row of MyLog as either */ /* blkdsessno & blkdloghost or as blkgsessno & */ /* blkingloghost. */ /********************************************************/ del from "MYTEMPLOG_ONE"; locking dbc.eventlog for access ins into "MYTEMPLOG_ONE" sel datefld, timefld, 116 Utilities

117 Chapter 4: Locking Logger (dumplocklog) Example Log Tables (logondate* logontime)as LogonTS, sessionno, logicalhostid, username, accountname, logonsource from dbc.eventlog where (event = 'Logon') and And LogonTS <= (Select max(begdatetime) From "MYTEMPLOG_TWO") And LogonTS >= (:t1date* :t1time) And ((sessionno, logicalhostid) in (Select blkdsessno, blkdloghost From "MYTEMPLOG_TWO") Or (sessionno, logicalhostid) in (Select blkingsessno, blkingloghost From "MYTEMPLOG_TWO")); /********************************************************/ /* Insert dummy rows for those sessions that are used */ /* by internal DBC system activities, such as cache */ /* management, space accounting, recovery, and so on. */ /********************************************************/ ins into "MYTEMPLOG_ONE" ('90/01/01',0,0,0,0,'SystemUser','SystemUser', 'SystemUser'); ins into "MYTEMPLOG_ONE" ('90/01/01',0,0,1,0,'SystemAccounting', 'SystemAccounting','SystemAccounting'); ins into "MYTEMPLOG_ONE" ('90/01/01',0,0,2,0,'SystemRecovery', 'SystemRecovery','SystemRecovery'); Determining the Blocked User At this point, the number of rows in temporary tables MYTEMPLOG_ONE and MYTEMPLOG_TWO should be small enough for the final statements to complete in a reasonable time. The remaining SQL query example uses MYTEMPLOG_ONE to determine the blocked user for each row in the reduced lock log, MYTEMPLOG_TWO. The resulting joined rows are placed in a global temporary table, named MYTEMPLOG_THREE which is then used for a similar final join with MYTEMPLOG_ONE to determine the blocking user for each row in the reduced lock log. The following join conditions use a correlated subquery to select the maximum logondatetime from MYTEMPLOG_ONE for a given begdatetime and logical host/session number from MYTEMPLOG_TWO : ("MYTEMPLOG_ONE".logicalhostid = "MYTEMPLOG_TWO".blkdloghost ) AND ("MYTEMPLOG_ONE".sessionno = "MYTEMPLOG_TWO".blkdsessno ) AND ("MYTEMPLOG_ONE".logondatetime = (SELECT MAX(ev3.logondatetime) FROM "MYTEMPLOG_ONE" AS ev3 WHERE (ev3.logicalhostid Utilities 117

118 Chapter 4: Locking Logger (dumplocklog) Example Log Tables ) ) = "MYTEMPLOG_TWO".blkdloghost) AND (ev3.sessionno = "MYTEMPLOG_TWO".blkdsessno ) AND (ev3.logondatetime < "MYTEMPLOG_TWO".begdatetime) This results in a unique (possibly null, if no match on logical host/session number exists) row from MYTEMPLOG_ONE for each row in MYTEMPLOG_TWO. Using the sample rows described earlier: ("MYTEMPLOG_ONE".logicalhostid = "MYTEMPLOG_TWO".blkdloghost) AND ("MYTEMPLOG_ONE".sessionno = "MYTEMPLOG_TWO".blkdsessno ) returns: "MYTEMPLOG_TWO" "MYTEMPLOG_ONE" <T2,S1> X <T1,S1,A>, <T3,S1,C>, <T5,S1,D>, <T11,S1,F> ^^ ^^ ^^ ^^ ^^ <T4,S2> X <T2,S2,B>, <T9,S2,E>, <T20,S2,G> ^^ ^^ ^^ ^^ <T10,S1> X <T1,S1,A>, <T3,S1,C>, <T5,S1,D>, <T11,S1,F> ^^ ^^ ^^ ^^ ^^ <T30,S2> X <T2,S2,B>, <T9,S2,E>, <T20,S2,G> ^^ ^^ ^^ ^^ and: ("MYTEMPLOG_ONE".logondatetime = (SELECT MAX(ev3.logondatetime) FROM "MYTEMPLOG_ONE" AS ev3 WHERE (ev3.logicalhostid = "MYTEMPLOG_TWO".blkdloghost) AND (ev3.sessionno = "MYTEMPLOG_TWO".blkdsessno ) AND (ev3.logondatetime < "MYTEMPLOG_TWO".begdatetime) ) ) returns: <T2,T1>, <T4,T2>, <T10,T5>, <T30,T20> Hence, using the result from the correlated subquery above, we are able to identify the proper users (A, B, D and G) for these rows: <A> : <T2,S1><T1,S1,A> in <T2,T1> ^^ ^^ ^^ ^^ <B> : <T4,S2><T2,S2,B> in <T4,T2> ^^ ^^ ^^ ^^ <D> : <T10,S1><T5,S1,D> in <T10,T5> ^^^ ^^ ^^^ ^^ <G> : <T30,S2><T20,S2,G> in <T30,T20> ^^^ ^^^ ^^^ ^^^ 118 Utilities

119 Chapter 4: Locking Logger (dumplocklog) Example Log Tables The following two SQL statements create the global temporary table that contains the reduced lock log information joined with the blocked user information: DROP TABLE "MYTEMPLOG_THREE"; CREATE GLOBAL TEMPORARY TABLE "MYTEMPLOG_THREE" ( begdatetime FLOAT FORMAT 'zzz,zzz,zzz,zzz.zzz' NOT NULL, begdate DATE NOT NULL, begtime FLOAT FORMAT '99:99:99.999' NOT NULL, delay FLOAT FORMAT '99:99:99.999' NOT NULL, databasename CHAR(30) NOT NULL, tablename CHAR(30) NOT NULL, blkdlevel CHAR(8) NOT NULL, blkdmode CHAR(2) NOT NULL, blkdloghost SMALLINT NOT NULL, blkdusernm CHAR(30) NOT NULL, blkdsessno INTEGER NOT NULL, blkdacctnm CHAR(30) NOT NULL, blkdlogonsrc VARCHAR(128), blkinglevel CHAR(8) NOT NULL, blkingmode CHAR(2) NOT NULL, blkingloghost SMALLINT NOT NULL, blkingsessno INTEGER NOT NULL, processor SMALLINT FORMAT 'zzzz9' NOT NULL, deadlock CHAR(1) NOT NULL, multipleblocker CHAR(1) NOT NULL, stmttype VARCHAR(20) NOT NULL ) PRIMARY INDEX (begdate, begtime); The remainder of the SQL example demonstrates a macro that populates MYTEMPLOG_THREE and then does a SELECT from it. The SELECT does another join with MYTEMPLOG_ONE, providing the blocking user information and producing the final report. REPLACE MACRO LockDisplay AS ( DELETE FROM "MYTEMPLOG_THREE"; /* Instantiate a local instance of the ** MYTEMPLOG_THREE table template by ** populating it with rows from MYTEMPLOG_TWO ** joined with blocked user information ** from MYTEMPLOG_ONE. */ INSERT INTO "MYTEMPLOG_THREE" SELECT "MYTEMPLOG_TWO".begdatetime, "MYTEMPLOG_TWO".begdate, "MYTEMPLOG_TWO".begtime, "MYTEMPLOG_TWO".delay, "MYTEMPLOG_TWO".databasename Utilities 119

120 Chapter 4: Locking Logger (dumplocklog) Example Log Tables, "MYTEMPLOG_TWO".tablename, "MYTEMPLOG_TWO".blkdlevel, "MYTEMPLOG_TWO".blkdmode, "MYTEMPLOG_TWO".blkdloghost, COALESCE ("MYTEMPLOG_ONE".username, 'Unknown'), "MYTEMPLOG_TWO".blkdsessno, COALESCE ("MYTEMPLOG_ONE".accountname, 'Unknown'), COALESCE ("MYTEMPLOG_ONE".logonsource, 'Unknown'), "MYTEMPLOG_TWO".blkinglevel, "MYTEMPLOG_TWO".blkingmode, "MYTEMPLOG_TWO".blkingloghost, "MYTEMPLOG_TWO".blkingsessno, "MYTEMPLOG_TWO".processor, "MYTEMPLOG_TWO".deadlock, "MYTEMPLOG_TWO".multipleblocker, "MYTEMPLOG_TWO".stmttype FROM "MYTEMPLOG_TWO" LEFT OUTER JOIN "MYTEMPLOG_ONE" ON ("MYTEMPLOG_ONE".logicalhostid = "MYTEMPLOG_TWO".blkdloghost ) AND ("MYTEMPLOG_ONE".sessionno = "MYTEMPLOG_TWO".blkdsessno ) AND ("MYTEMPLOG_ONE".logondatetime = (SELECT MAX(ev3.logondatetime) FROM "MYTEMPLOG_ONE" AS ev3 WHERE (ev3.logicalhostid = "MYTEMPLOG_TWO".blkdloghost) AND (ev3.sessionno = "MYTEMPLOG_TWO".blkdsessno ) AND (ev3.logondatetime < "MYTEMPLOG_TWO".begdatetime) ) ); /* Now do the final select in a similar fashion, ** filling in the user info for the blocking session. ** But now we select from the global temporary table ** instantiation instead of the reduced lock ** log "MYTEMPLOG_TWO". */ SELECT "MYTEMPLOG_THREE".begdate (NAMED RequestedDate) (FORMAT 'YYYY/MM/DD') (CHAR(10)), "MYTEMPLOG_THREE".begtime (NAMED RequestedTime) (FORMAT '99:99:99') (CHAR(8)), "MYTEMPLOG_THREE".delay (NAMED Delay) (FORMAT '99:99:99.999') (CHAR(12)), "MYTEMPLOG_THREE".databasename (NAMED DataBaseName) 120 Utilities

121 Chapter 4: Locking Logger (dumplocklog) Example Log Tables, "MYTEMPLOG_THREE".tablename (NAMED TableName), "MYTEMPLOG_THREE".blkdlevel (NAMED BlockedLockLevel), "MYTEMPLOG_THREE".blkdmode (NAMED BlockedLockMode), "MYTEMPLOG_THREE".blkdloghost (NAMED BlockedHostId) (FORMAT 'zzz9') (CHAR(4)), "MYTEMPLOG_THREE".blkdusernm (NAMED BlockedUser), "MYTEMPLOG_THREE".blkdacctnm (NAMED BlockedAccount), "MYTEMPLOG_THREE".blkdlogonsrc (NAMED BlockedLogonSource), "MYTEMPLOG_THREE".blkinglevel (NAMED BlockingLockLevel), "MYTEMPLOG_THREE".blkingmode (NAMED BlockingLockMode), "MYTEMPLOG_THREE".blkingloghost (NAMED BlockingHostId) (FORMAT 'zzz9') (CHAR(4)), coalesce("mytemplog_one".username, 'Unknown') (NAMED BlockingUser) (CHAR(30)), coalesce("mytemplog_one".accountname, 'Unknown') (NAMED BlockingAccount) (CHAR(30)), coalesce("mytemplog_one".logonsource, 'Unknown') (NAMED BlockingLogonSource), "MYTEMPLOG_THREE".processor (NAMED VProc) (FORMAT 'zz9-9')(char(5)), "MYTEMPLOG_THREE".deadlock (NAMED DeadLock), "MYTEMPLOG_THREE".multipleblocker (NAMED MultipleBlockers), "MYTEMPLOG_THREE".stmttype (NAMED StmtType) FROM "MYTEMPLOG_THREE" LEFT OUTER JOIN "MYTEMPLOG_ONE" ON ("MYTEMPLOG_ONE".logicalhostid ="MYTEMPLOG_THREE".blkingloghost ) AND ("MYTEMPLOG_ONE".sessionno = "MYTEMPLOG_THREE".blkingsessno ) AND ("MYTEMPLOG_ONE".logondatetime = (SELECT max(ev4.logondatetime) FROM "MYTEMPLOG_ONE" AS ev4 WHERE (ev4.logicalhostid = "MYTEMPLOG_THREE".blkingloghost) AND (ev4.sessionno Utilities 121

122 Chapter 4: Locking Logger (dumplocklog) Example Log Tables = "MYTEMPLOG_THREE".blkingsessno) AND (ev4.logondatetime < "MYTEMPLOG_THREE".begdatetime) ) ) ORDER by 1,2; ); /********************************************************/ /* To analyze the lock rows for users logged on after */ /* 6:30 a.m. on 92/01/02 and delays that occurred */ /* before 12:00 p.m. on 92/01/03: */ /* */ /* > EXEC LockBldTmp(920102,063000,920103,120000); */ /* */ /* > EXEC LockDisplay; */ /* */ /* To clean up the temporary tables: */ /* */ /* > Drop table "MYTEMPLOG_TWO"; */ /* */ /* > Drop table "MYTEMPLOG_ONE"; */ /* */ /* > Drop table "MYTEMPLOG_THREE"; */ /* */ /********************************************************/ Example The following shows a sample output: >dumplocklog / / \ --- / / / / \ \ \ \ \ Release Version DUMP LOCK LOG Utility (Dec 98) This utility writes lock log entries in memory to an user specified table. Enter your logon string: <username,password> (Q/q to quit) dbc,dbc Do you want this utility to run continuously? (Y/N) n Enter number of sessions (? For Help, Q/q to Quit): Utilities

123 Chapter 4: Locking Logger (dumplocklog) Example Log Tables 2 sessions will be logged on. Enter the table name where the lock log entries will be written (? For Help, Q/q to Quit): dmo.locklog Do you want this utility to create table DMO.LOCKLOG? (Y/N) y Table DMO.LOCKLOG has been created. Enter the time constraint to control selection of lock log entries that were generated AT or LATER than this time YYMMDD HHMMSS (? For Help, Q/q to Quit): Enter the time constraint to control selection of lock log entries that were generated AT or PRIOR to this time YYMMDD HHMMSS (? For Help, Q/q to Quit): Enter the object constraint for selection of lock log entries (? For Help, Q/q to Quit):? Specify the database objects for which lock delay should be selected. Up to 10 objects can be entered. Input ceases when an empty line or 10 objects have been entered. - <name1>.<name2> - name1 specifies a database and name2 specifies a table. - <name>.* - name specifies a database and all tables under it. - <name1> - name specifies a table under the user name specified in the logon. - * - All databases and tables. - <Return> - Done. - Q - Terminate the utility. Note that if database or table name is specified, it has to exist or an error will be returned. Enter the object constraint for selection of lock log entries (? For Help, Q/q to Quit): dmo.* more? (? For Help, <Ret> for Done): Writing lock log entries to table DMO.LOCKLOG. Press <F1> to interrupt the utility. 0 row has been inserted to table DMO.LOCKLOG. *** DumpLockLog is terminated *** Ready; Utilities 123

124 Chapter 4: Locking Logger (dumplocklog) Locking Logger Messages Locking Logger Messages The following table contains Locking Logger messages and their descriptions. Message Description "x rows have been inserted..." In CONTINUOUS mode, 1,000 additional rows have been generated and inserted into the target table. "*** Warning - some lock log entries have been lost from processor due to buffer overflow." "No rows inserted." "No rows have been inserted to table " In CONTINUOUS mode, some vprocs failed to insert all rows into the table because the holding buffer overflowed. In SNAPSHOT mode, the user has decided to terminate before entering all the data that Locking Logger requires to run, or Locking Logger terminated abnormally. In SNAPSHOT mode, this means a normal termination of the Locking Logger in which no rows were observed, that is, no locking contention within given parameters of the user. "1 row has been inserted to table " In SNAPSHOT mode, one single row was found and inserted successfully into the table. "%s rows have been inserted to table " In SNAPSHOT mode, more than one row was found and inserted successfully to the table. "*** DumpLockLog is terminated *** " In SNAPSHOT mode, this appears preceding a normal termination. "Utility is about to be terminated..." "Utility resumes..." In CONTINUOUS mode, this appears after the user presses <F2> to terminate Locking Logger. In CONTINUOUS mode, this appears after the user presses any key (usually the CTRL key) other than F Utilities

125 CHAPTER 5 Modify MPP List (modmpplist) The Modify MPP List utility, modmpplist, is an interactive utility that allows you to modify the node list file (by default, named mpplist). This utility is available only on Windows and Linux. modmpplist can read the real mpplist from the Teradata Configuration directory, and can create or modify a copy of the of mpplist in another location. When you must shut down a node for hardware maintenance, you can use modmpplist to place the downed node into an offline state, and to distribute the revised mpplist file on the Teradata Database system. If you use modmpplist to take a node offline, you must use modmpplist to bring the node back online. Audience Users of modmpplist include the following: Teradata Database system developers Teradata Database test and verification personnel Teradata Support Center personnel User Interfaces modmpplist runs on the following platforms and interfaces: Platform Windows Linux Interfaces Command line ( Teradata Command Prompt ) Command line For general information on starting the utilities from different platforms and interfaces, see Appendix B: Starting the Utilities. Utilities 125

126 Chapter 5: Modify MPP List (modmpplist) Syntax Syntax modmpplist -h -m file_path 1102A165 where: Syntax Element Description -h Displays general help for modmpplist. -m file_path Causes modmpplist to read settings from a specified local file in a location other than the default. Note: The local file specified with the -m option can be in any directory and have any name. Usage Notes By default, modmpplist reads from and writes to the default mpplist file. The default mpplist file is: On Windows: drive:\program Files\NCR\TDAT\tdConfig\mpplist On Linux: /etc/opt/teradata/tdconfig/mpplist To read from a different file, use the -m option of modmpplist. To write changed settings to a different file, use the -w option of the write command. For more information, see WRITE on page 134. Example 1 The following example shows how to start modmpplist on Windows to edit the default mpplist. Note the minus sign prefacing the offline node in the output from the list command. D:\>modmpplist reading default mpplist, D:\Program Files\NCR\TDAT\tdConfig\mpplist... 0:pdetnt5_bynet 1:pdetnt6_bynet 2:pdetnt7_bynet 3:pdetnt8_bynet all 4 nodes are online. 126 Utilities

127 Chapter 5: Modify MPP List (modmpplist) Usage Notes mpp> off 1 1 node is offline. (Buffer has been Modified since last read) mpp> list 0:pdetnt5_bynet -1:pdetnt6_bynet 2:pdetnt7_bynet 3:pdetnt8_bynet 1 node is offline. (Buffer has been Modified since last read) mpp> display # This file is generated by PUT. Please do not # edit it manually. Note a # or a space character in # the first column on a line causes the entire line to # be ignored. Field delimiter must be space character. # node tpa nodeid status # pdetnt5_bynet yes 43 yes pdetnt6_bynet yes 44 no pdetnt7_bynet yes 45 yes pdetnt8_bynet yes 46 yes (Buffer has been Modified since last read) mpp> write Do you really want to distribute mpplist file (yes no)? [no] yes All 4 node(s) have connected MODE SIZE INODE USER GROUP FILE -rw-r--r <anon> <anon> D:\TEMP\2\mpplist pdetnt5_bynet:1924: send completed: 485 bytes received (1 files/0 directories) pdetnt6_bynet:2933: send completed: 485 bytes received (1 files/0 directories) pdetnt7_bynet:3862: send completed: 485 bytes received (1 files/0 directories) pdetnt8_bynet:4256: send completed: 485 bytes received (1 files/0 directories) Wrote and distributed mpplist to 4 nodes successfully. mpp> quit D:> Example 2 The following example shows how to start modmpplist on Windows to edit a user-specified mpplist file named mympplist. Note that after writing to the local file, modmpplist will still ask if you want to save the mpplist file. This refers to the default mpplist file. If you are just working with a local file, with no desire to change the mpplist settings on all nodes, respond no to this message. D:>modmpplist -m mylist reading user s mpplist, mylist... 0:pdetnt5_bynet 1:pdetnt6_bynet 2:pdetnt7_bynet 3:pdetnt8_bynet all 4 nodes are online. Utilities 127

128 Chapter 5: Modify MPP List (modmpplist) modmpplist Commands mpp> off 2 1 node is offline. (Buffer has been Modified since last read) mpp> list 0:pdetnt5_bynet 1:pdetnt6_bynet -2:pdetnt7_bynet 3:pdetnt8_bynet 1 node is offline. (Buffer has been Modified since last read) mpp> write -w mylist Do you want to write mpplist to 'mylist' on a local node (yes no)? [no] yes Wrote mpplist buffer to 'mylist' file mpp> quit You have changed a value. Do you wish to save the mpplist file? (yes no) [no] no D:> modmpplist Commands The following table lists the commands available from within the modmpplist session (that is, from the mpp> prompt). Command DISPLAY LIST OFF id_list ON id_list QUIT WRITE!COMMAND Description Outputs the current mpplist buffer as it would appear in file format to the STDOUT file. Outputs the list of node names, their unique node IDs, and the status of nodes in the current mpplist buffer to the STDOUT file. Changes the status of the IDs in the space-separated list to NO (offline). Changes the status of the IDs in the space-separated list to YES (online). Causes modmpplist to quit the interactive session. Forces the mpplist file to be written out to all nodes in the MPP system. Runs a Teradata Database or operating system command from within the modmpplist session. The modmpplist commands are discussed in detail in the following sections. 128 Utilities

129 Chapter 5: Modify MPP List (modmpplist) DISPLAY DISPLAY Purpose The DISPLAY command outputs the current mpplist buffer as it would appear in file format to the STDOUT file. Syntax DISPLAY D 1102A026 Utilities 129

130 Chapter 5: Modify MPP List (modmpplist) LIST LIST Purpose The LIST command outputs the list of node names, their unique node IDs, and the status of nodes in the current mpplist buffer to the STDOUT file. Syntax LIST L 1102A027 Usage Notes The list shows the nodes in the following format: IndexId:nodename nodestatus where: Component... Specifies... IndexId nodename nodestatus an arbitrary index number starting from 0 to N-1, where N is the number of nodes in the mpplist file. the name of a node. displays the number of nodes currently online. Note: If a node is offline, the node appears with a dash (or minus sign) in front of the IndexID in the mpplist as shown below: -IndexId:nodename If a node is online, the dash does not appear. Example The following example lists the status and ID of the nodes. mpp> l 0:pdetnt5_bynet 1:pdetnt6_bynet 2:pdetnt7_bynet 3:pdetnt8_bynet all 4 nodes are online. 130 Utilities

131 Chapter 5: Modify MPP List (modmpplist) OFF id_list OFF id_list Purpose The OFF id_list command changes the status of the IDs in the space-separated list to NO (offline). Syntax OFF id_list 1102A028 where: Syntax element... Specifies... id_list list of node IDs. Example The following example changes node 2 to offline. mpp> off 2 1 node is offline. (Buffer has been Modified since last read) Utilities 131

132 Chapter 5: Modify MPP List (modmpplist) ON id_list ON id_list Purpose The ON id_list command changes the status of the IDs in the space-separated list to YES (online). Syntax ON id_list 1102A029 where: Syntax element... Specifies... id_list list of node IDs. Example The following example changes node 3 to online. mpp> on 3 all 4 nodes are online. 132 Utilities

133 Chapter 5: Modify MPP List (modmpplist) QUIT QUIT Purpose The QUIT command causes modmpplist to quit the interactive session. Syntax QUIT Q GS03C022 Usage Notes If you modify the mpplist file, but you did not issue a WRITE command, you are asked if you want to write the current mpplist buffer to all available nodes. The default is NO. If you just press RETURN, the session exits. If you type Y (YES) at the prompt, the current mpplist buffer is written, and then the session exits. Example 1 The following example quits modmpplist if you just press RETURN. mpp> quit You have changed a value. Do you wish to save the mpplist file? (yes no) [no] Example 2 The following example quits modmpplist if you type Y (YES) to the prompt. mpp> quit You have changed a value. Do you wish to save the mpplist file? (yes no) [no] y All 1 node(s) have connected MODE SIZE INODE USER GROUP FILE -rw-r--r <anon> <anon> C:\DOCUME~1\ADMINI~1\LOCALS~1 \Temp\mpplist localhost:1043: send completed: 444 bytes received (1 files/0 directories) Wrote and distributed mpplist to 1 node successfully. Utilities 133

134 Chapter 5: Modify MPP List (modmpplist) WRITE WRITE Purpose The WRITE command forces the mpplist file to be written out to all nodes in the MPP system. Syntax WRITE W -w file_path -y 1102B030 where: Syntax element... Specifies... -w file_path to write the modified mpplist settings to a file on the local node only. This option allows you to save changes to the local node when a remote copy fails. If you specify a directory path only, then the file mpplist is written to that directory. If you specify a path and file, then the file specified is written to the path specified. If you specify a file name alone, then that file is written to the current working directory. -y to skip the confirmation message. Example The following example bypasses the prompt and writes the mpplist file to all live nodes. 134 Utilities

135 Chapter 5: Modify MPP List (modmpplist) Running External Commands Running External Commands Syntax To run a Teradata Database or operating system command from within a modmpplist session, preface the command with an exclamation mark (!).!COMMAND where: 1102A031 Syntax element... Specifies... COMMAND a Teradata Database or operating system command. Example The following example runs the dir operating system command (Windows), which shows a listing of the contents of the current directory. mpp>!dir Volume in drive D is Applications Volume Serial Number is 601E-95CA Directory of D:\Program Files\NCR 03/14/ :48 AM <DIR>. 03/14/ :48 AM <DIR>.. 03/14/ :47 AM <DIR> BYNET 05/22/ :13 PM <DIR> Common Files 05/22/ :16 PM <DIR> FaultDefn 03/14/ :34 AM <DIR> NCRput 03/14/ :48 AM 234 PackageVars 03/14/ :37 AM 207 PackageVars.prev 03/14/ :04 PM <DIR> Tdat 05/23/ :24 PM <DIR> Teradata Client 05/22/ :17 PM <DIR> Teradata GSS 2 File(s) 441 bytes 9 Dir(s) 7,787,827,200 bytes free mpp> Utilities 135

136 Chapter 5: Modify MPP List (modmpplist) Running External Commands 136 Utilities

137 CHAPTER 6 Priority Scheduler (schmon, xschmon) Priority Scheduler is a workload-management facility that controls access to system resources by the different active jobs in Teradata Database. It allows administrators to define different priorities for different categories of work, and comes with a number of flexible options. Priority Scheduler does the following: Allows you to define a prioritized weighting system based on user logon characteristics, and on category 3 (workload class) classification rules in Teradata Dynamic Workload Manager (DWM). Prioritizes the workload in your data warehouse based on this weighting system. Offers utilities to define scheduling parameters and to monitor your current system activity. Priority Scheduler includes default parameters that provide four priority levels with all users assigned to one level. To take advantage of Priority Scheduler capabilities, do the following: Assign users to more than one of the default priority levels based on your work priority strategy. Define additional priority levels and assign users to them to provide a more sophisticated priority strategy. Assign very high priority users to a very high priority level to support Active Data Warehouse applications. The first part of this chapter generally describes the structure and relationships of the scheduling components and parameters. The second part describes the following interfaces you can use to add and modify scheduling parameters: schmon - a command line interface. For detailed information, see schmon Utility on page 165. xschmon - a graphical user interface (GUI) using X-Windows (MP-RAS only). For detailed information, see xschmon Utility on page 226. Note: If Workload Definitions have been activated using Teradata Dynamic Workload Manager, schmon and xschmon cannot be used to make changes to Priority Scheduler. For more information, see the Teradata Dynamic Workload Manager User Guide. The Priority Scheduler Administrator (PSA), a Teradata Manager application, provides an easy-to-use graphical interface to define Priority Scheduler configurations and to observe scheduler performance to Teradata Manager users. Unlike schmon, PSA does not require root privileges. For more information, see the PSA documentation in the Teradata Manager User Guide. Utilities 137

138 Chapter 6: Priority Scheduler (schmon, xschmon) Audience Audience Users of Priority Scheduler include the following: Teradata Database system administrators Teradata Database system programmers Overview Priority Scheduler consists of the following three-tiered control structure to group user sessions for scheduling purposes: Resource Partition Performance Group Allocation Group Each of these components includes parameters that relate them to each other. You define and associate these components to design an environment that favors or inhibits the performance of individual sessions based on their logon account attributes. The following figure shows the hierarchical structure of Priority Scheduler. 138 Utilities

139 Chapter 6: Priority Scheduler (schmon, xschmon) Overview Hierarchy of Components of One Resource Partition Resource Partition Weight CPU Limit 1:M Performance Group 1:M Performance Period Milestone Limit Allocation Group Milestone Type 1:1 Allocation Group 1:M = one to many 1:1 = one to one Type Weight 1102E421 The following table briefly summarizes the components of Priority Scheduler. Component Descriptions Resource Partition A Resource Partition is a collection of prioritized Performance Groups. A Resource Partition carries a weight that will be compared to other Resource Partition weights. A Resource Partition can limit the total amount of CPU used by sessions assigned to its Performance Groups. Priority Scheduler provides Resource Partition zero (0) as the default partition. You can define four additional Resource Partitions. Utilities 139

140 Chapter 6: Priority Scheduler (schmon, xschmon) Overview Component Descriptions Performance Group You define Performance Groups within each additional Resource Partition. The Performance Group name matches an entry in the account ID string, which is used for logons and stored in the AccountName column of the user record in the data dictionary. Each Performance Group name must be unique. Performance Period You must define at least one Performance Period, but you can have up to eight Performance Periods per Performance Group. A Performance Period links a Performance Group to an Allocation Group. Optionally, a Performance Period allows you to change Allocation Group assignments based on time-of-day or resource usage. Allocation Group An Allocation Group carries a weight that will be compared to other Allocation Group weights. An Allocation Group can limit the total amount of CPU used by sessions under its control. Several Performance Groups within a single Resource Partition might share the same Allocation Group. Every Teradata Database logon session is assigned to a Performance Group. Performance Groups control the prioritization of jobs started by sessions under their control. When a Performance Group is defined, it is assigned to a Resource Partition. Each Resource Partition has a weight that determines the proportion of resources available to it relative to the other defined Resource Partitions. More resources are made available to Resource Partitions with higher weights. These weights participate in determining the priorities of Teradata Database jobs. Allocation Groups are also associated with Performance Groups. Like Resource Partitions, Allocation Groups have weights that determine the proportion of resources allocated to jobs under their control, relative to the other Allocation Groups that are active within the same Resource Partition. The combination of Resource Partition and Allocation Group parameters, acting through their common Performance Groups, determines the precise priorities of jobs running on Teradata Database. Each Performance Group is associated with one Allocation Group at any time, however, as an option, a Performance Group's Allocation Group can change as system conditions change. Consequently, the jobs controlled by a Performance Group may have different priorities assigned to them at different times, and their priorities can change as the jobs run. The association between a Performance Group and an Allocation Group is mediated by the Performance Group's Performance Periods. Performance Periods link Performance Groups to Allocation Groups. As an option, the Allocation Group associated with a Performance group can be dynamically changed based on current resource usage or time of day. A Performance 140 Utilities

141 Chapter 6: Priority Scheduler (schmon, xschmon) Using Priority Scheduler Group can define from one to eight Performance Periods, however the most common approach is to define only a single Performance Period per Performance Group. For more information on Priority Scheduler components, see the following: Resource Partitions on page 141 Performance Groups on page 144 Performance Periods on page 147 Allocation Groups on page 152 To configure Priority Scheduler, see schmon Utility on page 165 Using Priority Scheduler Priority Scheduler can do the following for you: Provide better service for your more important work Control resource sharing among different applications Automate changes in priority by time of day or by amount of CPU used Place a ceiling on Teradata Database system resources for specific applications When using Priority Scheduler, keep the following in mind: Start out simple, monitor, and build from there. You can change parameters at any time using the schmon utility or the Priority Scheduler Administrator, a Teradata Manager application. On MP-RAS, you must have UNIX root privileges to monitor and change parameters and settings using schmon and xschmon commands. Any changes you make to any parameter, including weight, take place immediately across all nodes in the configuration. You can delete the definitions of unused Resource Partitions, Performance Groups, and Allocation Groups using a Teradata Database system utility like schmon. The element that you want to delete cannot be in use when you perform the deletion. This means that an Allocation Group or Resource Partition must not be referenced by a Performance Group, and a Performance Group must not be referenced by a currently logged on user. You can change the name of a defined but unused Resource Partition or Performance Group to make it obvious it is unused. For example, you might name the unused Resource Partition or Performance Group UNUSED or NULL. Resource Partitions Resource Partitions divide the Teradata Database users into groups based on some use or priority strategy, such as by subject area or type of work. Utilities 141

142 Chapter 6: Priority Scheduler (schmon, xschmon) Resource Partitions Priority Scheduler provides you with a default Resource Partition named Default. You can create up to four more Resource Partitions. The default Resource Partition has a default partition weight of 100 and has four Performance Groups accessible by users. You can define additional Performance Groups in the default Resource Partition. The following table presents a logical view of Resource Partition 0. Performance group... has a weight of... L (low) 5. M (medium) 10. H (high) 20. R (rush) 40. Resources are distributed to the Teradata Database system sessions that specify a Performance Group within a Resource Partition. The parameters associated with the Performance Groups and Allocations Groups of a Resource Partition control this resource allocation. For detailed information, see the following: Performance Groups on page 144 Allocation Groups on page 152 Resource Partition Parameters You can define up to a maximum of four additional Resource Partitions. The following table briefly describes the parameters of a Resource Partition. Parameter ID Resource Partition Name Weight Limit Description An integer from zero through four that identifies the Resource Partition. Priority Scheduler provides resource partition zero as the default partition. A unique name for the Resource Partition. The name can contain no more than 16 characters. An integer value that is converted into a relative weight at execution time. The relative weight determines the proportion of Teradata Database system resources the Resource Partition will receive. An optional number from one through 100 that specifies a percentage limit on the total CPU usage. This limit will be applied to sessions assigned to the Performance Groups associated with the Resource Partition. 142 Utilities

143 Chapter 6: Priority Scheduler (schmon, xschmon) Resource Partitions Determining the Relative Weight of a Resource Partition Assigned Resource Partition weights are transformed into relative weights, based on the weights of the currently active resource partitions. Dividing the weight of a Resource Partition by the sum of the weights of all active resource partitions gives the percentage of total Teradata Database system resources that will be made available to that Resource Partition. This percentage is neither a guarantee or a limit on the amount of Resource a Partition will receive. This percentage is the proportion of resource the Resource Partition will be offered relative to other partitions. Suppose three Resource Partitions are active. Their respective weights are shown in the following table. Resource Partition... Has a weight of To determine the relative weight of each Resource Partition, do the following: 1 Add the individual respective weights of the active Resource Partitions ( ) for a sum of Divide each respective weight (10, 20, and 30) by the sum of 60. The relative weight for each partition is as follows: Partition 1 = 16% Partition 2 = 33% Partition 3 = 50% Note: The relative weight for Resource Partition 1 is 16%, rather than 17%, because Teradata Database truncates fractional values when doing relative weight calculations. Limiting Resource Partition CPU Usage Optionally, you can limit a Resource Partition to a specified percentage of CPU resource usage. This CPU limit has no affect on the scheduling strategy defined by other Priority Scheduler parameters. The relative weights of Allocation Groups and Resource Partitions are observed. The normal distribution of resources prevails within the specified amount of CPU usage. Any other CPU resource limits defined by a Teradata Database system CPU limit are observed. Suggested Resource Partition Setup The following list shows a simple approach to Resource Partition setup. Utilities 143

144 Chapter 6: Priority Scheduler (schmon, xschmon) Performance Groups 1 Leave the default Resource Partition for console utilities and other internal work including Teradata Manager. 2 Assign user work to other Resource Partitions. 3 Group applications by the importance of the work. The following table shows a simple example of this approach. Resource Partition... Has a weight of... And is used for internal work and tools 1 60 tactical queries. These are short, highly-tuned queries that facilitate decision-making in a time-sensitive environment everything else. Performance Groups The logon process assigns each user session to a Performance Group (PG). PGs determine the priorities of Teradata Database jobs (mostly database queries) that are run from the session. Each PG is associated with a Resource Partition and one or more Allocation Groups. It is the interaction of Resource Partition and Allocation Group weights that determines the priority of jobs that are run from a particular Teradata Database session. Allocation Groups are dynamically assigned to Performance Groups according to relationships defined by Performance Periods. The specific Allocation Group associated with a Performance Group can change based on the time of day or the resource usage of running jobs. Performance Periods define which Allocation Group is assigned to a Performance Group at any moment based on these conditions. For more information on Performance Periods, see Performance Periods on page 147. For more information on Allocation Groups, see Allocation Groups on page 152. The Resource Partition and Performance Periods of a Performance Group are specified when the PG is created using the schmon -p command. The following table briefly describes the parameters used to define a Performance Group. For more information on the schmon -p command, see schmon -p on page Utilities

145 Chapter 6: Priority Scheduler (schmon, xschmon) Performance Groups Parameter Description Performance Group ID An integer from 0 through 39. Note: Priority Scheduler provides four predefined Performance Groups, having IDs 0 through 3. These Performance Groups are associated with Resource Partition 0. Performance Group Name Resource Partition ID Performance Period Type Performance Periods The name of the Performance Group that allows it to be assigned to a session. For more information, see Performance Group Names on page 145. An integer from zero through four that identifies the Resource Partition owning the Performance Group. For more information, see Resource Partitions on page 141. A code that indicates the type of milestone limits used to define Performance Periods. All Performance Periods of a Performance Group will be the same type. For more information, see Performance Period Types and Limits on page 148. Specifications for one to eight Performance Periods. Each period is defined by a milestone limit and an Allocation Group identifier. You can express milestone limits in the following units: Time-of-day Session resource usage Query resource usage Performance Group Names Performance Group names must be unique and not longer than 16 characters. Use names that represent the type of work performed in each group, or that relate the groups to their associated Resource Partitions. Priority Scheduler provides four predefined Performance Groups, L, M, H, and R, within default Resource Partition 0. These groups correspond to low, medium, high, and rush, and determine the priorities given to jobs started under the control of sessions associated with these PGs. The following table lists the predefined Performance Groups for default Resource Partition 0. The weights listed are those of the Allocation Group associated with each Performance Group. Each predefined Performance Group doubles the weight assigned to the previous lowervalued Performance Group. These weights are used when assigning priorities to jobs running Utilities 145

146 Chapter 6: Priority Scheduler (schmon, xschmon) Performance Groups under each Performance Group. For more information on Allocation Groups, see Allocation Groups on page 152. Default Performance Group Default Weight L 5 M 10 H 20 R 40 Assigning Performance Groups to Users When a user logs on to the system, the session is assigned to a Performance Group that determines the priority of session jobs. Generally, each user has access to a limited subset of Performance Groups. This subset is listed in the user s account ID string, which is specified as part of the CREATE USER and MODIFY USER statements. The entire account ID string is limited to 30 characters, and stored in the Teradata Database Data Dictionary. The following rules apply to formatting Performance Group names in account ID strings: Use single quotes to delimit each PG name. Immediately preface each name with a dollar sign ($). Names longer than a single character require terminating dollar signs. Single-character names do not require the terminal $, but may include it. Because the entire account ID string is limited to 30 characters, try to keep PG names brief. Note: The Teradata Database enforces other rules for the length and format of account ID strings, which may influence the choice of Performance Group names. For more information on CREATE USER, MODIFY USER, and the Data Dictionary, see the books SQL Reference: Data Definition Statements and Data Dictionary. The following are examples of valid Performance Group names that might appear in an account ID string for a user granted access to five Performance Groups: $L,'$L1$', $M$,$M2$', $tac1$ Assigning Performance Groups to Logon Sessions Every logon session is assigned to a Performance Group, which determines the priority of jobs started during that session. Users can specify one of their assigned Performance Groups when they log on to Teradata Database. If no Performance Groups are specified during logon, the session defaults to the pre-defined Performance Group M in Resource Partition 0. The following example shows a user logging on to Teradata Database and specifying the M2 Performance Group:.logon testdb/itbatch, cab,'$m2$' 146 Utilities

147 Chapter 6: Priority Scheduler (schmon, xschmon) Performance Periods The following table describes how Teradata Database assigns Performance Groups to sessions during the logon process. IF... THEN... the logon command includes a Performance Group name matching one of the PGs assigned to the user the logon command does not include a Performance Group name the logon command includes a Performance Group name that is not specified in the account ID string portion of the user record) the logon command includes a Performance Group that is specified in the user s account ID string, but that has not yet been created using the schmon -p command the session is assigned to the specified PG. the session is assigned to the first Performance Group specified in the user s account ID string. If no PG is specified in the account ID string, the session defaults to Performance Group M. logon fails. the session defaults to Performance Group M. Performance Periods Performance Periods associate Performance Groups with Allocation Groups. A Performance Period is a value pair that specifies a limit condition ( milestone ) and an Allocation Group. Performance Periods are specified when Performance Groups are defined. Each Performance Group can specify from one to eight Performance Periods. For more information on defining Performance Groups, see schmon -p on page 209. The logon process assigns each user session to a Performance Group, which controls how resources are allocated to session processes. The Performance Periods defined for the Performance Group determine which Allocation Groups will govern session processes. Performance Groups typically have only a single Performance Period. This is the case for the default Performance Groups in the default Resource Partition. Sessions controlled by these Performance Groups will have their resource allocation determined by a single Allocation Group. Optionally, Performance Groups can have more than one Performance Period. When this is the case, sessions controlled by these Performance Groups can have their Allocation Group dynamically changed as system conditions change. Consequently, processes running in those sessions may be assigned different priorities as those processes run. Utilities 147

148 Chapter 6: Priority Scheduler (schmon, xschmon) Performance Periods Performance Period Components The following table describes the components of a Performance Period. Component... Defines the... Milestone Type Milestone Limit Allocation Group type of threshold used to define each Performance Period for a Performance Group. You can express types in the following units: Time-of-day (T) Session resource usage (S or R) Query resource usage (Q) For more information, see Performance Period Types and Limits on page 148. value of the threshold used to change Performance Periods for a Performance Group. You can express this value in the following units: A valid time-of-day, such as 0800 for 8:00 a.m. A number of seconds of CPU usage. For more information, see Performance Period Types and Limits on page 148. number of the Allocation Group used to control sessions during this Performance Period. For more information, see Allocation Groups on page 152. The following sections describe milestone limits and Allocation Groups. Performance Period Types and Limits A Performance Group definition specifies the type of Performance Periods the group will use. If a Performance Group has multiple Performance Periods, they must all be the same type. There are three types of Performance Periods, based on the types of milestones they monitor: Query resource Performance Periods monitor the accumulated CPU time used by each query. When the threshold for the Performance Period is exceeded, the query is transferred to the next Performance Period and so placed under the control of a different Allocation Group. Typically, long-running queries are switched to progressively lower priority Allocation Groups. This prevents these queries from competing against the shorter-running queries in higher priority Allocation Groups. Note: Teradata recommends that query resource Performance Periods not be used with online components of Teradata Applications, such as Demand Change Management (DCM) and Customer Relationship Management (CRM). This prevents tactical online queries, which require quick responses, from being demoted. Session resource Performance Periods monitor the accumulated CPU time used by each session. When the threshold for the Performance Period is exceeded, the session is transferred to the next Performance Period, and the processes belonging to that session are placed under the control of a different Allocation Group. Typically, the change is to a 148 Utilities

149 Chapter 6: Priority Scheduler (schmon, xschmon) Performance Periods lower- priority Allocation Group. Consequently access to resources will be progressively reduced for longer-running sessions. Time-of-day Performance Periods monitor the clock time, and optionally the day of the week. These types of Performance Periods are used to dynamically switch the Allocation Group of a session based on changes in business priority of different work at different times of day. For example, a session can be switched to a higher-priority Allocation Group after business hours or on weekends, when competition for database resources is not high. All Performance Period monitoring occurs on a per-node basis. Note: Each Performance Group can specify only a single Performance Period type. All Performance Periods defined for a Performance Group must use the same milestone units. If a Performance Group uses only one Performance Period, the type is irrelevant because sessions assigned to that Performance Group will remain under the control of the single Allocation Group specified by the Performance Period. The following table shows the relationship between Performance Period types and milestone limit units. Performance Period Type Query resource usage Session resource usage Time-of-day Milestone Limit Units Seconds to hundredths of seconds, representing an amount of query CPU resource consumption per node. For example,.02. Seconds to hundredths of seconds, representing an amount of session CPU resource consumption per node. For example, 300. Minutes of military time, representing time periods during a 24-hour day. For example, 0800 is 8:00 A.M. Resource Usage Milestones When milestone limits are expressed in units of query or session resource usage, these limits apply to the total resource usage of all processes working on behalf of a query or session on a node. If multiple Performance Periods are defined for a Performance Group, the specified resource usage milestone value is an upper limit. When a query or session under the control of a Performance Group exceeds the limit defined for the current Performance Period, the Performance Period with the next-higher limit and its associated Allocation Group take control. The following command defines a Performance Group with two Performance Periods. For more information on defining Performance Groups, see schmon -p on page 209. schmon -p 10 H1 1 Q When a query under that control of Performance Group10 begins executing, all of its processes will be under the control of Allocation Group 9 until 15 seconds of CPU time are Utilities 149

150 Chapter 6: Priority Scheduler (schmon, xschmon) Performance Periods used by the query on the node. At that time, Allocation Group 33 assumes control of the query until the query completes. Note: The time to accumulate 10 seconds of CPU time might be different from 10 seconds of wall clock time. Time-of-Day Milestones When you express milestone limits in units of time-of-day, the respective Performance Period and its associated Allocation Group control every process assigned to the Performance Group, up until the time specified in that Performance Period. The actual time-of-day selected for the Performance Periods represents an upper limit of time. When this threshold is passed, the Performance Period with the next higher time-of-day and its associated Allocation Group take control. This Performance Period will change as the day proceeds through the 24-hour cycle. When the last-specified Performance Period expires, the first Performance Period and its Allocation Group take control of the processes assigned to the Performance Group. Suppose you rely on a window of time at night to perform batch work. To keep your query users from interfering with night work without shutting them out completely, do the following: 1 Between 8:00 a.m. and 5:00 p.m., give the query users an assigned weight of Between 5:00 p.m. and 11:00 p.m., reduce the assigned weight to Between 11:00 p.m. and 8:00 a.m., further reduce the assigned weight to 5. At the same time, you can increase the weighting of any batch work. Suppose you raise the assigned weight of the batch work Performance Group from 5 to 30 between 11:00 p.m. and 8:00 a.m. In doing so, you have helped the important batch work to finish, even if users issue queries after hours. Day-of-Week Optionally, you can use a day-of-week specification with a time-of-day milestone for a Performance Period to indicate days when the Performance Period is to be active. This specification might indicate one or more individual days, or a range of days, but not both. Days are numbered sequentially from 0 to 6, Sunday through Saturday. A range of days is indicated by two day numbers separated by a hyphen. If a day-of-week specification is present for one Performance Period, then day-of-week must be present for all. A time-of-day milestone for a Performance Period defines the end of a time period during which the associated Allocation Group is to control processes. The beginning of each period is the end of the preceding period. This might be on a previous day if day of week has been specified. If you do not use a day-of-week specification, then the specified periods apply to all days. In this case, the beginning of the first period is the end of the last period of the day. You might specify one period to define the Allocation Group to be used for the entire day. The milestone time given for this period is immaterial but must be a valid time. 150 Utilities

151 Chapter 6: Priority Scheduler (schmon, xschmon) Performance Periods Suppose you want to provide different levels of service on weekdays, Saturday, and Sunday. On weekdays, one Performance Period is in effect between 0800 and 1800, another beginning at 1800 and continuing until 0800 the next morning. On Saturday the Performance Period from 1800 on Friday continues until 1400 and then switches to another Performance Period that continues through Sunday and on until 0800 Monday morning. The Performance Period specification is as follows, where day of the week is denoted by enclosing / characters: /1/ Monday, use AG 5 until 0800 /2-5/ Tuesday through Friday, use AG 7 until 0900 /1-5/ Monday through Friday, use AG 2 until After 1800, use the next higher period. /6/ Saturday, use AG 7 until After 1400, use the next Performance Period, which is the one specified for 0800 Monday that uses AG 5. Note: If the Time Zone (TZ) is not set correctly, Priority Scheduler will not work as expected. To view the TZ on this platform... Do the following... Linux MP-RAS Windows See the files in the /usr/lib64 directory and the man pages for zic and environ. See the files in the /usr/lib/locale/tz directory and the man pages for zic and environ. Select Start -> Settings -> Control Panel -> Date/Time. In the Date/ Time Properties dialog box, select the Time Zone tab. If the Time Zone is changed, the current Priority Scheduler settings should be dumped (using the schmon -c command) and re-executed after PDE comes up so that the limit values in the system gdo are correct. Using cron With Priority Scheduler Using cron or a similar scheduler program to issue schmon commands at specific times adds flexibility in controlling how work is prioritized by Teradata Database. Time-of-day milestones allow you to change priorities at specific times of day and on specific days of the week. However, if a Performance Group uses time-of-day milestones, CPU resource utilization (query milestones) cannot also be considered when adjusting the priority of work controlled by that Performance Group. Using a scheduling program to run schmon at specific times allows both time and CPU resources to be considered when work is prioritized. One strategy is to define all Performance Groups to use only CPU resource usage (session or query) milestone types, and use cron jobs to additionally adjust priorities based on times of day, irrespective of CPU resources. An additional benefit of using cron with Priority Scheduler is that this technique allows you to change any of the Priority Scheduler settings on a regular basis. For example, you might run Utilities 151

152 Chapter 6: Priority Scheduler (schmon, xschmon) Allocation Groups schmon -b regularly to adjust the relative weights or CPU limits of different Resource Partitions to match the typical usage patterns of your database. Whereas Performance Groups determine the prioritization of individual jobs, changes to a Resource Partition affect all jobs assigned to its Performance Groups. In some situations, this type of broad, time-based prioritization control is useful. For more information on schmon options, see schmon Utility on page 165. Allocation Groups An Allocation Group establishes how resources are allocated to processes. It defines the following: A method for disbursing resources among sessions active within that Allocation Group An attribute that optionally expedites work requests for sessions controlled by the Allocation Group A weight Optionally, a CPU limit In a single Resource Partition, multiple Performance Periods belonging to different Performance Groups can reference the same Allocation Group, as shown in the following figure. 152 Utilities

153 Chapter 6: Priority Scheduler (schmon, xschmon) Allocation Groups One Resource Partition Performance Group P2 Performance Group B Performance Period Performance Period Performance Period Allocation Group 7 Allocation Group F423 An Allocation Group cannot be referenced by Performance Groups from more than one Resource Partition. Allocation Group Parameters The following table describes the parameters of an Allocation Group. Parameter Allocation Group ID Set Division Type Expedite Attribute Description Any number from 0 to 199 inclusive. Defines how resources are disbursed to the processes controlled by the Allocation Group. Can be N or S. For more information, see Set Division Type on page 154. Optional parameter that indicates that work requests are to be expedited through the AWT invocation procedures. If present, it appears as X. For more information, see Expedite Attribute on page 155. Utilities 153

154 Chapter 6: Priority Scheduler (schmon, xschmon) Allocation Groups Parameter Allocation Group Weight Limit Description A positive integer value used to compute the proportion of resources each process should receive. This weight is converted to a relative weight, taking into account all other active allocation groups within the same Resource Partition. For more information, see Allocation Group Weight on page 155 Optional parameter that is an integer from1 through 100. Specifies the limit on the total CPU usage by sessions controlled by the Allocation Group. Associating Allocation Groups to Performance Groups Set Division Type Recommendations: Start simple with a one-to-one relationship between Performance Groups and Performance Periods/Allocation Groups. Establish reasonable contrast between weights of Allocation Groups in the same Resource Partition, but avoid extreme differences. For example, use 2:1, 3:1, and 4:1 ratios between weights, rather than 12:1 or 20:1. If strong priority differences are required, establish relative weights for different priority Allocation Groups so that they have a contrast between them of a factor of two or more. For example, consider relative weights of 5%, 20% and 50%, rather than 15%, 18% and 20%. The set division type parameter of an Allocation Group defines how resources are disbursed to the processes controlled by the Allocation Group. The set division type parameter causes processes to be grouped into a scheduling set in one of two possible ways. The resources of the Allocation Group are divided among these scheduling sets according to the set division type described in the following table. Type... Determines that set division type can specify... None only one scheduling set for the Allocation Group. All processes controlled by the Allocation Group belong to this scheduling set. The resources of the Allocation Group are divided equally among them. In this case, a session with a multi-amp request that has invoked several processes (one process per AMP) receives the same resource per process as a single-amp request with one process. With this type of set division, the multi-amp request receives more resources than the single-amp request. 154 Utilities

155 Chapter 6: Priority Scheduler (schmon, xschmon) Allocation Groups Type... Determines that set division type can specify... Session one scheduling set per session. The resources of the Allocation Group are divided equally among the sessions that have processes controlled by the Allocation Group. In this case, a session with a multi-amp request receives the same resources as a session with a single-amp request if they are running in the same Allocation Group. The resources available for the multi-amp request are divided among the processes associated with it. The same amount of resources available for the single-amp request are given to the single process associated with the single AMP. Expedite Attribute You can specify an Expedite Attribute for an Allocation Group to indicate that work requests for sessions controlled by the Allocation Group are to be expedited through the AMP worker task (AWT) invocation procedures. Work requests controlled by the Allocation Group are favored over non-expedited work requests controlled by other Allocation Groups during the invocation procedure in two ways: Expedited work requests receive increased priority in the work request input queue when all AMP worker tasks are in use. They bypass normal work requests in the input queue and have quicker access to an AWT. Expedited work requests have access to a special pool of reserved AWTs that have been dedicated for this expedited work by the Teradata Database system administrator. Caution: Teradata recommends that only Allocation Groups supporting short, response-sensitive work, such as single-amp operations, be expedited. Work performed in this mode will have some impact on resources available to non-expedited work. Use this option judiciously. For more information on reserved AWT pool, see AMP Worker Task (AWT) Reservations and Limits on page 159. Allocation Group Weight Allocation group weights are values used to compute the proportion of resources each process will be offered. The relative weight of an Allocation Group is the ratio of its weight divided by the sum of the weights of all active Allocation Groups within the same Resource Partition multiplied by the relative weight of the Resource Partition. Determining Allocation Group Relative Weight Suppose each Performance Group of a Resource Partition is linked to one Allocation Group. The weights of these Allocation Groups are as follows: Allocation Group 1 = 5 Allocation Group 2 = 10 Allocation Group 3 = 20 Allocation Group 4 = 40 Utilities 155

156 Chapter 6: Priority Scheduler (schmon, xschmon) Allocation Groups Suppose that only Allocation Groups 1, 2, and 3 are active. To determine the weight for each of these active Allocation Groups, do the following: 1 Add the individual respective weights of the three active Performance Groups ( ) for a sum of Divide the weight (5, 10, and 20) of each Performance Group by the sum of 35. The relative weight for each Allocation Group, relative to its Resource Partition, is as follows: Allocation Group 1 = 14% (5/35) Allocation Group 2 = 28% (10/35) Allocation Group 3 = 57% (20/35) 3 If the relative weight of the Resource Partition is 50%, multiply the relative weight for each Allocation Group by.50 to determine the relative weight for each Allocation Group. The final Allocation Group weights are as follows: If the relative weight of the Resource Partition is 50%, multiply the relative weight for each Allocation Group by.50 to determine the relative weight for each Allocation Group. Allocation Group 1 = 7% (.14 x.50) Allocation Group 2 = 14% (.28 x.50) Allocation Group 3 = 28% (.57 x.50) The following example shows how Priority Scheduler handles Resource Partitions and associated Performance Groups. Suppose you have three active Resource Partitions with the following weightings: Default = 20 Tactical = 60 Standard = 20 The Standard Resource Partition consists of the following: Performance Group Allocation Group Weight Type of Work D 5 For demotions P2 10 Med/low priorities P1 40 High priorities B 20 Batch loads and reports To determine the resources allocated to med/low priority users, do the following: 1 Add the assigned weights of all active Resource Partitions: = Utilities

157 Chapter 6: Priority Scheduler (schmon, xschmon) Allocation Groups 2 Find the percentage of resources allocated to the Standard Resource Partition by dividing the weight of the Standard Resource Partition (20) by the sum of the active Resource Partitions (100): 20/100 = 20% 3 Add the assigned weights (5, 10, 40, and 20) of the active Allocation Groups within the Standard Resource Partition: = 75 4 Find the percentage of the Standard Resource Partition allocation that the med/low priority users can expect by dividing the P2 group weight (10) by the sum of the active Performance Groups (75): 10/75 = 13% 5 Multiply the percentage of resources (20%) allocated to the Standard Resource Partition by the percentage (13%) of the Standard Resource Partition allocation that the med/low priority users can expect: 20% x 13% = 2% With all Resource Partitions and all Performance Groups in the Teradata Database system active, the relative weight of the Allocation Group for med/low priority users is 2%. The relative weight of the Allocation Group for batch load and report users is 5%. In this example, the batch load and report users will have more than twice as much access to resources than the med/low priorities. Query Response Time and Allocation Groups The consistency of response times within a given Allocation Group depends on the following: The number of users active at the same time within the Allocation Group The nature of the queries (such as data skew, complexity of the work submitted, and how long the queries take to complete) The average query response time grows as active users in the same Allocation Group increase. The following table shows how the number of users in Performance Group H (and its associated Allocation Group) affects query response time of all queries in that Allocation Group. IF the number of active users in a Performance Group/ Allocation Group pair is... THEN the average query response time might be seconds seconds seconds seconds. Utilities 157

158 Chapter 6: Priority Scheduler (schmon, xschmon) Resource Accounting Resource Accounting Priority Scheduler resource accounting employs three user-settable parameters: Age Time is the period of time over which Priority Scheduler measures the resource consumption of Allocation Groups in order to balance usage and priority. Active Time is the period of time over which Priority Scheduler monitors the activity level of Allocation Groups. Groups with no processes running for the length of time represented by the Active Time are removed from Priority Scheduler resource accounting for the period. CPU Usage Limit is the total amount of CPU resource that can be used at any point in time by all Teradata Database sessions that are under the control of Priority Scheduler. Age Time Active Time Age Time tells Priority Scheduler how many seconds constitute recent in evaluating recent resource consumption. The default value for Age Time is 60 seconds. Decreasing or increasing Age Time makes Priority Scheduler respond more or less quickly to changes in resource usage. This responsiveness affects the frequency and degree of changes in process dispatch priorities and how Priority Scheduler manages process resource allocation. Note: In this case, responsiveness is not the same as query response time. Modifying Age Time does not necessarily affect query response time. You should monitor adjustments in Age Time carefully to judge their effects on Teradata Database system performance. The default value for Active Time is 61 seconds. During this period, an Allocation Group continues to participate in relative weight calculations and resource allocations, even when no processes are active, in anticipation of a new process being associated with the Allocation Group. This period causes a smoothing effect in the scheduling algorithms when a few processes are associated with an Allocation Group at interrupted intervals. Note: If no process controlled by an Allocation Group has consumed resources within the preceding Active Time period, the Allocation Group is considered inactive. An Allocation Group and scheduling set are inactive when they have no active processes during the active time interval. A Resource Partition is inactive when it has no active Allocation Group within the active time. Priority Scheduler considers only active Resource Partitions and Allocation Groups when computing the total weight used to calculate the relative weight of Resource Partitions and Allocation Groups. You should monitor adjustments to Active Time carefully to judge their effect on Teradata Database system performance. Age Time and Active Time should be kept similar to each other. For example, if Age Time is reduced from the default of 60 to 30 seconds, change the Active Time from the default of 61 to Utilities

159 Chapter 6: Priority Scheduler (schmon, xschmon) AMP Worker Task (AWT) Reservations and Limits Teradata Database System CPU Usage Limit You can use an optional Priority Scheduler parameter to limit the total amount of CPU resources used by the Teradata Database sessions under its control. This limit does the following: Limits the total CPU resources consumed to a specified percentage value Has no affect on the scheduling strategy defined by other Priority Scheduler parameters Is enforced separately on each individual node of the Teradata Database system AMP Worker Task (AWT) Reservations and Limits AWTs are processes (threads on some platforms) dedicated to servicing the Teradata Database work requests. A fixed number of AWTs are pre-allocated during Teradata Database system initialization for this purpose for each AMP vproc. Each AWT looks for a work request to arrive in the Teradata Database system, services the request, and then looks for another. An AWT can process requests of any work type. Each Teradata Database query is composed of a series of work requests that are performed by AWTs. Each work request is assigned a work type that indicates when the request should be executed relative to other work requests that are waiting to execute. An example of work types include the following: New work Spawned work Transaction completion and control requests New work is the lowest in importance. A single query might require different types of work requests to reach completion. AWT Resource Allocation Since the number of AWTs is fixed, when all AWTs are busy and none are available to service new arriving requests, these are placed in an input queue. When an AWT completes a request for service and is available to service another, the first queued work request is removed from the input queue and serviced. An AWT resource manager controls the number of active requests for each AMP based on work type of the requests. The resource manager reserves some number of tasks for each work type to ensure that requests from each work type can be processed when necessary. For example, an ongoing query might spawn additional tasks of a different work type part way to completion. If reserve tasks of the new work type are unavailable, a deadlock condition can result. The resource manager allows a task to process a request of a particular work type if one of the following conditions is met: Utilities 159

160 Chapter 6: Priority Scheduler (schmon, xschmon) AMP Worker Task (AWT) Reservations and Limits The total number of active tasks is less than a Current Limit, where Current Limit = # of AWTs - (Total Reserved - Active Reserved). The number of active tasks of that type is below its reserved number. The default Teradata Database system provides 80 AWTs for each AMP. Out of these 80, three tasks are reserved for each of eight work types, yielding 24 reserved tasks. That leaves 56 unreserved tasks that can be used for any work type. If only two work types are active, for example WORKNEW and WORKONE, they can use up to 62 AWTs in combination. This includes the 56 unreserved tasks in addition to the three tasks that are reserved for each of the active work types ( = 62). The 56 unreserved tasks can be divided in any way between the two work types. Besides reserving work tasks, the AWT resource manager also enforces an upper limit of 50 on requests of work type WORKNEW. Since many queries rely on multiple work types to reach completion, the limit on WORKNEW insures that requests that start up new work do not use too many unreserved AWTs. Other work types have no limit on the number of tasks they can request from the unassigned pool of 56, and are limited only by the availability of unassigned tasks. AWTs Reservation for Expedited Allocation Groups To aid response time consistency for short queries, Priority Scheduler parameters can extend the default resource management function, and allow an administrator to reserve and limit AWTs exclusively for processing these types of work requests. All work requests controlled by Allocation Groups to which the administrator has given the Expedite (X) attribute fall into this category. A number of reserved AWTs and a limit are applied to a set of three work types used solely to process work requests controlled by one or more expedited Allocation Groups. As described in AWT Resource Allocation on page 159, the number of reserved tasks for expedited requests determines the minimum number of tasks that are always available for that work. This ensures that these tasks will be able to run with that level of concurrency any time. When the reserved tasks are all active, additional requests of that type can still be issued until the unassigned AWTs are depleted, or the limit on the expedited work type is reached. When either limit is reached, requests are queued until an active task completes and is available to service another request. Of course, if the work type limit is reached, an active task of that type must complete before another can be started. The number of reserved tasks for the three work types used by expedited requests is added to the number of reserved tasks defined for normal work. Whenever you specify that one or more Allocation Groups have the expedite option, two AWTs each are always reserved for the two of the three work types that support spawned work. In addition, the number of tasks you explicitly reserve is reserved for the third work type that supports new expedited work. If you reserve three tasks for expedited requests, a total of seven tasks would be reserved across the three work types. The total number of reserved AWTs is increased to 31. It is possible to expedite an Allocation Group, yet set or leave its reserve number at zero. If the number of reserved AWTs for expedited work types is zero, four AWTs are still reserved across two of the three work types. Under those conditions, expedited requests will be serviced before normal work but are not guaranteed immediate access to an AWT. 160 Utilities

161 Chapter 6: Priority Scheduler (schmon, xschmon) AMP Worker Task (AWT) Reservations and Limits If expedited work consists of short, single, or few AMP queries, the amount of time a reserved work task is held by any such query might be very short, such that a single AMP worker task could service hundreds of queries per second. Under these conditions, a reservation of one or two tasks might be adequate, depending on the expected arrival and service rate of the queries. If any queries running within an expedited Allocation Group are all-amp queries, a minimum reserve number of two should be selected. Teradata recommends that the reserve limit be set the same as the limit for WORKNEW, 50. (The reserve number cannot exceed 5 for expedited work.) Note: The work request for a single-amp query is processed by just one task of the AMP vprocs of an MPP system. Each AMP in the Teradata Database system could be performing a similar single-amp request simultaneously. The schmon -m display includes data indicating the queue length, queue wait time, and service time for all Allocation Groups. This data might be useful for adjusting the Expedited work type reservation and limit values. If the queue wait time is between zero and five milliseconds for a non-expedited Allocation Group, then it might not benefit from being expedited, because no shortage of AWTs is being experienced. The optional Expedite attribute of an Allocation Group is intended to provide quicker and more consistent response time for queries than might be experienced with a non-expedited Allocation Group. This Allocation Group option is intended for use by sessions submitting short, simple queries where quick response time is critical. This type of work is sometimes referred to as tactical query work. AMP Worker Task Examples (puma -c) The puma utility includes a command option that displays data describing AWTs for each VPROC. The puma -c command shows the reserve, limit, in-use, and peak values for each work type. The following examples show how AWTs might be allocated under a heavy load of normal data warehouse work and various expedited work loads and settings. All are the results of running the puma -c command. In the examples, the following applies: An asterisk indicates which work types are used for expedited work requests. The Min and Max columns indicate reserved and limit values, respectively. A Max value of 999 indicates that no individual limit on that work type exists and only the computed current limit will control the number of tasks of that type that can be active. Further, this assumes that normal (non-expedited) requests active in this example require two AWTs to complete (one WORKNEW and one WORKONE type tasks [for redistribution and other spawned work]). Example 1 Example 1 shows the output of puma -c in an ordinary case where no tasks are reserved for expedited work types. No expedited queries are running. The total number of reserved tasks is 24 (the sum of the Min column), and the current limit is 62 (the sum of the Inuse column). Utilities 161

162 Chapter 6: Priority Scheduler (schmon, xschmon) AMP Worker Task (AWT) Reservations and Limits The output shows 62 active tasks on behalf of 31 queries divided between WORKNEW and WORKONE. Because 62 is the current limit in this example, newly arriving requests are placed on the input queue. WorkType Min Max Inuse Peak MSGWORKNEW MSGWORKONE MSGWORKTWO MSGWORKTHREE *MSGWORKEIGHT *MSGWORKNINE *MSGWORKTEN MSGWORKABORT MSGWORKSPAWN MSGWORKNORMAL MSGWORKCONTROL Example 2 Example 2 shows the output of puma -c for a system in which a reserve of one and limit of three is made for expedited work types. Work type MSGWORKEIGHT has one task reserved, and MSGWORKNINE and MSGWORKTEN each have two tasks reserved, for a total of five tasks. Now, the total number of reserve tasks has increased from 24 (in example 1) to 29 (in example 2). When only normal work is running, the current limit on non-expedited work drops from 62 to 57, reducing the level of regular work that can be supported. WorkType Min Max Inuse Peak MSGWORKNEW MSGWORKONE MSGWORKTWO MSGWORKTHREE *MSGWORKFOUR MSGWORKFIVE MSGWORKSIX MSGWORKSEVEN *MSGWORKEIGHT *MSGWORKNINE *MSGWORKTEN *MSGWORKELEVEN MSGWORKABORT MSGWORKSPAWN MSGWORKNORMAL MSGWORKCONTROL Example 3 Example 3 shows the output of puma -c for a system in which a reserve of three and limit of 50 is made for expedited work types. The reservation for MSGWORKNINE and MSGWORKTEN remains two. Now, the total number of reserved tasks is 31. When only normal work is running, the current limit is 55. WorkType Min Max Inuse Peak MSGWORKNEW MSGWORKONE MSGWORKTWO MSGWORKTHREE *MSGWORKFOUR Utilities

163 Chapter 6: Priority Scheduler (schmon, xschmon) AMP Worker Task (AWT) Reservations and Limits MSGWORKFIVE MSGWORKSIX MSGWORKSEVEN *MSGWORKEIGHT *MSGWORKNINE *MSGWORKTEN *MSGWORKELEVEN MSGWORKABORT MSGWORKSPAWN MSGWORKNORMAL MSGWORKCONTROL AMP Worker Task Examples (awtmon) The awtmon utility is a user-friendly alternative to puma -c. It collects and displays a summary of AWT in-use count snapshots for the local node or for all nodes in the Teradata Database system. For more information, see awtmon Utility in Utilities. The following examples show how AWTs might be allocated under a heavy load of normal data warehouse work and various expedited work loads and settings. All are the results of running the awtmon utility. Example 1 awtmon default output > awtmon ====> Thu Feb 15 10:02: <==== Amp 0: Inuse: 22: FOUR: 1 NEW: 13 ONE: 8 Amp 2: Inuse: 20: NEW: 12 ONE: 8 Amp 4: Inuse: 20: NEW: 12 ONE: 8 Amp 6: Inuse: 20: NEW: 12 ONE: 8 Amp 8: Inuse: 20: NEW: 12 ONE: 8 Amp 10: Inuse: 20: NEW: 12 ONE: 8 Amp 12: Inuse: 20: NEW: 12 ONE: 8 Amp 14: Inuse: 20: NEW: 12 ONE: 8 Amp 16: Inuse: 21: NEW: 13 ONE: 8 Amp 18: Inuse: 20: NEW: 12 ONE: 8 Example 2 This example shows awtmon run in summary mode, displaying information only if 8 or more AMPs have a combined total of 50 or more AWTs in use. The final two numbers in the command specify that awtmon will automatically run 3 times, with a 2-second delay between runs. > awtmon -S 8 -t ====> Tue Feb 16 08:53: <==== LOOP_0: Inuse: 55: Amps: 5,6,11,12,17,18,23,29,30,35,36,41,42 LOOP_0: Inuse: 56: Amps: 0,47 LOOP_0: Inuse: 57: Amps: 24 ====> Tue Feb 16 08:53: <==== LOOP_1: Inuse: 54: Amps: 5,6,11,12,17,18,23,29,30,35,36,41,42 LOOP_1: Inuse: 55: Amps: 0,47 LOOP_1: Inuse: 56: Amps: 24 ====> Tue Feb 16 08:53: <==== LOOP_2: Inuse: 54: Amps: 5,11,12,17,18,23,29,30,35,36,41,42 Utilities 163

164 Chapter 6: Priority Scheduler (schmon, xschmon) AMP Worker Task (AWT) Reservations and Limits LOOP_2: Inuse: 55: Amps: 0,6,47 LOOP_2: Inuse: 56: Amps: Utilities

165 Chapter 6: Priority Scheduler (schmon, xschmon) schmon Utility schmon Utility Function The schmon utility provides a command line interface that allows you to display and alter Priority Scheduler parameters. Note: If Workload Definitions have been activated using Teradata Dynamic Workload Manager, schmon and xschmon cannot be used to make changes to Priority Scheduler. For more information, see the Teradata Dynamic Workload Manager User Guide. Note: Teradata Database Warehouse Appliances support only a subset of schmon commands, and do not support changing any Priority Scheduler settings. Run schmon -h to see the available commands. User Interfaces schmon runs on the following platforms and interfaces: Platform MP-RAS Windows Linux Interfaces Command line Database Window Note: On MP-RAS, Priority Scheduler includes an X11-based graphical user interface, xschmon. For more information, see xschmon Utility on page 226 Command line ( Teradata Command Prompt ) Database Window Command line Database Window For general information on starting the utilities from different platforms and interfaces, see Appendix B: Starting the Utilities. Utilities 165

166 Chapter 6: Priority Scheduler (schmon, xschmon) schmon Utility Syntax schmon -a AG# div -x -s -S X weight limit none -T -P -d delay reps -b -c -d -f -h -l -m -M -p -s -t -T -w path specific option(s) limit none age RP# delayage reserve active RPNAME weight limit none -s -S -T -P -d delay -x -a -b -p -t -w -S -P -L -n PG# all id maximum disp -d delay -f path reps reps -p -s -P -d delay -V PGNAME R T PP -x -s -S -T -P -d delay -S -T -P -d delay reps reps reps 1102E005 Note: Some internal and rarely-needed options have been omitted from the following discussion. Those options are described in the online help for schmon. 166 Utilities

167 Chapter 6: Priority Scheduler (schmon, xschmon) schmon Utility Priority Scheduler Default Settings The following example shows the Priority Scheduler default settings on MP-RAS. The following example shows the Priority Scheduler default settings on Linux and Windows. You can use schmon to change the defaults, and to define new Resource Partitions, Performance Groups, and Allocation Groups. Utilities 167

168 Chapter 6: Priority Scheduler (schmon, xschmon) schmon -a schmon -a Purpose The schmon -a option displays or sets Allocation Group parameters. Syntax schmon -a AG# div -x -s -S X weight limit none -T -P -d delay reps 1102D006 where: Syntax element Description -a Sets or displays Allocation Group parameters. If no additional options are specified, schmon -a displays the parameters for Allocation Groups currently in use (those with defined parameters). AG# An integer from 0 through 199 that identifies the Allocation Group for which parameters will be set or displayed. To set parameters for a Allocation Group, follow AG# with the div and weight specifications. To view information about a specific Allocation Group, follow AG# with the -s or -S options, or with no options. To clear all parameters for a specific Allocation Group, follow AG# with the -x option. 168 Utilities

169 Chapter 6: Priority Scheduler (schmon, xschmon) schmon -a Syntax element div Description A single character that indicates the type of scheduling set division enforced by the Allocation Group. A scheduling set is a collection of processes controlled by the Allocation Group. The resources of the Allocation Group are shared equally by its scheduling sets. Permissible values for div are as follows: Value... Specifies... N (NONE) S (SESSION) all processes controlled by the Allocation Group form one scheduling set and the Allocation Group resources are divided equally among these processes: The lone process invoked by a single-amp query receives the same resource allocation as each process invoked by an all-amp query that has several processes, one per vproc. This is more advantageous to multi-amp queries, if work within an Allocation Group is mixed. processes are grouped into one scheduling set for each session. The Allocation Group resources are divided equally among the scheduling sets. The resources for each scheduling set are divided equally among its processes. Each query receives the same resources no matter how many processes are involved. This is more advantageous to single-amp queries, if work within the Allocation Group is mixed. X weight limit The Allocation Group is expected to process expedited work. Work requests controlled by the Allocation Group receive special treatment in the request input queue and AWT allocation phase. Requests receive superior priority in the input queue, bypassing normal requests, and are assigned to work processes from a pool reserved for the purpose. You can use this option with more than one Allocation Group. When multiple Allocation Groups have the expedited attribute, work requests for all of the Allocation Groups are satisfied from a single reserved work process pool. Note: You can use the schmon -w command to define the reserved work process pool. A numeric value used to compute a relative weight to determine the proportion of resources the processes of the Allocation Group are to receive. A percentage limit on total CPU usage by all processes controlled by the Allocation Group or the character string none. The value range is from 1 through 100. A value of 100 indicates that no limit is to be enforced. A character string of none indicates that no limit is to be enforced. If limit is not present, any previously defined limit is removed. -s Displays Priority Scheduler data for all sessions controlled by the specified Allocation Group on the current node. -S Displays Priority Scheduler data for all sessions controlled by the specified Allocation Group on all Teradata Database nodes. Utilities 169

170 Chapter 6: Priority Scheduler (schmon, xschmon) schmon -a Syntax element Description -T Displays process and thread tasks for the specified Allocation Groups on the current node (the node from which schmon was invoked). Even when used in conjunction with the -S option, -T will display only task data for the current node. Note: The -T option should not be used for prolonged periods of time, because it can interfere with the normal operation of Priority Scheduler. The -T output includes the following columns: Procqueue Tsk Addr: Kernel address of the proc control block Tskid: PID (MPRAS), thread ID (Windows, Linux) Prio: OS priority Session: Task session number Request: Task request number Tskuse: Task CPU resource usage Tskterm: Task resource usage to weight ratio -P Shows session information for individual Performance Groups. Note: Performance Groups with no CPU usage are not shown. -d Displays the differences in data between sequential runs of schmon. Use the delay [reps] option to control timing of automatic schmon runs. The following symbols precede numbers that appear in the output from the -d option. For decimal numbers: - (a minus sign) indicates the value has decreased by the indicated amount since the previous schmon run. An unsigned decimal number indicates the value has increased by the indicated amount since the previous schmon run. For task data (displayed if the -T option is used with the -d option): n-> indicates a task has been moved from the control of AG n to the control of the displayed AG since the previous schmon run. + indicates a task is new, started since the previous schmon run. - indicates a task that ended since the previous schmon run. * indicates a task that has changed sessions or requests since the previous schmon run. For examples of the -d option output, see schmon -m on page 188, and schmon -s on page 214. Note: The output of the -d option shows only those items for which data has changed since the previous schmon run. delay [reps] Causes schmon -a to run again automatically after a specified delay using the current session options. delay is a positive integer that specifies the number of seconds between schmon executions. Use the optional reps argument, a positive integer, to specify the number of times schmon should run. If reps is not specified, schmon runs indefinitely with delay seconds between executions. In this case, schmon can be stopped by pressing Ctrl-C or otherwise killing the schmon process. Note: The difference between time stamps of successive information displays may not precisely match the specified delay value due to the time required for the collection activity itself. 170 Utilities

171 Chapter 6: Priority Scheduler (schmon, xschmon) schmon -a Syntax element Description -x Clears the parameters that define the specified Allocation Group, effectively deleting it from the system (though an empty group will still appear in the output of schmon -a all). The Allocation Group must not be referenced by any Performance Period defined by any Performance Group. Usage Notes Example 1 A session s processes are assigned to Allocation Groups based on the session s Performance Group. Each Performance Group may have from one to eight Performance Periods defined, each of which specifies an Allocation Group. As a processes runs, its Performance Period changes according to limit criteria ( milestones ) that are defined along with the Performance Group. Consequently, the Allocation Group that controls a process can change over time. For more information, see Performance Periods on page 147. The following apply to MPP configurations: For the -S option: The count of nodes is displayed. Time information is displayed. If a node is offline, it is not included in the output, and the node count reflects this; however, information about this node being excluded is not displayed. The following apply to SMP configurations: Node count is not shown. A status message that includes time of day is displayed. No transient status messages are displayed. To display parameters for all in-use Allocation Groups, type: schmon -a The following appears: Allocation Groups (0-199) Id Type Wght Lim Id Type Wght Lim Id Type Wght Lim Id Type Wght Lim 1 N 5 none 2 N 10 none 3 N 20 none 4 N 40 none 30 S 30 none Example 2 The following example shows a four-node MPP MP-RAS system. To display session data for Allocation Group 1 on the current node, type: schmon -a 1 -s The following appears: Utilities 171

172 Chapter 6: Priority Scheduler (schmon, xschmon) schmon -a Stats: Mon Mar 8 14:47: AG HostID Session Request #prc CPU(msec) DSK(blk) RP PG [PP] === ====== ========== ========== ==== ========== ========== === =============== L[0] Example 3 The following example shows a four-node MPP MP-RAS system. Note: PDE was not up on one of the nodes. To display session data for Allocation Group 1 on all nodes, type: schmon -a 1 -S The following appears: Stats: 3 node(s) Mon Mar 8 14:50: AG HostID Session Request #prc CPU(msec) DSK(blk) RP PG [PP] === ====== ========== ========== ==== ========== ========== === =============== L[0] Example 4 To set the expedite attribute on an Allocation Group 1, type: schmon -a 1 N X 30 The following appears: Id Type Weight 1 N 5 >>>>> Changed to: 1 NX 30 Allocation Groups (0-199) Example 5 To change the weight of Allocation Group 5 from 1 to 10, type: schmon -a 5 S 10 The following appears: Id Type Weight 5 S 1 Allocation Groups (0-199) >>>>> Changed to: 5 S Utilities

173 Chapter 6: Priority Scheduler (schmon, xschmon) schmon -b schmon -b Purpose The schmon -b option displays or sets Resource Partition parameters. Syntax schmon -b RP# RPNAME weight limit none -s -S -T -P -d delay -x reps 1102D004 where: Syntax element Description -b Sets or displays Resource Partition parameters. If no additional options are specified, schmon -b displays the parameters for Resource Partitions currently in use (those with defined parameters). RP# RPNAME weight An integer from 0 through 4 that identifies the Resource Partition for which parameters will be set or displayed. To set parameters for a Resource Partition, follow RP# with the RPNAME and weight specifications. To view information about a specific Resource Partition, follow RP# with the -s or -S options, or with no options. To clear all parameters for a specific Resource Partition, follow RP# with the -x option. The name of the Resource Partition. Resource Partition names that contain spaces must be in quotation marks. For example, RP ONE. A numeric value used to compute a relative weight to determine the proportion of resources that the processes controlled by the Resource Partition are to receive. Utilities 173

174 Chapter 6: Priority Scheduler (schmon, xschmon) schmon -b Syntax element limit Description A percentage limit on total CPU usage by all processes controlled by this Resource Partition or the character string none. The value ranges from 1 through 100. A value of 100 indicates that no limit is to be enforced. The character string none indicates that no limit is to be enforced. If limit is not present, any previously defined limit is removed. -s Displays Priority Scheduler data for all sessions controlled by the Resource Partition on the current node. -S Displays Priority Scheduler data for all sessions controlled by the Resource Partition on all nodes of the Teradata Database system. -T Displays process and thread tasks for the specified Resource Partition on the current node (the node from which schmon was invoked). Even when used in conjunction with the -S option, -T will display only task data for the current node. Note: The -T option should not be used for prolonged periods of time, because it can interfere with the normal operation of Priority Scheduler. The -T output includes the following columns: Procqueue Tsk Addr: Kernel address of the proc control block Tskid: PID (MPRAS), thread ID (Windows, Linux) Prio: OS priority Session: Task session number Request: Task request number Tskuse: Task CPU resource usage Tskterm: Task resource usage to weight ratio -P Shows session information for individual Performance Groups. Note: Performance Groups with no CPU usage are not shown. 174 Utilities

175 Chapter 6: Priority Scheduler (schmon, xschmon) schmon -b Syntax element Description -d Displays the differences in data between sequential runs of schmon. Use the delay [reps] option to control timing of automatic schmon runs. The following symbols precede numbers that appear in the output from the -d option. For decimal numbers: - (a minus sign) indicates the value has decreased by the indicated amount since the previous schmon run. An unsigned decimal number indicates the value has increased by the indicated amount since the previous schmon run. For task data (displayed if the -T option is used with the -d option): n-> indicates a task has been moved from the control of AG n to the control of the displayed AG since the previous schmon run. + indicates a task is new, started since the previous schmon run. - indicates a task that ended since the previous schmon run. * indicates a task that has changed sessions or requests since the previous schmon run. For examples of the -d option output, see schmon -m on page 188, and schmon -s on page 214. Note: The output of the -d option shows only those items for which data has changed since the previous schmon run. delay [reps] Causes schmon -b to run again automatically after a specified delay using the current session options. delay is a positive integer that specifies the number of seconds between schmon executions. Use the optional reps argument, a positive integer, to specify the number of times schmon should run. If reps is not specified, schmon runs indefinitely with delay seconds between executions. In this case, schmon can be stopped by pressing Ctrl-C or otherwise killing the schmon process. Note: The difference between time stamps of successive information displays may not precisely match the specified delay value due to the time required for the collection activity itself. -x Clears the parameters that define the specified Resource Partition, effectively deleting it from the system (though an empty group will still appear in the output of schmon -b all ). The Resource Partition must not be referenced by any Performance Group. Usage Notes For information on the settings displayed using the -b option, see schmon -d on page 180. The following apply to MPP configurations: For the -S option: The count of nodes is displayed. Time information is displayed. Utilities 175

176 Chapter 6: Priority Scheduler (schmon, xschmon) schmon -b If a node is offline, it is not be included in the output, and the node count reflects this; however, information about this node being excluded is not displayed. The following apply to SMP configurations: Node count is not shown. A status message that includes time of day is displayed. No transient status messages are displayed. Example 1 The following example shows a four-node MPP MP-RAS system. To display session data for Resource Partition 0 on the current node, type: schmon -b 0 -s The following appears: Stats: Mon Mar 8 14:59: AG HostID Session Request #prc CPU(msec) DSK(blk) RP PG [PP] === ====== ========== ========== ==== ========== ========== === =============== L[0] M[0] R[0] Example 2 The following example shows a four-node MPP MP-RAS system. Note: PDE was not up on one of the nodes. To display session data for Resource Partition 0 on all nodes, type: schmon -b 0 -S The following appears: Stats: 3 node(s) Mon Mar 8 15:02: AG HostID Session Request #prc CPU(msec) DSK(blk) RP PG [PP] === ====== ========== ========== ==== ========== ========== === =============== L[0] M[0] R[0] Example 3 To limit CPU usage by processes controlled by Resource Partition 1 to 40 percent of the total CPU available, type: schmon -b 1 RP The following appears: Resource Partitions (0-4) Id Partition Name Weight Limit 1 RP1 50 none >>>>> Changed to: 1 RP Utilities

177 Chapter 6: Priority Scheduler (schmon, xschmon) schmon -b Example 4 To reset the limit to none on Resource Partition 1, type: schmon -b 1 RP1 50 none The following appears: Resource Partitions (0-4) Id Partition Name Weight Limit 1 RP >>>>> Changed to: 1 RP1 50 none Example 5 To change the Resource Partition name, the relative weight, and the total CPU limit for Resource Partition 1, type: schmon -b 1 "RP NO 1" 100 none The following appears: Resource Partitions (0-4) Id Partition Name Weight Limit 1 rp >>>>> Changed to: 1 RP NO none Utilities 177

178 Chapter 6: Priority Scheduler (schmon, xschmon) schmon -c schmon -c Purpose The schmon -c option displays the current Priority Scheduler settings as schmon commands. The output can also be sent to a specified file, which can be used as input to the schmon -f command to reapply the current schmon settings. Syntax schmon -c -a -b -p -t -w -f path 1102B022 where: Syntax element Description -c Displays current Priority Scheduler settings as schmon commands. If no additional options are specified, schmon -c displays all of the current settings. -p Displays settings for the current Performance Group as schmon commands. Displays schmon commands that can be used to re-create the current Performance Groups. -b Displays schmon commands that can be used to re-create the current Resource Partitions. -a Displays schmon commands that can be used to re-create the current Allocation Groups. -w Displays schmon commands that can be used to re-create the current AWT expedite parameters. -t Displays schmon commands that can be used to re-create the current Times and Attributes parameters. -f path Saves the output of schmon -c to a specified file. The file can be used in conjunction with the schmon -f command to reapply some or all of the current schmon settings.this option can be used with any combination of the other schmon -c options. 178 Utilities

179 Chapter 6: Priority Scheduler (schmon, xschmon) schmon -c Usage Notes If you do not specify any options with the schmon-c command, then all commands, including those for setting system times and attributes, are displayed. Example 1 (MP-RAS) To dump all settings, type: schmon -c The following appears: # Priority Scheduler Times & Attributes # Age_Time Active_Time Dispatch_Age schmon -t # System Limit schmon -l 100 # Resource Partitions schmon -b 0 Default 100 none # Allocation Groups schmon -a 1 N 5 none schmon -a 2 N 10 none schmon -a 3 N 20 none schmon -a 4 N 40 none # Performance Groups schmon -p 0 L 0 S schmon -p 1 M 0 S schmon -p 2 H 0 S schmon -p 3 R 0 S # AWT Expedited work type limits (reserve maximum) schmon -w Example 2 To dump only Allocation Group parameters, type: schmon -c -a The following appears: # Allocation Groups schmon -a 1 N 5 none schmon -a 2 N 10 none schmon -a 3 N 20 none schmon -a 4 N 40 none Utilities 179

180 Chapter 6: Priority Scheduler (schmon, xschmon) schmon -d schmon -d Purpose The schmon -d option displays the current Priority Scheduler settings in multi-line format. Syntax schmon -d 1102A024 Usage Notes The following table describes the Priority Scheduler settings. Setting category Description Scheduler Times & Attributes Displays scheduler times and attributes. Setting... Specifies the... Age Time Active Time Limit time period over which recent resource usage by a scheduling set is measured. The default is 60 seconds. time period during which an Allocation Group is considered active if any process assigned to the Allocation Group has been scheduled. Inactive Allocation Groups are not included in resource consumption calculations. The default is 61 seconds. Teradata Database system CPU limit or None if not specified. 180 Utilities

181 Chapter 6: Priority Scheduler (schmon, xschmon) schmon -d Setting category Resource Partitions Description Displays Resource Partition parameters. Setting... Specifies... ID Partition Name Weight Limit the identifier number of the Resource Partition. the name of the Resource Partition. the numeric value used to compute the relative weight of this Resource Partition. a number between 1 and 100, inclusive, that specifies a percentage limit on the total CPU usage by sessions assigned to the Performance Groups associated with the Resource Partition or the string none to indicate no limit is present. Performance Groups Displays Performance Group parameters. Setting... Specifies the... ID Group Name RP Type Teradata Database system-wide, unique identifier of the Performance Group. name of the Performance Group. Resource Partition to which this Performance Group is to be assigned. the single character that specifies the type of units used in these Performance Period definitions: Character... Indicates that milestone... Q S T limits are seconds ( ) of query resource usage. limits are seconds ( ) of session resource usage. units are time-of-day, in military time (0 to 2359). You must define at least two periods. Milestones & Allocation Groups that each milestone defines a period milestone (in units defined by Type above), and that the corresponding Allocation Group defines the Allocation Group in effect during that period. If you are defining only one Performance Period for the Performance Group, use S or Q as the default milestone type and 0 (zero) as the default milestone limit. Utilities 181

182 Chapter 6: Priority Scheduler (schmon, xschmon) schmon -d Setting category Allocation Groups Description Displays Allocation Group parameters. Setting... Specifies... ID Type the Teradata Database system-wide, unique identifier of the Allocation Group. a single character that indicates the type of scheduling set division supported by the Allocation Group. The resources of the Allocation Group are shared equally by its scheduling sets. Permissible values for Type are the following: Value... Specifies that resources are divided... N (NONE) S (SESSION) among processes: For all-amp operations, each AMP counts for one process. Each step in a parallel-step plan counts for one process. Complex queries could be offered more Teradata Database system resources. by the number of active sessions and then by processes: Each query receives the same resources no matter how many AMPS are involved. This is an advantage for single- AMP queries if work within the Allocation Group is mixed. X Wght Lim that an Allocation Group has the Expedite attribute. a numeric value used to compute the relative weight of the Allocation Group. A percentage limit on total CPU usage by all processes controlled by this Resource Partition or the character string none. The value ranges from 1 through 100. A value of 100 indicates that no limit is to be enforced. The character string none indicates that no limit is to be enforced. If Lim is not present, any previously defined limit is removed. 182 Utilities

183 Chapter 6: Priority Scheduler (schmon, xschmon) schmon -d Example (MP-RAS) To show the current Priority Scheduler settings in multi-line format, type: schmon -d The following appears: Scheduler Times & Attributes Age Time(sec): 60 Active Time(sec): 61 Limit(%): none Resource Partitions (0-4) Id Partition Name Weight Limit 0 Default 100 none Performance Groups (0-39) Id Group Name RP Type Milestones & Allocation Groups[0-7] 0 L 0 S M 0 S H 0 S R 0 S Allocation Groups (0-199) Id Type Wght Lim Id Type Wght Lim Id Type Wght Lim Id Type Wght Lim 1 N 5 none 2 N 10 none 3 N 20 none 4 N 40 none AWT Expedited work type limits res max Utilities 183

184 Chapter 6: Priority Scheduler (schmon, xschmon) schmon -f schmon -f Purpose The schmon -f option reads schmon commands from a file or standard input device. This command is most often used in conjunction with the schmon -c command to reapply Priority Scheduler settings that were in effect at the time schmon -c was run. Syntax schmon -f path 1102A061 where: Syntax element path Description Specifies a path from which input is to be read. If path is not specified, data is read from standard input (STDIN). Usage Notes Example Input data is assumed to be a single file of schmon commands separated by new line characters. A command that begins with the # character (on MP-RAS and Linux) or rem (on Windows) is treated as a comment. Each input command is written to the standard error device when the command is read. Changes to Priority Scheduler parameters are accumulated until the end of file is encountered and then applied to the Teradata Database system. An error in a command will terminate reading, and no changes will be applied. Errors are reported on the standard output device. To simplify creation of a suitable input file, see schmon -c on page 178. Assume that file sample contains the following lines: schmon -t schmon -a The command schmon -f sample results in the following output: schmon -t Age Time(sec): 60 Active Time(sec): 61 Disp Age(sec): 10 schmon -a Allocation Groups (0-199) Id Type Wght Lim Id Type Wght Lim Id Type Wght Lim Id Type Wght Lim 1 N 5 none 2 N 10 none 3 N 20 none 4 N 40 none 184 Utilities

185 Chapter 6: Priority Scheduler (schmon, xschmon) schmon -h schmon -h Purpose The schmon -h option displays help for schmon. Syntax schmon -h specific option(s) where: 1102A063 Syntax element specific option(s) Description Specifies one or more schmon top-level options on which to display extended help. Utilities 185

186 Chapter 6: Priority Scheduler (schmon, xschmon) schmon -l schmon -l Purpose The schmon -l option displays or sets the Teradata Database system CPU usage limit. Syntax schmon -I limit none 1102A066 where: Syntax element Description -l Displays or sets the system CPU usage limit. If no additional options are specified, schmon -l displays the current CPU usage limit. limit none A percentage value to limit the amount of CPU usage by the Teradata Database sessions or the character string none. This usage does not include non-teradata work, such as time-share users, I/O or other interrupt services, Gateway processing, or streams work. The value ranges from 1 through 100. A value of 100 indicates that no limit is to be enforced. Zero is not a valid limit value. Indicates that no limit is to be enforced. Example 1 To set the Teradata Database system CPU resource limit from 60 percent to none on each node, type: schmon -l none The following appears: System CPU Limit(%) 60 >>>>> Changed to: none Example 2 To set the Teradata Database system CPU resource limit from none to 90 percent on each node, type: 186 Utilities

187 Chapter 6: Priority Scheduler (schmon, xschmon) schmon -l schmon -l 90 The following appears: System CPU Limit(%) none >>>>> Changed to: 90 Utilities 187

188 Chapter 6: Priority Scheduler (schmon, xschmon) schmon -m schmon -m Purpose The schmon -m option displays or monitors Priority Scheduler resource usage statistics. Syntax schmon -m -S -P -L -d delay reps 1102C067 where: Syntax element Description -m Displays or monitors Priority Scheduler resource usage statistics. If no additional options are specified, schmon -m displays current statistics for the current node. -S Displays or monitors statistics for all nodes in an MPP system. -L Includes information related to the CPU usage limits imposed on Allocation Groups. CPU usage limits can be set at the AG, RP, or Teradata Database system level using schmon -a, -b, and -l options, respectively. AG processes and threads can be delayed by the system, if necessary, to keep the CPU usage within those limits. -P Displays a separate line of information for each Performance Group. Note: Performance Groups with no CPU usage are not shown. -d Displays the differences in data between sequential runs of schmon. Use the delay [reps] option to control timing of automatic schmon runs. The following symbols precede numbers that appear in the output from the -d option. - (a minus sign) indicates the value has decreased by the indicated amount since the previous schmon run. An unsigned number indicates the value has increased by the indicated amount since the previous schmon run. Note: The output of the -d option shows only those items for which data has changed since the previous schmon run. 188 Utilities

189 Chapter 6: Priority Scheduler (schmon, xschmon) schmon -m Syntax element delay [reps] Description Monitors resource usage over time by causing schmon to run again automatically after a specified delay using the current -m options. delay is a positive integer that specifies the number of seconds between schmon executions. Use the optional reps argument, a positive integer, to specify the number of times schmon should run. If reps is not specified, schmon runs indefinitely, with delay seconds between executions to continually monitor resource usage. Note: The difference between time stamps of successive information displays may not precisely match the specified delay value due to the time required for the collection activity itself. Usage Notes The statistics are described in the following table. Display category Stats Collection Resource Partitions Description The date and time of the statistics displayed, as well as repetition number, if you specify multiple repetitions. The statistics for each active Resource Partition, including the following: Setting... Specifies... RP Rel Wgt Avg CPU the Resource Partition ID Number. the weight of the Resource Partition relative to the active Resource Partitions. Note: The sum of relative weights might be greater or less than 100 due to the following considerations: Fractions are truncated as the final step in relative weight calculations. Any relative weight calculated to be less than one is converted to one. the resource usage during the preceding age period for a single CPU. The CPU data is shown in two columns. Column... Is the... % percentage of CPU consumed by the Resource Partition. When statistics are collected from all nodes in an MPP system, this is the average percentage per Resource Partition for all nodes. msec milliseconds of CPU time consumed by the Resource Partition. Utilities 189

190 Chapter 6: Priority Scheduler (schmon, xschmon) schmon -m Display category Resource Partitions (continued) Description Setting... Specifies... Avg I/O a normalized number of data blocks transferred by the Resource Partition. When statistics are collected from all nodes in an MPP system, this is the average normalized resource use per Resource Partition for all nodes on the Teradata Database system. I/O data is shown in two columns. Column... Is the... % percentage of disk consumed by the Resource Partition. When statistics are collected from all nodes in an MPP system, this is the average percentage per Resource Partition for all nodes. sblks number of blocks read and written by the Resource Partition. # of Procs the number of processes assigned to the Resource Partition at the end of the preceding collection period. When statistics are collected from all nodes in an MPP system, this is the average per Resource Partition for all nodes. # of Sets IF Allocation Group Set Division is... THEN one scheduling set... Session per session exists. None to the Allocation Group exists. 190 Utilities

191 Chapter 6: Priority Scheduler (schmon, xschmon) schmon -m Display category Allocation Groups Description The statistics for each active Allocation Group, including the following: Setting... Specifies... AG Rel Wgt Avg CPU the Allocation Group ID number. the weight of the Allocation Group relative to the active Allocation Groups of the Resource Partition and the active Resource Partitions. Note: The sum of relative weights might be greater or less than 100 due to the following considerations: Fractions are truncated as the final step in relative weight calculations. Any relative weight calculated to be less than one is converted to one. resource usage by the Allocation Group during the preceding age period for a single CPU. The CPU data is shown in two columns. Column... Is the... % percentage of total available CPU on the node consumed by the Allocation Group. When statistics are collected from all nodes in an MPP system, this is the average percentage for all nodes. msec milliseconds of CPU usage consumed by the group. Avg I/O a normalized number of data blocks transferred by the Allocation Group. When statistics are collected from all nodes in an MPP system, this is the average normalized resource use per Allocation Group for all nodes on the Teradata Database system. I/O data is shown in two columns. Column... Is the... % percentage of total I/O blocks transferred by the Allocation Group. When statistics are collected from all nodes in an MPP system, this is the average percentage for all nodes. sblks number of blocks read and written by the group. Utilities 191

192 Chapter 6: Priority Scheduler (schmon, xschmon) schmon -m Display category Allocation Groups (continued) Description Setting... Specifies... # of Procs a number of processes assigned to the Allocation Group at the end of the proceeding collection period. When statistics are collected from all nodes in an MPP system, this is the average per Allocation Group for all nodes. # of Sets a number of scheduling sets associated with the Allocation Group at the end of the preceding collection period. When statistics are collected from all nodes in an MPP system, this is the total per Allocation Group for all nodes. IF Allocation Group Set Division is... THEN one scheduling set... Session per session exists. None to the Allocation Group exists. Performance Groups Affected all Performance Groups by name that reference the Allocation Group at that time. Since Allocation Groups can be shared among Performance Groups, this information is useful for resource usage traceback. (This information is not displayed when statistics are collected from all nodes in an MPP system, unless you use the -p option.) Note: System information is listed under AG 200. This AG has RelWgt set to MAX, which indicates that system work receives the maximum priority, but is not in any RelWgt calculations. Work Requests Displays work request statistics for each active Allocation Group. This data refers to the preceding age period and is the average for all nodes on a multi-node Teradata Database system. The data includes the following: Setting... Specifies the... AG Allocation Group number. # requests number of work requests received. Avg queue wait Avg queue length Avg service time average time, in milliseconds, that a work request waited on an input queue before being serviced. average number of work requests waiting on the input queue for service. average time, in milliseconds, that a work request required for service. 192 Utilities

193 Chapter 6: Priority Scheduler (schmon, xschmon) schmon -m The following apply to MPP configurations: For the -S option: The count of nodes for a single repetition or for multiple repetitions is displayed. Time information is displayed. If a node is offline, it is not be included in the output, and the node count reflects this; however, information about this node being excluded is not displayed. The following apply to SMP configurations: Node count is not shown. A status message that includes time of day regardless of the number of repetitions is displayed. No transient status messages are displayed. Example 1 The following example shows a four-node MPP MP-RAS system. To monitor current Priority Scheduler statistics for the current node, type: schmon -m The following appears: Stats: Tue Jan 20 07:48: Rel Avg CPU Avg I/O # of # of RP Wgt % (msec) % (sblks) Procs Sets === === === ======= === ======= ===== ===== ============================== Rel Avg CPU Avg I/O # of # of AG Wgt % (msec) % (sblks) Procs Sets Performance Groups Affected === === === ======= === ======= ===== ===== ============================== L M R, PGFive 200 MAX System Avg queue Avg queue Avg service AG #requests wait(msec) length time(msec) === ========== ========== ========== =========== Example 2 The following example shows a four-node MPP MP-RAS system. Note: PDE was not up on one of the nodes. To monitor Priority Scheduler statistics for all nodes with a monitoring interval with a fivesecond delay between repetitions of the display, type: schmon -m -S 5 1 The following appears: Stats: 3 node(s) Mon Mar 8 15:32: Avg Avg Node Resource Usage Rel Avg CPU Avg I/O # of # of Minimum Maximum RP Wgt % (msec) % (sblks) Procs Sets CPU I/O Procs CPU I/O Procs Utilities 193

194 Chapter 6: Priority Scheduler (schmon, xschmon) schmon -m === === === ======= === ======= ===== ===== =================== =================== Avg Avg Node Resource Usage Rel Avg CPU Avg I/O # of # of Minimum Maximum AG Wgt % (msec) % (sblks) Procs Sets CPU I/O Procs CPU I/O Procs === === === ======= === ======= ===== ===== =================== =================== Example 3 The following output is from an SMP configuration. The L option shows information on CPU usage limits placed AGs by the System/RP/AG limit feature. This information includes a count of delays imposed on each AG to keep CPU usage within the limits. Delays are reported for the Delay Age period (defined by schmon T). To monitor current Priority Scheduler statistics for the current node with information related to System/RP/AG limits, type: schmon -m -L The following appears: Stats: Tue Jun 13 12:21: Rel Avg CPU Avg I/O # of # of RP Wgt % (msec) % (sblks) Procs Sets === === === ======= === ======= ===== ===== ============================== Rel Avg CPU Avg I/O # of # of Eff. Delay Delay Total AG Wgt % (msec) % (sblks) Procs Sets Limit Count Amnt Delay === === === ======= === ======= ===== ===== ===== ======= ===== ========== Avg queue Avg queue Avg service AG #requests wait(msec) length time(msec) === ========== ========== ========== =========== The following table explains the four additional columns related to CPU limits and delays. Column Eff. Limit Delay Count Delay Amnt Total Delay Explanation The CPU% limit placed on the AG due to a System/RP/AG limit. If the CPU% goes above the effective limit, then delays are imposed on processes or threads to bring the CPU% down towards the limit. The number of delays imposed on tasks in the AG over the Delay Age period. The Delay Age period can be viewed and set using schmon -T. The number of clock ticks that a task was delayed if it had been delayed at the time of the monitor snapshot. The total number of clock ticks that all tasks in the AG have been delayed over the Delay Age period. The Delay Age period can be viewed and set using schmon -T. 194 Utilities

195 Chapter 6: Priority Scheduler (schmon, xschmon) schmon -m Example 4 The following output is from an SMP configuration. To monitor current Priority Scheduler statistics for the current node with a monitoring interval of five seconds and two repetitions, type: schmon -m 5 2 The following appears: Stats Collection #1: Mon Mar 20 18:02: Rel Avg CPU Avg I/O # of # of RP Wgt % (msec) % (sblks) Procs Sets === === === ======= === ======= ===== ===== ============================== Rel Avg CPU Avg I/O # of # of AG Wgt % (msec) % (sblks) Procs Sets Performance Groups Affected === === === ======= === ======= ===== ===== ============================== M Stats Collection #2: Mon Mar 20 18:02: Rel Avg CPU Avg I/O # of # of RP Wgt % (msec) % (sblks) Procs Sets === === === ======= === ======= ===== ===== ============================== Rel Avg CPU Avg I/O # of # of AG Wgt % (msec) % (sblks) Procs Sets Performance Groups Affected === === === ======= === ======= ===== ===== ============================== M Example 5 The -P option shows a separate line of information for each Performance Group. The following example compares the output from schmon -m and schmon -m -P. >schmon -m Stats: Mon Oct 30 14:33: Rel Avg CPU Avg I/O # of # of RP Wgt % (msec) % (sblks) Procs Sets === === === ======= === ======= ===== ===== ============================== Rel Avg CPU Avg I/O # of # of AG Wgt % (msec) % (sblks) Procs Sets Performance Groups Affected === === === ======= === ======= ===== ===== ============================== H, R PG10, PG11, PG PG11, PG12, PG MAX System Utilities 195

196 Chapter 6: Priority Scheduler (schmon, xschmon) schmon -m Avg queue Avg queue Avg service AG #requests wait(msec) length time(msec) === ========== ========== ========== =========== Example 6 >schmon -m -P Stats: Mon Oct 30 14:33: Avg CPU Avg I/O # of # of RP PG % (msec) % (sblks) Procs Sets === === === ======= === ======= ===== ===== ============================== Avg CPU Avg I/O # of # of AG PG % (msec) % (sblks) Procs Sets Performance Groups Affected === === === ======= === ======= ===== ===== ============================== R PG PG PG PG PG PG System Avg queue Avg queue Avg service AG PG #requests wait(msec) length time(msec) === === ========== ========== ========== =========== The following example displays changes in data over time using the default delay time of five seconds. > schmon -m -d Using default 5 second delay. Stats: Thu Feb 08 18:24: Rel Avg CPU Avg I/O # of # of RP Wgt % (msec) % (sblks) Procs Sets === === === ======= === ======= ===== ===== ============================== Rel Avg CPU Avg I/O # of # of AG Wgt % (msec) % (sblks) Procs Sets Performance Groups Affected === === === ======= === ======= ===== ===== ============================== M R PG10, PG11, PG PG10, PG11, PG PG10, PG11, PG PG10, PG11, PG MAX System 196 Utilities

197 Chapter 6: Priority Scheduler (schmon, xschmon) schmon -m Avg queue Avg queue Avg service AG #requests wait(msec) length time(msec) === ========== ========== ========== =========== Utilities 197

198 Chapter 6: Priority Scheduler (schmon, xschmon) schmon -M schmon -M Purpose The schmon -M option displays or monitors Priority Scheduler resource usage statistics for all nodes of an MPP Teradata Database. Syntax schmon -M -n -p -s -P -d delay -V reps 1102C068 where: Syntax element Description -M Displays or monitors Priority Scheduler resource usage statistics for all nodes of Teradata Database. If no additional options are specified, schmon -M displays the current statistics one time. -n Show names for nodes that have the minimum and maximum resource usage and work requests. The displayed names come from the mpplist file. Due to space limitations, names longer than nine characters may be truncated. -p Specifies to display Performance Group names associated with the Allocation Groups that are displayed with the -M command. -s Show Resource Partition and allocation group node resource usage statistics. Displays median and standard deviation values. Also displays a frequency table that shows the number of nodes falling within each of ten usage ranges. If no nodes fall within a range, that range is not included in the table. -V Verbose mode includes inactive nodes in statistical calculations and in the display. Inactive nodes are nodes that report zero usage, which can change the values calculated for median and standard deviations. -P Shows a separate line of information for each Performance Group. Note: Performance Groups with no CPU usage are not shown. 198 Utilities

199 Chapter 6: Priority Scheduler (schmon, xschmon) schmon -M Syntax element Description -d Displays the differences in data between sequential runs of schmon. Use the delay [reps] option to control timing of automatic schmon runs. The following symbols precede numbers that appear in the output from the -d option. - (a minus sign) indicates the value has decreased by the indicated amount since the previous schmon run. An unsigned number indicates the value has increased by the indicated amount since the previous schmon run. For examples of the -d option output, see schmon -m on page 188. Note: The output of the -d option shows only those items for which data has changed since the previous schmon run. delay [reps] Monitors resource usage over time by causing schmon to run again automatically after a specified delay using the current -M options. delay is a positive integer that specifies the number of seconds between schmon executions. Use the optional reps argument, a positive integer, to specify the number of times schmon should run. If reps is not specified, schmon runs indefinitely, with delay seconds between executions. Note: The difference between time stamps of successive information displays may not precisely match the specified delay value due to the time required for the collection activity itself. Usage Notes You can type this command from any node in an MPP system. The settings are described in the following table. Setting category Stats Resource Partitions Description The date and time of the statistics displayed, as well as repetition number, if you specify multiple repetitions. The statistics for each active Resource Partition, including the following: Setting... Specifies... RP Rel Wgt the Resource Partition ID Number. the weight of the Resource Partition relative to the active Resource Partitions. Note: The sum of relative weights might be greater or less than 100 due to the following considerations: Fractions are truncated as the final step in relative weight calculations. Any relative weight calculated to be less than one is converted to one. Utilities 199

200 Chapter 6: Priority Scheduler (schmon, xschmon) schmon -M Setting category Resource Partitions (continued) Description Avg CPU the resource usage during the preceding age period for a single CPU. The CPU data is shown in two columns. Column... Is the... % percentage of CPU consumed by the Resource Partition. When statistics are collected from all nodes in an MPP system, this is the average percentage per Resource Partition for all nodes. msec milliseconds of CPU time consumed by the Resource Partition. Avg I/O a normalized number of data blocks transferred by the Resource Partition. When statistics are collected from all nodes in an MPP system, this is the average normalized resource use per Resource Partition for all nodes on the Teradata Database system. I/O data is shown in two columns. Column... Is the... % percentage of disk consumed by the Resource Partition. When statistics are collected from all nodes in an MPP system, this is the average percentage per Resource Partition for all nodes. sblks number of blocks read and written by the Resource Partition. Avg # of Procs Avg # of Sets the number of processes assigned to the Resource Partition at the end of the preceding collection period. When statistics are collected from all nodes in an MPP system, this is the average per Resource Partition for all nodes. the number of scheduling sets associated with the Resource Partition at the end of the preceding collection period. IF Allocation Group Set Division is... THEN one scheduling set... Session per session exists. None to the Allocation Group exists. Minimum CPU Minimum I/O Minimum Procs Maximum CPU Maximum I/O Maximum Procs the lowest value in milliseconds of CPU resource usages from all nodes. the lowest value of I/O data blocks transferred from all nodes in sblks. the lowest number of processes from all nodes. the highest value in milliseconds of CPU resource usages from all nodes. the highest value of I/O data blocks transferred from all nodes in sblks. the highest number of processes from all nodes. 200 Utilities

201 Chapter 6: Priority Scheduler (schmon, xschmon) schmon -M Setting category Allocation Groups Description The statistics for each active Allocation Group, including the following: Setting... Specifies... AG Rel Wgt Avg CPU the Allocation Group ID Number. the weight of the Allocation Group relative to the active Allocation Groups of the Resource Partition and the active Resource Partitions. Note: The sum of relative weights might be greater or less than 100 due to the following considerations: Fractions are truncated as the final step in relative weight calculations. Any relative weight calculated to be less than one is converted to one. the resource usage by the Allocation Group during the preceding age period for a single CPU. The CPU data is shown in two columns. Column... Is the... % percentage of total available CPU on the node consumed by the Allocation Group. When statistics are collected from all nodes in an MPP system, this is the average percentage for all nodes. msec milliseconds of CPU usage consumed by the Allocation Group. Avg I/O a normalized number of data blocks transferred by the Allocation Group. When statistics are collected from all nodes in an MPP system, this is the average normalized resource use per Allocation Group for all nodes on the Teradata Database system. I/O data is shown in two columns. Column... Is the... % percentage of total I/O blocks transferred by the Allocation Group. When statistics are collected from all nodes in an MPP system, this is the average percentage for all nodes. sblks number of blocks read and written by the Allocation Group. Avg # of Procs the number of processes assigned to the Allocation Group at the end of the preceding collection period. When statistics are collected from all nodes in an MPP system, this is the average per Allocation Group for all nodes. Utilities 201

202 Chapter 6: Priority Scheduler (schmon, xschmon) schmon -M Setting category Allocation Groups (continued) Description Setting... Specifies... Avg # of Sets number of scheduling sets associated with the Allocation Group at the end of the preceding collection period. When statistics are collected from all nodes in an MPP system, this is the average per Allocation Group for all nodes. IF Allocation Group Set Division is... THEN one scheduling set... Session per session exists. None to the Allocation Group exists. When you submit the -M command on an MPP system, the following minimum and maximum values are displayed: Setting... Specifies the... Minimum CPU Minimum I/O Minimum Procs Maximum CPU Maximum I/O Maximum Procs lowest value in milliseconds of CPU resource usages from all nodes. lowest value of I/O data blocks transferred from all nodes in sblks. lowest number of processes from all nodes. highest value in milliseconds of CPU resource usages from all nodes. highest value of I/O data blocks transferred from all nodes in sblks. highest number of processes from all nodes. When you submit the -M command or specify the -p option on an SMP system, the affected Performance Groups are displayed instead of the minimum and maximum values: Setting... Specifies... Performance Groups Affected all Performance Groups by name that reference the Allocation Group at that time. Since Allocation Groups can be shared among Performance Groups, this information is useful for resource usage traceback. (This information is not displayed when statistics are collected from all nodes in an MPP system unless you use the -p option.) Note: System information is listed under AG 200. This AG has RelWgt set to MAX, which indicates that system work receives the maximum priority, but is not in any RelWgt calculations. 202 Utilities

203 Chapter 6: Priority Scheduler (schmon, xschmon) schmon -M Setting category Work Requests Description Displays work request statistics for each active Allocation Group. This data refers to the preceding age period and is the average for all nodes on a multi-node Teradata Database system. The data includes the following: Setting... Specifies the... AG Allocation Group number. # requests number of work requests received. Avg queue wait Avg queue length Avg service time average time, in milliseconds, that a work request waited on an input queue before being serviced. average number of work requests waiting on the input queue for service. average time, in milliseconds, that a work request required for service. The following apply to MPP configurations: For the -M option: The count of nodes for a single repetition or for multiple repetitions is displayed. Time information is displayed. If a node is offline, it is not be included in the output, and the node count reflects this; however, information about this node being excluded is not displayed. The following apply to SMP configurations: Node count is not shown. A status message that includes time of day regardless of the number of repetitions is displayed. No transient status messages are displayed. Example 1 schmon -M Stats: 4 node(s) Tue Oct 25 14:10: Avg Avg Node Resource Usage Rel Avg CPU Avg I/O # of # of Minimum Maximum RP Wgt % (msec) % (sblks) Procs Sets CPU I/O Procs CPU I/O Procs == === === ======= === ======= ===== ===== ================== ====================== Avg Avg Node Resource Usage Rel Avg CPU Avg I/O # of # of Minimum Maximum AG Wgt % (msec) % (sblks) Procs Sets CPU I/O Procs CPU I/O Procs == === === ======= === ======= ===== ===== ================== ====================== MAX Avg queue Avg queue Avg service AG #requests wait(msec) length time(msec) === ========== ========== ========== =========== Utilities 203

204 Chapter 6: Priority Scheduler (schmon, xschmon) schmon -M Minimum Avg queue Avg queue Avg service AG #requests wait(msec) length time(msec) === ========== ========== ========== =========== Maximum Avg queue Avg queue Avg service AG #requests wait(msec) length time(msec) === ========== ========== ========== =========== Example 2 The following example shows a four-node MPP MP-RAS system with one node where PDE is NULL. Note: PDE was not up on one of the nodes. To monitor Priority Scheduler statistics for all nodes with a five-second delay between two repetitions of the display, type: schmon -M 5 2 The following appears: Stats Collection #1: 3 node(s) Sat Aug 30 08:44: Avg Avg Node Resource Usage Rel Avg CPU Avg I/O # of # of Minimum Maximum RP Wgt % (msec) % (sblks) Procs Sets CPU I/O Procs CPU I/O Procs === === === ======= === ======= ===== ===== ================= ================== Avg Avg Node Resource Usage Rel Avg CPU Avg I/O # of # of Minimum Maximum AG Wgt % (msec) % (sblks) Procs Sets CPU I/O Procs CPU I/O Procs === === === ======= === ======= ===== ===== ================= ================== Stats Collection #2: 3 node(s) Sat Aug 30 08:44: Avg Avg Node Resource Usage Rel Avg CPU Avg I/O # of # of Minimum Maximum RP Wgt % (msec) % (sblks) Procs Sets CPU I/O Procs CPU I/O Procs === === === ======= === ======= ===== ===== ================= ================== Avg Avg Node Resource Usage Rel Avg CPU Avg I/O # of # of Minimum Maximum AG Wgt % (msec) % (sblks) Procs Sets CPU I/O Procs CPU I/O Procs === === === ======= === ======= ===== ===== ================= ================== Example 3 The following example shows a four-node MPP MP-RAS system with one node where PDE is NULL. This display also appears if you execute the -M command (with or without the -p option) on an SMP system. Note: PDE was not up on one of the nodes. To display Performance Group names associated with the Allocation Groups that are displayed with the -M command on an MPP system, type: schmon -M -p 204 Utilities

205 Chapter 6: Priority Scheduler (schmon, xschmon) schmon -M The following appears: Stats: 3 node(s) Sat Aug 30 08:45: Avg Avg Rel Avg CPU Avg I/O # of # of RP Wgt % (msec) % (sblks) Procs Sets === === === ======= === ======= ===== ===== ============================== Avg Avg Rel Avg CPU Avg I/O # of # of AG Wgt % (msec % (sblks) Procs Sets Performance Groups Affected === === === ======= === ======= ===== ===== ============================== M Example 4 To display the names of the nodes that have the minimum and maximum resource usage, type: schmon -M -n The following appears: Stats: 4 node(s) Tue Oct 25 14:10: Avg Avg Node Resource Usage Rel Avg CPU Avg I/O # of # of Minimum Maximum RP Wgt % (msec) % (sblks) Procs Sets CPU I/O Procs CPU I/O Procs === === === ======= === ======= ===== ===== ===================== =================== Avg Avg Node Resource Usage Rel Avg CPU Avg I/O # of # of Minimum Maximum AG Wgt % (msec) % (sblks) Procs Sets CPU I/O Procs CPU I/O Procs === === === ======= === ======= ===== ===== ===================== =================== MAX Node Names: RP/AG CPU_min CPU_max I/O_min I/O_max Procs_min Procs_max ===== ========== ========== ========== ========== ========== ========== RP0 tnt45_byne tnt47_byne tnt47_byne tnt46_byne tnt45_byne tnt44_byne AG2 tnt45_byne tnt47_byne tnt47_byne tnt46_byne tnt45_byne tnt44_byne AG200 tnt44_byne tnt47_byne tnt45_byne tnt47_byne tnt45_byne tnt44_byne Avg queue Avg queue Avg service AG #requests wait(msec) length time(msec) === ========== ========== ========== =========== Minimum Avg queue Avg queue Avg service AG #requests wait(msec) length time(msec) === ========== ========== ========== =========== Maximum Avg queue Avg queue Avg service AG #requests wait(msec) length time(msec) === ========== ========== ========== =========== Node Names: RP/AG Rqsts_min Rqsts_max QWait_min QWait_max QLen_min QLen_max STime_min STime_max ===== ========= ========= ========= ========= ========= ========= ========= ======== AG2 tnt44_byn tnt47_byn tnt46_byn tnt47_byn tnt46_byn tnt47_byn tnt44_byn tnt47_byn AG200 tnt46_byn tnt47_byn tnt46_byn tnt47_byn tnt46_byn tnt47_byn tnt46_byn tnt47_byn Utilities 205

206 Chapter 6: Priority Scheduler (schmon, xschmon) schmon -M Example 5 To show RP and AG resource usage statistics, type: schmon -M -s The following appears: Stats: 4 node(s) Tue Oct 25 14:11: Avg Avg Node Resource Usage Rel Avg CPU Avg I/O # of # of Minimum Maximum RP Wgt % (msec) % (sblks) Procs Sets CPU I/O Procs CPU I/O Procs === === === ======= === ======= ===== ===== ===================== =================== Avg Avg Node Resource Usage Rel Avg CPU Avg I/O # of # of Minimum Maximum AG Wgt % (msec) % (sblks) Procs Sets CPU I/O Procs CPU I/O Procs === === === ======= === ======= ===== ===== ===================== =================== MAX Statistics: RP 0 (4 Active Nodes): CPU Median: I/O Median: Procs Median: 9.50 StdDev: StdDev: StdDev: 0.83 Range Freq Range Freq Range Freq ====================== ====================== ====================== AG 2 (4 Active Nodes): CPU Median: I/O Median: Procs Median: 9.50 StdDev: StdDev: StdDev: 0.83 Range Freq Range Freq Range Freq ====================== ====================== ====================== AG 200 (4 Active Nodes): CPU Median: I/O Median: Procs Median: StdDev: StdDev: StdDev: 1.22 Range Freq Range Freq Range Freq ====================== ====================== ====================== Avg queue Avg queue Avg service AG #requests wait(msec) length time(msec) === ========== ========== ========== =========== Minimum Avg queue Avg queue Avg service AG #requests wait(msec) length time(msec) === ========== ========== ========== =========== Maximum Avg queue Avg queue Avg service AG #requests wait(msec) length time(msec) === ========== ========== ========== =========== Statistics: AG 2 (4 Active Nodes): Requests Median: Q Length Median: Utilities

207 Chapter 6: Priority Scheduler (schmon, xschmon) schmon -M StdDev: 8.66 StdDev: 0.00 Range Freq Range Freq ====================== ====================== Que Wait Median: 1.00 Srv Time Median: StdDev: 0.38 StdDev: Range Freq Range Freq ====================== ====================== AG 200 (2 Active Nodes): Requests Median: 3.00 Q Length Median: 0.00 StdDev: 2.83 StdDev: 0.00 Range Freq Range Freq ====================== ====================== Que Wait Median: Srv Time Median: StdDev: StdDev: Range Freq Range Freq ====================== ====================== Example 6 To show statistics in verbose mode, which includes inactive nodes, type: schmon -M -s -V The following appears: Stats: 4 node(s) Tue Oct 25 14:13: Avg Avg Node Resource Usage Rel Avg CPU Avg I/O # of # of Minimum Maximum RP Wgt % (msec) % (sblks) Procs Sets CPU I/O Procs CPU I/O Procs === === === ======= === ======= ===== ===== ===================== =================== Avg Avg Node Resource Usage Rel Avg CPU Avg I/O # of # of Minimum Maximum AG Wgt % (msec) % (sblks) Procs Sets CPU I/O Procs CPU I/O Procs === === === ======= === ======= ===== ===== ===================== =================== MAX Statistics: RP 0 (4 Active Nodes): CPU Median: I/O Median: Procs Median: StdDev: StdDev: StdDev: 1.22 Range Freq Range Freq Range Freq ====================== ====================== ====================== AG 2 (4 Active Nodes): CPU Median: I/O Median: Procs Median: StdDev: StdDev: StdDev: 1.12 Range Freq Range Freq Range Freq ====================== ====================== ====================== Utilities 207

208 Chapter 6: Priority Scheduler (schmon, xschmon) schmon -M AG 3 (1 Active Node): CPU Median: I/O Median: 0.00 Procs Median: 2.00 StdDev: 0.00 StdDev: 0.00 StdDev: 0.00 Range Freq Range Freq Range Freq ====================== ====================== ====================== AG 3 (All Nodes): CPU Median: 0.00 I/O Median: 0.00 Procs Median: 0.00 StdDev: StdDev: 0.00 StdDev: 0.87 AG 4 (1 Active Node): CPU Median: I/O Median: 0.00 Procs Median: 0.00 StdDev: 0.00 StdDev: 0.00 StdDev: 0.00 Range Freq Range Freq Range Freq ====================== ====================== ====================== AG 4 (All Nodes): CPU Median: 0.00 I/O Median: 0.00 Procs Median: 0.00 StdDev: 4.76 StdDev: 0.00 StdDev: 0.00 AG 200 (4 Active Nodes): CPU Median: I/O Median: Procs Median: StdDev: StdDev: StdDev: 1.22 Range Freq Range Freq Range Freq ====================== ====================== ====================== Utilities

209 Chapter 6: Priority Scheduler (schmon, xschmon) schmon -p schmon -p Purpose The schmon -p option sets or displays Performance Group parameters. Syntax schmon -p PG# PGNAME R T PP -x -s -S -T -P -d delay reps 1102E010 where: Syntax Element Description -p Sets or displays Performance Group parameters. If no additional options are specified, schmon -p displays the parameters for all Performance Groups currently in use (those with defined parameters). PG# PGNAME R An integer from 0 through 39 that identifies the Performance Group for which parameters will be set or displayed. To set parameters for a Performance Group, follow PG# with the PGName, R, T, and PP specifications. To view information about a specific Performance Group, follow PG# with the -s or -S options, or with no options. To clear all parameters for a specific Performance Group, follow PG# with the -x option. Specifies the name of the Performance Group with the Resource Partition. Names with spaces must be enclosed in single quotation marks. Specifies the Resource Partition to which this Performance Group is to be assigned. Utilities 209

210 Chapter 6: Priority Scheduler (schmon, xschmon) schmon -p Syntax Element T PP Description Specifies a single character that indicates the milestone type used in the Performance Period definitions for that Performance Group, where: Q indicates that milestone units are seconds ( ) of query resource usage. Each query submitted by a session begins a new resource usage accumulation at the first Performance Period defined for the Performance Group. R or S indicates that milestone units are seconds ( ) of session resource usage. These two characters are equivalent. The R option is provided for backward compatibility with earlier software versions. T indicates that milestone units are time-of-day, in military time (0-2359). Time-of- day units can be optionally preceded by a day-of-week indicator. Day-of-week format is: '/d1-d2/ or /d1,d2,...dn/'. Valid values for day are 0(Sun)-6(Sat). For example, '/3-5/' indicates that the associated Performance Period would be active Wednesday through Friday. A Performance Period pair consisting of a milestone limit value and Allocation Group number for each of up to eight Performance Periods. Allocation groups can be referenced by multiple Performance Groups, which must belong to the same Resource Partition. When the milestone type is Q, R, or S, the lower bound for the first Performance Period is assumed to be zero. Also, the milestone of the last Performance Period must be zero. After a session or query enters the last Performance Period, that period remains in control for the remainder of the session or query. When the milestone type is Q, R, or S, the milestone limit is a real number greater than 0 and less than You can enter this number with an optional decimal point and fractional value. The given number is rounded to the nearest 1/100 second value. The following examples are valid milestone limit CPU usage times: s Displays Priority Scheduler data for all sessions controlled by the Performance Group on the current node. -S Displays Priority Scheduler data for all sessions controlled by the Performance Group on all nodes of the Teradata Database system. 210 Utilities

211 Chapter 6: Priority Scheduler (schmon, xschmon) schmon -p Syntax Element Description -T Displays process and thread tasks for the specified Performance Group on the current node (the node from which schmon was invoked). Even when used in conjunction with the -S option, -T will display only task data for the current node. Note: The -T option should not be used for prolonged periods of time, because it can interfere with the normal operation of Priority Scheduler. The -T output includes the following columns: Procqueue Tsk Addr: Kernel address of the proc control block Tskid: PID (MPRAS), thread ID (Windows, Linux) Prio: OS priority Session: Task session number Request: Task request number Tskuse: Task CPU resource usage Tskterm: Task resource usage to weight ratio -P Shows session information for individual Performance Groups. Note: Performance Groups with no CPU usage are not shown. -d Displays the differences in data between sequential runs of schmon. Use the delay [reps] option to control timing of automatic schmon runs. The following symbols precede numbers that appear in the output from the -d option. For decimal numbers: - (a minus sign) indicates the value has decreased by the indicated amount since the previous schmon run. An unsigned decimal number indicates the value has increased by the indicated amount since the previous schmon run. For task data (displayed if the -T option is used with the -d option): n-> indicates a task has been moved from the control of AG n to the control of the displayed AG since the previous schmon run. + indicates a task is new, started since the previous schmon run. - indicates a task that ended since the previous schmon run. * indicates a task that has changed sessions or requests since the previous schmon run. For examples of the -d option output, see schmon -m on page 188, and schmon -s on page 214. Note: The output of the -d option shows only those items for which data has changed since the previous schmon run. Utilities 211

212 Chapter 6: Priority Scheduler (schmon, xschmon) schmon -p Syntax Element delay [reps] Description Causes schmon -p to run again automatically after a specified delay using the current session options. delay is a positive integer that specifies the number of seconds between schmon executions. Use the optional reps argument, a positive integer, to specify the number of times schmon should run. If reps is not specified, schmon runs indefinitely with delay seconds between executions. In this case, schmon can be stopped by pressing Ctrl-C or otherwise killing the schmon process. Note: The difference between time stamps of successive information displays may not precisely match the specified delay value due to the time required for the collection activity itself. -x Clears the parameters that define the specified Performance Group, effectively deleting it from the system (though an empty group will still appear in the output of schmon -p all ). The Teradata Database must be in the logons enabled state to delete a Performance Group. The Performance Group must not be referenced by any system user. Under certain circumstances, the deletion process of a Performance Group within schmon may be rejected and the cleanup process may not be executed successfully. In this situation, any subsequent attempts to delete the Performance Group will fail and the following error message is reported: schmon -p 4 -x schmon: Performance Group is in remove state If this occurs, do the following: 1 Recreate the Performance Group by executing the proper schmon -p command. Recreating the Performance Group clears the remove status. 2 Delete the Performance Group created in step one by executing the proper schmon - p command using the format below. schmon -p PG# -x For example, to delete Performance Group 4, type: schmon -p 4 -x Usage Notes If a Performance Group has only a single Performance Period, the milestone limit must be zero. If a Performance Group has multiple Performance Periods, the milestone limit of the final Performance Period must be zero. The following apply to MPP configurations: For the -S option: The count of nodes for a single repetition or for multiple repetitions is displayed. Time information is displayed. 212 Utilities

213 Chapter 6: Priority Scheduler (schmon, xschmon) schmon -p If a node is offline, it is not be included in the output, and the node count reflects this; however, information about this node being excluded is not displayed. The following apply to SMP configurations: Node count is not shown. A status message that includes time of day regardless of the number of repetitions is displayed. No transient status messages are displayed. Example 1 To display session data for sessions assigned to Performance Group 1, type: schmon -p 1 -s The following appears: AG HostID Session Request #prc CPU(msec) DSK(blk) RP PG [PP] === ====== ========== ========== ==== ========== ========== === =============== M[0] Example 2 Suppose you want to provide different levels of service on weekdays, Saturday, and Sunday. On weekdays, one Performance Period is in effect between 0800 and 1800, another beginning at 1800 and continuing until 0800 the next morning. On Saturday the Performance Period from 1800 on Friday continues until 1400 and then switches to another Performance Period that continues through Sunday and on until 0800 Monday morning. The Performance Period specification is as follows, where day of the week is denoted by enclosing / characters, as shown below: /1/ Monday, use AG 5 until 0800 /2-5/ Tuesday through Friday, use AG 7 until 0900 /1-5/ Monday through Friday, use AG 2 until After 1800, use the next higher period. /6/ Saturday, use AG 7 until After 1400, use the next Performance Period, which is the one specified for 0800 Monday that uses AG 5. To provide the above levels of service, type: schmon -p 2 M 0 T /1/ /2-5/ /1-5/ /6/ The following appears: Performance Groups (0-39) Id Group Name RP Type Milestones & Allocation Groups[0-4] 2 M 0 T /1/ /2-5/ /1-5/ /6/ 1800 Utilities 213

214 Chapter 6: Priority Scheduler (schmon, xschmon) schmon -s schmon -s Purpose The schmon -s option displays Priority Scheduler data for the specified sessions from the current node or all nodes in the Teradata Database system. Syntax schmon -s all id -S -T -P -d delay reps 1102C071 where: -s Displays Priority Scheduler data for the current sessions. If no additional options are specified, schmon -s displays session information for the current node. all id Shows information for all sessions. This is the default. A positive integer that identifies a session for which Priority Scheduler data will be displayed. -S Shows session information from all nodes in Teradata Database. 214 Utilities

215 Chapter 6: Priority Scheduler (schmon, xschmon) schmon -s -T Displays process and thread tasks for the specified sessions on the current node (the node from which schmon was invoked). Even when used in conjunction with the -S option, -T will display only task data for the current node. Note: The -T option should not be used for prolonged periods of time, because it can interfere with the normal operation of Priority Scheduler. The -T output includes the following columns: Procqueue Tsk Addr: Kernel address of the proc control block Tskid: PID (MPRAS), thread ID (Windows, Linux) Prio: OS priority Session: Task session number Request: Task request number Tskuse: Task CPU resource usage Tskterm: Task resource usage to weight ratio -P Shows session information for individual Performance Groups. Note: Performance Groups with no CPU usage are not shown. -d Displays the differences in data between sequential runs of schmon. Use the delay [reps] option to control timing of automatic schmon runs. The following symbols precede numbers that appear in the output from the -d option. For decimal numbers: - (a minus sign) indicates the value has decreased by the indicated amount since the previous schmon run. An unsigned decimal number indicates the value has increased by the indicated amount since the previous schmon run. For task data (displayed if the -T option is used with the -d option): n-> indicates a task has been moved from the control of AG n to the control of the displayed AG since the previous schmon run. + indicates a task is new, started since the previous schmon run. - indicates a task that ended since the previous schmon run. * indicates a task that has changed sessions or requests since the previous schmon run. Note: The output of the -d option shows only those items for which data has changed since the previous schmon run. Utilities 215

216 Chapter 6: Priority Scheduler (schmon, xschmon) schmon -s delay [reps] Causes schmon -s to run again automatically after a specified delay using the current options. delay is a positive integer that specifies the number of seconds between schmon executions. Use the optional reps argument, a positive integer, to specify the number of times schmon should run. If reps is not specified, schmon runs indefinitely with delay seconds between executions. In this case, schmon can be stopped by pressing Ctrl-C or otherwise killing the schmon process. The difference between time stamps of successive information displays may not precisely match the specified delay value due to the time required for the collection activity itself. Note: The delay option cannot be used alone with schmon -s. It must be preceded by one or more of the id, all, -S, -T, or -P options. Usage Notes schmon -s displays the following columns: Column AG Host ID Session Request #prc CPU(msec) DSK(blk) RP PG [PP] Description Allocation Group ID. Host system of an active session. Session number of an active session. Request number of an active session. Number of processes working on behalf of the session. Number of milliseconds of CPU time accumulated by the session or request during the previous age period. Number of disk blocks transferred by the session or request during the previous age period. Resource Partition to which the line s allocation group belongs. Performance Group to which the session is assigned. Performance Period currently controlling the session. Each Performance Group defines one or more Performance Periods. A PG s PPs determine the resource allocation to processes run by sessions controlled by the PG. For more information on PGs and PPs, see Performance Groups on page Utilities

217 Chapter 6: Priority Scheduler (schmon, xschmon) schmon -s Example 1 To display Priority Scheduler data for the specified sessions from the current node or all nodes in the Teradata Database system, type: In the following example, session 0 indicates a session performing system utility functions that might have processes running in several allocation groups. schmon -s The following appears: Stats: Mon Mar 8 15:49: AG HostID Session Request #prc CPU(msec) DSK(blk) RP PG [PP] === ====== ========== ========== ==== ========== ========== === =============== L[0] M[0] R[0] Example 2 The -P option shows a separate line of information for each Performance Group. The following example compares the output from schmon -s and schmon -s -P. >schmon -s Stats: Mon Oct 30 16:55: AG HostID Session Request #prc CPU(msec) DSK(blk) RP PG [PP] === ====== ========== ========== ==== ========== ========== === =============== L[0] M[0] H[0] R[0] PG10[0] PG11[0] PG12[0] PG13[0] PG10[0] PG11[0] PG12[0] PG13[0] PG10[0] PG11[0] PG12[0] PG13[0] PG10[0] PG11[0] PG12[0] PG13[0] System[0] >schmon -s -P: Stats: Mon Oct 30 16:55: AG HostID Session Request #prc CPU(msec) DSK(blk) RP PG [PP] === ====== ========== ========== ==== ========== ========== === =============== L[0] M[0] H[0] R[0] PG13[0] PG10[0] PG12[0] PG11[0] System[0] Example 3 The -T option displays per-ag process and thread information for the specified sessions. This is an example of some of the output from an MP-RAS system. >schmon -s all -T AG HostID Session Request #prc CPU(msec) DSK(blk) RP PG [PP] === ====== ========== ========== ==== ========== ========== === =============== M[0] Utilities 217

218 Chapter 6: Priority Scheduler (schmon, xschmon) schmon -s Procqueue Tsk Addr Tskid Prio Session Request Tskuse Tskterm ==================== ====== ==== ========== ========== ========== ======= c820cbe c820ca c7a c820c c820c67c c820c4b c820bf4c c820c2e c820c c820bd c820bbb c820b9e c820b81c c820b AG HostID Session Request #prc CPU(msec) DSK(blk) RP PG [PP] === ====== ========== ========== ==== ========== ========== === =============== R[0] Procqueue Tsk Addr Tskid Prio Session Request Tskuse Tskterm ==================== ====== ==== ========== ========== ========== ======= c5da c5da6f0c c5d9e2e c820d c820fc c7a22f4c c7a1fb c6c9f c6ca8f c7a c70795e Example 4 This example displays differences in session data over three automatic runs of schmon spaced five seconds apart. > schmon -s -d 5 3 Stats Collection #1: Mon Mar 19 11:50: AG HostID Session Request #prc CPU(msec) DSK(blk) RP PG [PP] === ====== ========== ========== ==== ========== ========== === =============== M[0] Stats Collection #2: Mon Mar 19 11:50: AG HostID Session Request #prc CPU(msec) DSK(blk) RP PG [PP] === ====== ========== ========== ==== ========== ========== === =============== M[0] Stats Collection #3: Mon Mar 19 11:50: Example 5 No difference in data this period > schmon -s -T -d 5 3 This example displays differences in session data over three automatic runs of schmon spaced five seconds apart, and includes information on process and thread tasks for the current node. Stats Collection #1: Mon Mar 19 11:51: Utilities

219 Chapter 6: Priority Scheduler (schmon, xschmon) schmon -s AG HostID Session Request #prc CPU(msec) DSK(blk) RP PG [PP] === ====== ========== ========== ==== ========== ========== === =============== DR98889[4] Procqueue Tsk Addr Tskid Prio Session Request Tskuse Tskterm ==================== ====== ==== ========== ========== ========== ======= + 0xffffff fa AG HostID Session Request #prc CPU(msec) DSK(blk) RP PG [PP] === ====== ========== ========== ==== ========== ========== === =============== DR98889[5] Procqueue Tsk Addr Tskid Prio Session Request Tskuse Tskterm ==================== ====== ==== ========== ========== ========== ======= 14->0xffffff c Stats Collection #2: Mon Mar 19 11:51: AG HostID Session Request #prc CPU(msec) DSK(blk) RP PG [PP] === ====== ========== ========== ==== ========== ========== === =============== DR98889[5] DR98889[5] Procqueue Tsk Addr Tskid Prio Session Request Tskuse Tskterm ==================== ====== ==== ========== ========== ========== ======= 0xffffff c >0xffffff fa Stats Collection #3: Mon Mar 19 11:51: AG HostID Session Request #prc CPU(msec) DSK(blk) RP PG [PP] === ====== ========== ========== ==== ========== ========== === =============== DR98889[5] DR98889[5] Procqueue Tsk Addr Tskid Prio Session Request Tskuse Tskterm ==================== ====== ==== ========== ========== ========== ======= 0xffffff c xffffff fa Utilities 219

220 Chapter 6: Priority Scheduler (schmon, xschmon) schmon -t schmon -t Purpose The schmon -t option sets or displays Age Time, Active Time, and Disp Time. Syntax schmon -t age active disp 1102C072 where: Syntax element Description -t Sets or displays Age Time, Active Time, and Disp Time. where: Option age active Description The time period, in seconds, over which recent allocating group resource usage is measured. The range is 1 to 1800 seconds. The default is 60 seconds. The time period, in seconds, during which an Allocation Group is considered active if any process assigned to the Allocation Group has been scheduled. Inactive Allocation Groups are not included in resource consumption calculations. The range is 1 to 1800 seconds. The default is 61 seconds. 220 Utilities

221 Chapter 6: Priority Scheduler (schmon, xschmon) schmon -t Syntax element Description -t (continued) Option disp Description The maximum period of time that a process can wait in a ready-for-execution state in a dispatch queue without receiving access to a CPU. After this time, the process dispatch priority is promoted to the next-higher dispatch priority and its wait period re-initialized. Note: This option is functional on MP-RAS only. A value of... Specifies... 0 that processes are not to be promoted. Note: The dispatch wait setting (or anti-starvation mechanism) is enabled by default. The dispatch wait default value is 4 seconds. If the dispatch wait setting is 0 and the task has been waiting in the dispatch queue more than 4 seconds, the task priority is promoted to the next-higher dispatch priority. The task priority can be promoted to a maximum of that the anti-starvation mechanism be disabled. Caution: Teradata recommends you do not use this setting unless absolutely necessary a wait period in seconds. The following applies. IF you do... THEN... not specify any options specify options the current settings are displayed. you must specify all the options: Active Time, Age Time, and Disp Time. Example To view the current settings, type: schmon -t The following appears: Age Time(sec): 60 Active Time(sec): 61 Disp Age(sec): 5 To change the settings, type: schmon -t The following appears: Utilities 221

222 Chapter 6: Priority Scheduler (schmon, xschmon) schmon -t Age Time(sec): 60 Active Time(sec): 61 Disp Age(sec): 0 >>>>> Changed to: Age Time(sec): 30 Active Time(sec): 31 Disp Age(sec): Utilities

223 Chapter 6: Priority Scheduler (schmon, xschmon) schmon -T schmon -T Purpose The schmon -T option sets or displays the Delay Age, the time period over which Delay Count and Total Delay statistics are collected. These statistics can be displayed using the schmon -m -L command. For more information see schmon -m on page 188. Syntax schmon -T delayage 1102A167 where: Syntax element delayage Description The time in seconds during which AG Delay Count and Total Delay statistics will be collected. Usage Notes Example CPU usage limits can be set at the AG, RP, or Teradata Database system level using schmon -a, -b, and -l options, respectively. AG processes and threads can be delayed by the system, if necessary, to keep the CPU usage within those limits. To view the current settings, type: schmon -T The following appears: Delay Age Time(sec): 60 To change the Delay Age to 30 seconds, type: schmon -T 30 The following appears: Delay Age Time(sec): 60 >>>>> Changed to: Delay Age Time(sec): 30 Utilities 223

224 Chapter 6: Priority Scheduler (schmon, xschmon) schmon -w schmon -w Purpose The schmon -w option sets or displays the number of processes available on each vproc for use by work requests assigned to Allocation Groups having the Expedite attribute. Syntax schmon -w reserve maximum HH01A011 where: Syntax element Description -w Sets or displays the number of processes available on each vproc for use by work requests assigned to Allocation Groups having the Expedite attribute. where: Option reserve Description A number between 0 and 5, inclusive, that indicates the number of AWTs reserved within each AMP vproc for work requests assigned to Allocation Groups having the EXPEDITE attribute. This reserve ensures that at least this specified number of AWTs will be ready to service a work request when it arrives. When the number of expedited work requests exceeds this reserve, arriving expedited work requests might be forced to wait in an input queue, depending on overall work load conditions. This reserve determines the minimum number of expedited work requests that will run concurrently. This reserve, multiplied by three, is deducted from the general pool of AWTs and will impact the number of tasks available for normal non-expedited work requests. Teradata recommends the following: Initially select a low number for reserve (1-3). Expedite only Allocation Groups supporting short, response-sensitive queries. 224 Utilities

225 Chapter 6: Priority Scheduler (schmon, xschmon) schmon -w Syntax element Description -w (continued) maximum A number between 1 and 999, inclusive, that indicates the maximum number of AWTs that can run at any time. The number of tasks that run might be less than this maximum, depending on the current limit. Since the special reserve work type supports new work, similar to MSGWORKNEW, one reasonable setting for the parameter is the same as the MSGWORKNEW maximum(50). Note: Since most systems have a practical limit of 80 AMP worker tasks per AMP that can be supported at any one time, the 999 value has no real function. If you do not supply any parameters, the current settings for reserve and maximum are displayed. Usage Notes Example 1 The Expedite attribute is defined by an Allocation Group. For more information see Expedite Attribute on page 155 and AMP Worker Task (AWT) Reservations and Limits on page 159. Consider scripting a set of schmon commands for each restoration and maintenance. To display the number AWTs reserved within each AMP vproc for work requests assigned to Allocation Groups having the EXPEDITE attribute and the maximum number of AWTs that can run at any time, type: schmon -w The following appears: res max AWT Expedited work type limits Example 2 To set the number AWTs reserved within each AMP vproc for work requests assigned to Allocation Groups having the EXPEDITE attribute and the maximum number of AWTs that can run at any time, type: schmon -w 5 10 The following appears: res max AWT Expedited work type limits >>>>> Changed to: 5 10 Utilities 225

226 Chapter 6: Priority Scheduler (schmon, xschmon) xschmon Utility xschmon Utility Note: xschmon will be removed from the next release of Teradata Database. For a graphical user interface to Priority Scheduler, use Priority Scheduler Administrator. For more information on Priority Scheduler Administrator, see Teradata Manager User Guide. Function The xschmon utility is a graphical user interface X-window system that uses the OSF/Motif Toolbox to manage its window resources. xschmon allows you to display and alter Priority Scheduler parameters. Note: If Workload Definitions have been activated using Teradata Dynamic Workload Manager, schmon and xschmon cannot be used to make changes to Priority Scheduler. For more information, see the Teradata Dynamic Workload Manager User Guide. User Interfaces xschmon runs on the following platforms and interfaces: Platform MP-RAS Interfaces Command line For general information on starting the utilities from different platforms and interfaces, see Appendix B: Starting the Utilities. On MP-RAS, xschmon displays a windowed graphical user interface (GUI). xschmon requires an X server to be running on the local machine. Use the X11 -display option to specify the name or IP address of the current workstation and display. For example: xschmon -display displayspec & where displayspec is the name or IP address of the local machine, followed by a colon and the server number, usually 0 or 0.0. For example: xschmon -display myworkstation.mycompany.com:0.0 & or xschmon -display :0.0 & Syntax xschmon -display host : server.screen GS02A Utilities

227 Chapter 6: Priority Scheduler (schmon, xschmon) xschmon Utility where: Syntax element... Specifies the... -display host server screen display is output to a particular host, server, and screen specified. IP address of your machine. server number. screen number. xschmon Main Window When you start xschmon, the main window appears, as shown below. Utilities 227

228 Chapter 6: Priority Scheduler (schmon, xschmon) xschmon Utility The main window consists of the following attributes. Attribute Description Age Time The time period over which recent resource usage is measured. The default is 60 seconds. Active Time System CPU Limit (%) The time period during which an Allocation Group is considered active if any process assigned to the group has been scheduled for execution. Inactive Allocation Groups are not included in resource consumption or relative weight calculations. The default is 61 seconds. A percentage value to limit the amount of CPU usage by the Teradata Database sessions. This usage does not include non-teradata work, such as time-share users, I/O or other interrupt services, Gateway processing, or streams work. The value ranges from 1 through 100. A value of... Specifies that or none no limit is to be enforced CPU resource use is to be limited to the indicated percentage. Dispatch Age Time (sec) The maximum period of time that a process can wait in a ready-for-execution state in a dispatch queue without receiving access to a CPU. After this time, the process dispatch priority is promoted to the next-higher dispatch priority and its wait period re-initiated. A value of... Specifies... 0 that processes are not to be promoted a wait period in seconds. Main Window Menus The main window contains the following menus: File Edit View Help The following sections describe the main window menus. File Menu The File menu allows you to do the following: 228 Utilities

229 Chapter 6: Priority Scheduler (schmon, xschmon) xschmon Utility Display Priority Scheduler performance parameters Exit the program The following table describes the File menu items. Menu item... Allows you to... Monitor Activity monitor Priority Scheduler operational statistics using the Monitor Mode window shown below. The Monitor Mode window is the functional equivalent to the schmon -M command, which monitors all nodes, and the schmon -m command, which monitors the current node. The Monitor Mode window consists of the following. Window component or button Interval Repetitions Description The interval ranges from 5 to 1800 seconds. The minimum monitoring interval is 5 seconds. The display repeats for the number of repetitions. The number of repetitions must be positive. The interval cannot match the actual time between statistics collection displays due to the time required for the collection activity itself. On MPP systems, this time varies, depending on the number of nodes and speed of response. On SMP systems, this time should be insignificant. If you do not set the Repetitions field, it defaults to a value of forever. Utilities 229

230 Chapter 6: Priority Scheduler (schmon, xschmon) xschmon Utility Menu item... Allows you to... Monitor Activity (continued) Window component or button Monitoring Apply Close Undo Help Description You can toggle among the following: This node only All nodes Cancel (stops monitoring) Modifies the settings. Closes the window without changing any settings. The settings remain if the window is re-opened. Makes all edited settings revert to the last applied settings. Displays the appropriate help screen. Exit exit xschmon. Edit Menu The Edit menu allows you to set the following: Resource Partitions parameters Performance groups parameters Allocation groups parameters General Priority Scheduler parameters When using one of the edit windows to modify Priority Scheduler parameters, you can delete a Performance Group, Resource Partition, or Allocation Group by removing the entire description line. xschmon ensures that the deletion is legal and displays an error message if not. All of the Edit windows display four buttons at the bottom of the window. The following table describes each button. Button Apply Close Undo Help Description Modifies the settings. Closes the window without changing any settings. The settings remain if the window is re-opened. Makes all edited settings revert to the last applied settings. Displays the appropriate help screen. The following table describes the Edit menu items. 230 Utilities

231 Chapter 6: Priority Scheduler (schmon, xschmon) xschmon Utility Menu item... Allows you to... Resource Partition set Resource Partition parameters using the Resource Partitions window shown below. The Resource Partitions window is the functional equivalent to the schmon -b command and consists of the following. Window component... ID Name Weight Limit Specifies... identifier number of the Resource Partition. name of the Resource Partition. numeric value used to compute the percentage of resources to be assigned to this Resource Partition. optional number between 1 and 100, inclusive, that specifies a percentage limit on the total CPU usage by sessions assigned to the Performance Groups associated with the Resource Partition. None indicates that no limit is to be enforced. Utilities 231

232 Chapter 6: Priority Scheduler (schmon, xschmon) xschmon Utility Menu item... Allows you to... Performance Group set Performance Group parameters using the Performance Groups window shown below. The Performance Groups window is the functional equivalent to the schmon -p command and consists of the following. Window component... ID Name RP Type Specifies the... identifier number of the Performance Group. name of the Performance Group. Resource Partition to which this Performance Group is to be assigned. single character that indicates the milestone type used in the Performance Period definitions for that Performance Group: Q indicates that milestone units are seconds ( ) of query resource usage. Each query submitted by a session begins a new resource usage accumulation at the first Performance Period defined for the Performance Group. R or S indicates that milestone units are seconds ( ) of session resource usage. These two characters are equivalent. The R option is provided for backward compatibility with earlier software versions. T indicates milestone units as time-of-day, in military time (0-2359), optionally preceded by a day-of-week indicator. 232 Utilities

233 Chapter 6: Priority Scheduler (schmon, xschmon) xschmon Utility Menu item... Allows you to... Performance Group (continued) Window component... Limit[0] AG[0]... Limit[7] AG[7] Specifies... up to eight Performance Periods. Each limit defines a period milestone (in units defined by T in Type). The corresponding AG defines the Allocation Group in effect during that period. When milestone limits are time of day, they can contain an optional day-ofweek specification, as described in the schmon -p command. For more information, see schmon -p on page 209. Allocation Group set or display Allocation Group parameters using the Allocation Groups window shown below. The Allocation Groups window is the functional equivalent of the schmon -a command and consists of the following: Utilities 233

234 Chapter 6: Priority Scheduler (schmon, xschmon) xschmon Utility Menu item... Allows you to... Allocation Group (continued) Window component... ID Type Weight Limit Specifies... the identifier of the Allocation Group. a single character that indicates the type of scheduling set division enforced by the Allocation Group. The resources of the Allocation Group are shared equally by its scheduling sets. Permissible values for Type are as follows: N (NONE). Allocation group resources are divided among processes: For all-amp operations, each AMP counts for one process. Each step in a parallel-step plan counts for one process. Complex queries could be offered more Teradata Database system resources. S (SESSION). Resources are divided by the number of active sessions and then by processes: Each query receives the same resources no matter how many processes are involved. This is an advantage for single-amp queries if work within the Allocation Group is mixed. X (EXPEDITE). The Allocation Group is expected to process expedited work. a numeric value used to compute the percent of Resource Partition resources the processes of the Allocation Group are to receive. A percentage limit on total CPU usage by all processes controlled by this Resource Partition or the character string none. The value ranges from 1 through 100. A value of 100 indicates that no limit is to be enforced. The character string none indicates that no limit is to be enforced. If Limit is not present, any previously defined limit is removed. 234 Utilities

235 Chapter 6: Priority Scheduler (schmon, xschmon) xschmon Utility Menu item... Allows you to... Parameters modify the current Priority Scheduler Active and Aging Times, the System CPU Limit, the Dispatch Queue Age Time, the AWT Reserve and Limit values using the Set Scheduler Times window shown below. The Set Scheduler Times window is the functional equivalent of the schmon -t and -l commands and consists of the following: Parameter... Is the... Active Time (sec) Age Time (sec) System CPU Limit (%) Dispatch Queue Age Time (sec) time period during which an Allocation Group is considered active if any process assigned to the Allocation Group has been scheduled. Inactive Allocation Groups are not included in resource consumption or relative weight calculations. The range for Active Time is from seconds. The default is 61 seconds. time period over which recent resource usage by a scheduling set is measured. The range for Age Time is from seconds. The default is 60 seconds. maximum percentage limit on total CPU usage by a node. The value ranges from None indicates 100. Click the none button to set the limit to 100. time period in seconds that a process can wait in a ready-for-execution state in a dispatch queue without receiving access to a CPU. After this time, the process dispatch priority is promoted to the next-higher dispatch priority and its wait period re-initiated. The value ranges from A value of 0 indicates that processes are not to be promoted. Clicking the none button sets the value to 0. Utilities 235

236 Chapter 6: Priority Scheduler (schmon, xschmon) xschmon Utility Menu item... Allows you to... Parameters (continued) Parameter... Is the... AWT Reserve # AWT Limit # number of reserve AWT processes available for use by requests controlled by Allocation Groups having the expedite attribute. maximum number of AWT processes available for use by requests controlled by Allocation Groups having the expedite attribute. To change the current value for Active Time, Age Time, System CPU Limit, and Dispatch Queue Age Time, do the following: To drag the slider, click and hold while sliding. To increment or decrement by seconds, click the hot zone with the left mouse button. After you apply changes made in this window, the changes will appear in the Attributes window. View Menu The View menu allows you to display the current settings for the following: Resource Partitions Performance Groups Allocation Groups Session data For detailed information on each of these windows (except for Session data), see Edit Menu on page 230. The following table describes the Session Data window. 236 Utilities

237 Chapter 6: Priority Scheduler (schmon, xschmon) xschmon Utility Menu item... Allows you to... Session Data view session data using the View Session window shown below. Node Selector Category Selector The View Session window is the functional equivalent to the schmon -s command and consists of the following: Window component... Node selector scroll bar Category selector scroll bar Select All Sessions button Allows you to... view session data from the following: This Node (the node on which xschmon is running) All Nodes (in the Teradata Database system) To toggle between the options, click the up or down arrow. select from the following: Session # Resource Partition (RP) ID Performance Group (PG) ID Allocation Group (AG) ID To cycle through the options, click the up or down arrow. view data for all sessions. Utilities 237

238 Chapter 6: Priority Scheduler (schmon, xschmon) xschmon Utility Menu item... Allows you to... Session Data (continued) Window component... Text field Allows you to... enter a session number, RP, PG, or AG ID to display information about sessions controlled by that scheduler group. Session numbers are unique for each host ID. Although unlikely, duplicate session numbers might occur. Therefore, if duplicate session numbers exist, this field accepts a session number and reports data for all host IDs. Note: This field changes depending on which category you have selected. Getting Help The xschmon Help screens briefly describe each function or window. For more complete descriptions of each function or window, see schmon Utility on page 165. To display help, click the following: Help menu item in the xschmon main window Help button in any of the subwindows The xschmon Help window is shown below. 238 Utilities

239 Chapter 6: Priority Scheduler (schmon, xschmon) xschmon Utility Utilities 239

240 Chapter 6: Priority Scheduler (schmon, xschmon) xschmon Utility 240 Utilities

241 CHAPTER 7 Query Configuration (qryconfig) The Query Configuration utility, qryconfig, reports the current Teradata Database system configuration from a Teradata Database system console running the Database Window or from a host terminal. This configuration is defined using the Configuration and Reconfiguration utilities. For more information, see Configuration Utility in Utilities and Chapter 10: Reconfiguration Utility (reconfig). The Query Configuration utility is also referred to as Configuration Display. Audience Users of Query Configuration include the following: Field engineers Teradata Database system developers Teradata system engineers User Interfaces qryconfig runs on the following platforms and interfaces: Platform MP-RAS Windows Linux MVS/VM Interfaces Database Window Database Window Database Window Host Utility Console (HUTCNS) For general information on starting the utilities from different platforms and interfaces, see Appendix B: Starting the Utilities. Utilities 241

242 Chapter 7: Query Configuration (qryconfig) About Query Configuration About Query Configuration Vprocs and Physical Processors Display Options The Query Configuration utility displays configuration information about the nodes in a Teradata Database system. This utility supplies information about the PEs associated with the node and the AMPs. While physical processor identifiers are presented where appropriate in the configuration displays, the focus of the Query Configuration utility is on the vprocs managed by the node. These vprocs exist within a previously defined physical configuration. Use the Parallel Upgrade Tool (PUT) to configure parts of the physical configuration, such as creating Logical Units (LUNs) on disk arrays. See your Parallel Upgrade Tool (PUT) User Guide. The Query Configuration utility can display a variety of status and configuration information for the entire Teradata Database system or portions of the Teradata Database system including the following: Complete configuration Node, online or offline AMPs, online or offline PEs, online or offline Query Configuration Options You can display all or parts of the current Teradata Database system configuration by entering various Query Configuration options. The following sections describe the options and their use: ALL Processors Online processors Offline processors AMPs Online AMPS Offline AMPs PEs Online PEs Offline PEs 242 Utilities

243 Chapter 7: Query Configuration (qryconfig) Query Configuration Options In a large Teradata Database system configuration, use discretion when selecting the All, AMPs, and Online AMPs options, because of the potentially large numbers of output lines that may be produced. Instead of the All, AMPs, and Online AMPs options, consider Processor level options or the Offline AMPs and Offline PEs options when the configuration is large, to avoid having to deal with large numbers of Query Configuration output lines consuming valuable space and time resources. ALL Option To produce a display of all the components in the Teradata Database system and their current status, use the ALL option. The following is an example of an ALL display. Enter display option, QUIT or END to terminate. all DBS Configuration Status Report: 00/06/13 18:31:23 Vproc Node Config Config Cluster/ Vproc Node Config Config Cluster/ Number ID Type Status Host No. Number ID Type Status Host No AMP Online AMP Online AMP Online AMP Online AMP Online AMP Online AMP Online AMP Online AMP Online AMP Online AMP Online AMP Online AMP Online AMP Online AMP Online AMP Online AMP Online AMP Online AMP Online AMP Online PE Online PE Online PE Online Processors Option The information in the ALL display is ordered by vproc number. The display shows the following for each vproc: The identifier (Node ID) of the Node associated with each vproc (virtual processor). The type (AMP or PE) of each vproc. The status (online or offline) of each vproc. A status of Online means that the associated Node is available and online to the operating system. The cluster (for an AMP) or host number (for a PE) associated with each vproc. To obtain configuration information for all processors in the Teradata Database system, use the Processors option. This option produces a display identical to that produced by the ALL Option on page 243. Utilities 243

244 Chapter 7: Query Configuration (qryconfig) Query Configuration Options Online Processors or Offline Processors Options Configuration information for all online or all offline processors that is similar to that of all processors is also available. To obtain configuration information for online processors, use the Online Processors option. This option includes the same information as the all processors display option with the exception of the Status column. The following is an example of an Online Processors display. Enter display option, QUIT or END to terminate. online processors DBS Configuration Status Report: 00/06/13 18:35:56 Vproc Node Config Cluster/ Vproc Node Config Cluster/ Number ID Type HostId Number ID Type Host No AMP AMP AMP AMP AMP AMP AMP AMP AMP AMP AMP AMP AMP AMP AMP AMP AMP AMP AMP AMP PE PE PE PE 1 To obtain configuration information for offline processors, use the Offline Processors option. The information displayed is similar to that for all processors, but the Status column does not appear, since only offline processors are displayed. AMPs Option To obtain configuration information for all AMPs in the Teradata Database system, use the AMPs option. It produces a display containing AMP numbers, node identifiers, status (online or offline), and cluster numbers. The following is an example of an AMPs configuration display. Enter display option, QUIT or END to terminate. amps DBS Configuration Status Report: 00/06/13 18:38:20 Vproc Node Config Config Cluster/ Vproc Node Config Config Cluster/ Number ID Type Status Host No. Number ID Type Status Host No AMP Online AMP Online AMP Online AMP Online AMP Online AMP Online AMP Online AMP Online AMP Online AMP Online AMP Online AMP Online AMP Online AMP Online AMP Online AMP Online Utilities

245 Chapter 7: Query Configuration (qryconfig) Query Configuration Options AMP Online AMP Online AMP Online AMP Online 9 Online AMPS or Offline AMPs Options The same type of configuration information previously described for all AMPs is also available for all online or all offline AMPs. To obtain configuration information for online AMPs, use the Online AMPs option. The information displayed is similar to that for all AMPs, but the Status column does not appear, since only online AMPs are displayed. To obtain configuration information for offline AMPs, use the Offline AMPs option. The information displayed is similar to that for all AMPs, but the Status column does not appear, since only offline AMPs are displayed. PEs Option To obtain configuration information for all PEs in the Teradata Database system, use the PEs option. It produces a display containing PE numbers, node identifiers, status (online or offline), and host numbers. The following is an example of a PEs configuration display. Enter display option, QUIT or END to terminate. pes DBS Configuration Status Report: 00/06/13 18:44:20 Vproc Node Config Config Cluster/ Vproc Node Config Config Cluster/ Number ID Type Status Host No. Number ID Type Status Host No PE Online PE Online PE Online PE Online 1 Online PEs and Offline PEs Options The same type of configuration information available as described above for all PEs is also available for all online or all offline PEs. To obtain configuration information for online PEs, use the Online PEs option. The information displayed is similar to that for all PEs, but the status is Online for each PE listed. To obtain configuration information for offline PEs, use the Offline PEs option. The information displayed is similar to that for all PEs, but the status is Offline for each PE listed. Utilities 245

246 Chapter 7: Query Configuration (qryconfig) Query Configuration Options Getting HELP To produce a list of all of the Query Configuration options, type HELP or question mark (?). The list of options appears as follows: Enter display option, QUIT or END to terminate. help The following key words return the indicated display. All; - complete configuration. Processors; - processor status. Online Processors; - online processors. Offline Processors; - offline processors. AMPs; - AMP status. Online AMPs; - online AMPs. Offline AMPs; - offline AMPs. PEs; - PE status. Online PEs; - online PEs. Offline PEs; - offline PEs. As indicated in the HELP option list, type a keyword to produce the desired display. 246 Utilities

247 CHAPTER 8 Query Session (qrysessn) The Query Session utility, qrysessn, provides information about active Teradata Database sessions. It allows you to monitor the state of all or selected database sessions on all or selected logical host IDs attached to the Teradata Database. Query Session is also known as Session States. This chapter provides an overview of the information Query Session reports as well as several sample Query Session displays. Because the Query Session displays for sessions involved in Archive and Recovery, FastLoad, MultiLoad (MLOAD), and FastExport operations are different from other session displays, these displays are described at the end of this chapter. Audience Users of Query Session include the following: Teradata Database operators Teradata Database system administrators Teradata Database system programmers User Interfaces qrysessn runs on the following platforms and interfaces: Platform MP-RAS Windows Linux MVS/VM Interfaces Database Window Database Window Database Window Host Utility Console (HUTCNS) For general information on starting the utilities from different platforms and interfaces, see Appendix B: Starting the Utilities. Utilities 247

248 Chapter 8: Query Session (qrysessn) Query Session States Query Session States Query Session provides information on the following possible states of a session. The Session State... Indicates that... ABORTING ACTIVE BLOCKED DELAYED IDLE INDOUBT INDOUBT PARSING PARSING QTDELAYED QUIESCED ABORT QUIESCED ABORT WITH LOGOFF QUIESCED INDOUBT RESPONSE SESDELAYED the session is aborting its latest request. the session has sent steps to the dispatcher and possibly to one or more AMP vprocs. an active session is waiting for a database lock to be released. the session is being delayed because query limit, imposed by a Teradata Dynamic Workload Manager throttle rule, has been met. the Teradata Database system recognizes a session, but no processing is taking place. a two-phase commit session is in doubt. a two-phase commit session is in doubt and is parsing a vote or commit request. the session is active in the Teradata SQL parser phase, before the steps are dispatched to the AMP vprocs. the session is waiting for rows to be inserted into a queue table. the session is blocked from executing further requests because transactions associated with this session are being aborted. the session is quiesced because the transactions or requests associated with this session are being aborted, after which this session will be logged off the machine. the session is blocked from exercising further requests because the outstanding transaction/request will be terminated. a response to a session request is in process. the session is being delayed because a utility limit, imposed by a Teradata Dynamic Workload Manager throttle rule, has been met. Parent and Child Sessions When a connected session is part of either a FastLoad, MultiLoad, FastExport, or Archive and Recovery operation, that session establishes subordinate sessions to accomplish the task more quickly. The originating session is then called a Parent session; the subordinate sessions are called Child sessions that belong to that Parent. A Child session is not recognized as such, and its activity is not reported until it has transmitted at least one request to the AMPs in the current transaction. 248 Utilities

249 Chapter 8: Query Session (qrysessn) Query Session Displays Information about the activity of Child sessions is available to Query Session when the Parent session is in the Active state or when one of several inactive states described later in this chapter. In FastLoad operations, child sessions are reported only while the Parent session is in the loading phase. In MultiLoad operations, Child sessions are reported only while the Parent session is in the acquisition phase. Query Session reports the status of Child sessions when you request detail information. Query Session Displays The following sections describe the Query Session displays that provide information on what you can input. General Help displays are described first, followed by displays for sessions involved in Archive and Recovery, FastLoad, FastExport, and MultiLoad operations. After you have started Query Session, it prompts for the following: Please Enter A Logical Host ID (? For Help) You can type any of the following responses when you are prompted for the logical host ID. IF you type... an integer an asterisk (*) a question mark (?) a carriage return (Enter) THEN... Query Session provides information only for the sessions associated with the specified logical host ID. Query Session provides information on sessions for every logical host. you will get Help for this entry. you will exit from the Query Session utility. If you type an integer or an asterisk, the following prompt displays: Please Enter Session Ids (? For Help): You can input any of the following when you are prompted for the Session ID. Utilities 249

250 Chapter 8: Query Session (qrysessn) Query Session Displays IF you type... THEN you see... an integer to indicate a specific session ID Note: You can input up to five session Ids in integer format. You can type them on one line separated by spaces or on multiple lines. the following prompt: Is detail information needed if the session is involved in HUT/FastLoad/MLoad/Export? y-yes, n-no IF... THEN type... you want to view the Child session states. the session is not part of a FastLoad, MultiLoad, FastExport, or an Archive and Recovery operation. y n an asterisk (*) the following prompt: Is detail information needed if the session is involved in HUT/FastLoad/MLoad/Export? y-yes, n-no IF... you want to view the Child session states. the session is not part of a FastLoad, MultiLoad, FastExport, or an Archive and Recovery operation. THEN type... y n a question mark help concerning input information. Note: If an unsuccessful attempt was made to obtain temporary table information for the given session, the following query session message could appear: WARNING: Session may contain incomplete temporary table information due to deadlock! If temporary table information is important to you, then you should retry querying the session at a later time. 250 Utilities

251 Chapter 8: Query Session (qrysessn) Session State Display Session State Display The session state display consists of session identifier information and session state details. Displays for sessions involved in FastLoad, MultiLoad, FastExport, or Archive and Recovery operations provide additional information described later in this chapter. If a session is idle, only the session identifier information is displayed, as shown below. Host Session PE DBC User ID DBC The columns for the Session Identifier display the following information. The column named... Contains the... Host Session PE DBC User ID logical host identifier. session identifier. PE number of the PE to which the session is assigned. user assigned to the session. If a session is active, and not part of a FastLoad, MultiLoad, FastExport, or Archive and Recovery operation, the following session state detail information displays. Session State Query Results : 00/06/15 14:14:13 Host Session PE DBC User ID DBC State Details : ACTIVE Statements Dispatched Time CPU Usage Accesses :22: Session State Details During Stored Procedure Execution If a stored procedure is being executed, the following session state information is displayed. Session State Query Results : 00/06/15 13:14:13 Host Session PE DBC User ID DBC State Details : ACTIVE (Stored Procedure is executing) The State Details correspond to the latest SQL request that the stored procedure executed. Utilities 251

252 Chapter 8: Query Session (qrysessn) State Information Displays Session State Details Pertaining to the Teradata Index Wizard Query Session reports the index analysis state pertaining to the Teradata Index Wizard. If a workload is being analyzed for indexes, the following session state information is displayed. Session State Query Results : 02/04/15 12:22:03 Host Session PE DBC User ID USER1 State Details: <status> Analyzing a workload for index recommendations. State Information Displays ABORTING State This following sections provide session information for each possible state: ABORTING ACTIVE BLOCKED DELAYED IDLE INDOUBT INDOUBT PARSING PARSING QTDELAYED QUIESCED ABORT QUIESCED ABORT WITH LOGOFF QUIESCED INDOUBT RESPONSE SESDELAYED The ABORTING state indicates that the session is aborting its latest request. The ABORTING state display is shown below. State Details : ABORTING Statements Code Time CPU Usage Accesses :22: Utilities

253 Chapter 8: Query Session (qrysessn) State Information Displays The columns on the ABORTING state display provide the following information. The column named... Contains the... Statements Code Time CPU Usage Accesses statements, up to the number displayed, that are aborting. error that caused the abort. time that the abort step was sent to the AMP. accumulated time in thousandths of a second that all AMPs spent processing the current request. total number of segment access calls executed on all AMPs for the session request. ACTIVE State The ACTIVE state indicates that the session has sent steps to the dispatcher and possibly to one or more AMP vprocs. The ACTIVE state display for a session not part of a FastLoad, MultiLoad, FastExport or Archive and Recovery operation is shown below. State Details : ACTIVE Statements Dispatched Time CPU Usage Accesses :22: The columns on the ACTIVE state display provide the following information. The column named... Contains the... Statements Dispatched Time CPU Usage Accesses total number of statements in the current session request. highest statement number dispatched to the AMPs. time that the last step in the highest statement number was sent to the AMPs. accumulated time in thousandths of a second that all AMPs spent processing the current request. total number of segment access calls executed on all AMPs for the session request. Utilities 253

254 Chapter 8: Query Session (qrysessn) State Information Displays BLOCKED State The BLOCKED state indicates that an active session is waiting for a database lock to be released. The BLOCKED state display for a session is shown below. State Details : BLOCKED Resource X.T Statement AMPs Mode AMP Vproc HUT READ 19 NO The columns on the BLOCKED state display provide the following information. The column named... Contains the... Resource database or table for which the lock is requested. IF the lock is requested for a... THEN this column displays the information... database table or row X.* where: X is the database name. X.T where: X is the database name, and T is the table name. Statement AMPs Mode AMP Vproc HUT highest statement number for which steps have been dispatched to the AMPs. number of AMPs for which the session is waiting to acquire a lock. type of lock requested by the session. number of the AMP with the blocked session. host utility lock (if encountered). DELAYED State The DELAYED state indicates that an SQL request is delayed because a query limit has been exceeded. When the limit is no longer exceeded, the delayed requests are processed. Teradata Dynamic Workload Manager (Teradata DWM) allows you to define and manage throttle rules, which restrict the number of requests that can be simultaneously executed against Teradata Database. These rules delay or reject database requests based on specified 254 Utilities

255 Chapter 8: Query Session (qrysessn) State Information Displays conditions, such as the number of concurrent queries or the duration of queries. A delayed request is allowed to proceed when one of the following occurs: The rule s limit is no longer exceeded. The Teradata DWM administrator explicitly releases the request. The DELAYED state display for a session is shown below. State Details : DELAYED For information on Teradata DWM, refer to Teradata Dynamic Workload Manager User Guide. IDLE State The IDLE state indicates that the Teradata Database system recognizes a session, but no processing is taking place. The IDLE state display for a session is shown below. State Details : IDLE INDOUBT State The INDOUBT state indicates that a two-phase commit session is in doubt. This state continues until an abort or commit is received from the host application. The INDOUBT state display for a session is shown below. State Details : INDOUBT INDOUBT PARSING State The INDOUBT PARSING state indicates that a two-phase commit session is in doubt and is parsing a vote or commit request. The INDOUBT PARSING state display for a session is shown below. State Details : INDOUBT PARSING PARSING State The PARSING state indicates that the session is active in the Teradata SQL parser phase, before the steps are dispatched to the AMP vprocs. The PARSING state displays no column information and only the word PARSING. The PARSING state for a session display is shown below. State Details : PARSING QTDELAYED State The QTDELAYED state indicates that a session is waiting for rows to be inserted into a queue table. The QTDELAYED state is limited to 20% of the total possible sessions, which is 120 x the number of PEs. If the 20% limit is exceeded, then error message 3128 appears: 3128 Transaction aborted due to exceeding the maximum consume statement limit. Utilities 255

256 Chapter 8: Query Session (qrysessn) State Information Displays QUIESCED ABORT State You must decrease the number of sessions consuming queue table rows. For detailed information on error message 3128, refer to Messages. The QTDELAYED state display for a session is shown below. State Details : QTDELAYED The QUIESCED ABORT state indicates that the session is blocked from executing further requests because transactions associated with this session are being aborted. The outstanding transaction or request will be aborted by the performance monitor. The QUIESCED ABORT state for a session display is shown below. State Details : QUIESCED ABORT QUIESCED ABORT WITH LOGOFF State The QUIESCED ABORT WITH LOGOFF state indicates that the session is quiesced because the transactions or requests associated with this session are being aborted by the Teradata Database system or the performance monitor. The session is logged off. QUIESCED INDOUBT State RESPONSE State The QUIESCED ABORT WITH LOGOFF state for a session display is shown below. State Details : QUIESCED ABORT WITH LOGOFF The QUIESCED INDOUBT state indicates that the session is blocked from exercising further requests because the outstanding transaction/request will be terminated by the resolver base module. The QUIESCED INDOUBT state for a session display is shown below. State Details : QUIESCED INDOUBT The RESPONSE state indicates a response to a session request is in process. The RESPONSE state for a session display is shown below. State Details : RESPONSE Statements This column for the RESPONSE display contains the following information. The column named... Contains the... Statements highest statement number for which a response has been returned to the host or the stored procedure in execution. 256 Utilities

257 Chapter 8: Query Session (qrysessn) Archive and Recovery Sessions State Displays SESDELAYED State The SESDELAYED state indicates that a session is delayed because a utility limit has been exceeded. The utilities that can be limited are FastLoad, MultiLoad, FastExport, and ARC. When the limit is no longer exceeded, the delayed requests are processed. Teradata Dynamic Workload Manager (Teradata DWM) allows you to define and manage throttle rules, which restrict the type and number of utilities that are allowed to run concurrently. The SESDELAYED state display for a session is shown below. State Details : SESDELAYED For more information on Teradata DWM, see Teradata Dynamic Workload Manager User Guide. Archive and Recovery Sessions State Displays Several displays for sessions are part of the Archive and Recovery operations. If you request detail information, Query Session reports child sessions and the parent information. The following sections describe these displays: Active Parent Session with Regular Request Active Parent Session with Directed Request Inactive Parent Session Child Session Active Parent Session with Regular Request Display The following shows an example display for a parent session involved in an Archive and Recovery operation. State Details : Active Parent Session with regular request involved in HUT. Operation: Restore Statements Dispatched Time CPU Usage Accesses Byte Count :22: ,367 The Active State Display for a parent session involved in processing an Archive and Recovery request contains the following information. The column named... Contains the... Statements Dispatched total number of statements in the current session request. highest statement number dispatched to the AMPs. Utilities 257

258 Chapter 8: Query Session (qrysessn) Archive and Recovery Sessions State Displays The column named... Contains the... Time CPU Usage Accesses Byte Count time that the last step for the highest statement number was sent to the AMPs. accumulated time in thousandths of a second that all AMPs spent processing the current request. total number of segment access calls executed on all AMPs for the session request. total number of bytes accessed by the Archive and Recovery operation. Active Parent Session with Directed Request Display The following shows an example display for a parent session involved in an Archive and Recovery operation processing a directed request. State Details : Active Parent Session with directed request involved in HUT. Request # Operation Time CPU Usage Accesses Byte Count Restore 14:22: ,234 The directed request active state display for a parent session involved in processing an Archive and Recovery request contains the following information. The column named... Contains the... Request # Operation Time CPU Usage Accesses Byte Count number of the request. type of operation being performed. time that the last step for the highest statement was sent to the AMPs. accumulated time in thousandths of a second that all AMPs spent processing the current request. total number of segment access calls executed on all AMPs for the session request. total number of bytes accessed by the Archive and Recovery operation. Inactive Parent Session Display The following shows an example display for an inactive parent session involved in an Archive and Recovery operation. State Details : Inactive Parent Session involved in HUT. Operation CPU Usage Accesses Byte Count Utilities

259 Chapter 8: Query Session (qrysessn) FastLoad Sessions State Displays Restore 1,234 9,543 1,259,234 The inactive state display for a parent session involved in processing an Archive and Recovery request contains the following information. The column named... Contains the... Operation CPU Usage Accesses Byte Count type of operation being performed. accumulated time in thousandths of a second that all AMPs spent processing the current request. total number of segment access calls executed on all AMPs for the session request. total number of bytes accessed by the Archive and Recovery operation. Child Session Display The following shows an example display for child sessions involved in an Archive and Recovery operation. Session # Request # State TimeStamp Byte Count Inactive 17:57:21 1, Active 17:57: Inactive 17:57:41 3,024 Child sessions involved in Archive and Recovery operations display these columns. The column named... Contains the... Session # Request # State TimeStamp Byte Count session identifier. number of the request. state of the session, indicating whether the session is active or inactive. time that is updated whenever a request is received from the host, a request is re-initiated to another AMP, or a response is sent to the host. total number of bytes accessed by the session. FastLoad Sessions State Displays Several displays for sessions are part of FastLoad operations. The following sections describe those displays: Utilities 259

260 Chapter 8: Query Session (qrysessn) FastLoad Sessions State Displays Active Parent Session in a Loading Phase Active Parent Session in a Nonloading Phase Inactive Parent Session in a Loading Phase Inactive Parent Session in a Nonloading Phase Child Sessions If you request detail information, Query Session reports child sessions as well. These displays are identified after the phrase State Details by two lines describing the current phase. Information for a FastLoad session in the loading phase is different from information for a non-loading phase of FastLoad. Active Parent Session in a Loading Phase Display The following example shows a display of an active parent session for a FastLoad operation in the loading phase. State Details : Active Parent Session involved in FASTLOAD utility FastLoad Phase : Loading Statements Dispatched Time CPU Usage Accesses Row Count :22:09 15,110 6,462 2,060 The display for an active parent session in the loading phase of a FastLoad operation contains the following information. The column named... Contains the... Statements Dispatched Time CPU Usage Accesses Row Count total number of statements in the current session request. highest statement number dispatched to the AMPs. time that the last step for the highest statement number was sent to the AMPs. accumulated time in thousandths of a second that all AMPs spent processing the current request. total number of segment access calls executed on all AMPs for the session request. total number of rows loaded by the FastLoad utility. Active Parent Session in a Nonloading Phase Display The following shows an example display of an active parent session of a FastLoad operation in any phase other than the loading phase. State Details : Active Parent Session involved in FASTLOAD utility FastLoad Phase : LoadPending 260 Utilities

261 Chapter 8: Query Session (qrysessn) FastLoad Sessions State Displays Statements Dispatched Time CPU Usage Accesses :22: The display for an active parent session in any phase other than the loading phase of a FastLoad operation contains the following information. The column named... Contains the... Statements Dispatched Time CPU Usage Accesses total number of statements in the current session request. highest statement number dispatched to the AMPs. time that the last step for the highest statement number was sent to the AMPs. accumulated time in thousandths of a second that all AMPs spent processing the current request. total number of segment access calls executed on all AMPs for the session request. Inactive Parent Session in a Loading Phase Display The following shows an example display of an inactive parent session of a FastLoad operation in the loading phase. State Details : Inactive Parent Session involved in FASTLOAD utility FastLoad Phase : Loading CPU Usage Accesses Row Count ,321 The display for an inactive parent session in the loading phase of a FastLoad operation contains the following information. The column named... Contains the... CPU Usage Accesses Row Count accumulated time in thousandths of a second that all AMPs spent processing the current request. total number of segment access calls executed on all AMPs for the session request. total number of rows loaded by the FastLoad utility. Inactive Parent Session in a Nonloading Phase Display The following shows an example display of an inactive parent session involved in a FastLoad operation in any phase other than the loading phase. State Details : Inactive Parent Session involved in FASTLOAD utility. FastLoad Phase : Load Pending Utilities 261

262 Chapter 8: Query Session (qrysessn) FastLoad Sessions State Displays CPU Usage Accesses The inactive parent session display for sessions involved in any phase other than the loading phase contains the following information. The column named... Contains the... CPU Usage Accesses accumulated time in thousandths of a second that all AMPs spent processing the current request. total number of segment access calls executed on all AMPs for the session request. Child Sessions Display A FastLoad operation only involves child sessions when in the loading phase. If the parent of the queried child session is not in the loading phase, the child session information is not available. The following shows an example display for child sessions involved in a FastLoad operation when the long form of the display is requested in response to the Detail Information Needed prompt. Session # Request # State TimeStamp Byte Count Inactive 15:57:10 5, Active 15:57: The display for Child sessions involved in FastLoad operations contain the following information. The column named... Contains the... Sessions# Request # State TimeStamp Row Count session identifier. number of the request. state of the session, indicating whether the session is active or inactive. time that is updated whenever a request is received from the host, a request is reinitiated to another AMP, or a response is sent to a host. total number of rows loaded by the session. 262 Utilities

263 Chapter 8: Query Session (qrysessn) MultiLoad Sessions State Displays MultiLoad Sessions State Displays Several displays are defined for the sessions that are part of MultiLoad operations. The following sections describe those displays: Preliminary Phase Sessions Application Phase Session for Apply Task Application Phase Session for Delete Task Active Parent Session in an Acquisition Phase Inactive Parent Session in an Acquisition Phase Child Session in an Acquisition Phase In addition to the phase State Detail line, a line describing the current phase is displayed. If the session is in the Preliminary or Application phase, the current task type (Delete or Apply) is displayed. The information displayed is different for each phase: Preliminary, Application, and Acquisition. In the Application phase, each of the two task types is displayed. When the action involves more than one AMP, row count summaries are meaningless and are not reported. Preliminary Phase Session Display The following shows an example display session, that is part of a MultiLoad operation, in the Preliminary phase. State Details : Session involved in MLOAD utility MLoad Phase : Preliminary - Received all DML Steps. Task Running : Apply Task Statements Dispatched Time CPU Usage Accesses DMLCount :09: The possible tasks include Apply Task and Delete Task. These are the Subphases: No MLOAD step has been received. Receiving MLOAD step. Received all MLOAD steps. Received all DML (Data Manipulation Language) steps. The state display for the preliminary phase of a MultiLoad operation contains the following information. The column named... Contains the... Statements Dispatched total number of statements in the current session request. highest statement number dispatched to the AMPs. Utilities 263

264 Chapter 8: Query Session (qrysessn) MultiLoad Sessions State Displays The column named... Contains the... Time CPU Usage Accesses DML Count time that the last step for the highest statement number was sent to the AMPs. accumulated time in thousandths of a second that all AMPs spent processing the current request. total number of segment access calls executed on all AMPs for the session request. number of DML steps received if the current phase is Received all DML Steps. Application Phase Session for Apply Task Display The Query Session display for each table during an Apply Task includes the name of the database and table, the current action, the number of workrows applied, and the total number of workrows. The following shows an example display session involved in a MultiLoad operation during an Apply Task. State Details : Session involved in MLOAD utility MLoad Phase : Application. Task Running : Apply Task Statements Dispatched Time CPU Usage Accesses :09: ,637 DataBase.Table = SPOOL_RES.WT_TDEM_PAIMT_MED Action = Process Data and Secondary index # of WorkRows applied = 1,210,838 Total # of WorkRows = 51,639,908 # of NUSI change rows applied = 0 Total # of NUSI change rows = 0 The display for active parent sessions involved in the Apply Task of a MultiLoad operation provides the following information. The column named... Contains the... Statements Dispatched Time CPU Usage Accesses total number of statements in the current session request. highest statement number dispatched to the AMPs. time that the last step for the highest statement number was sent to the AMPs. accumulated time in thousandths of a second that all AMPs spent processing the current request. total number of segment access calls executed on all AMPs for the session request. 264 Utilities

265 Chapter 8: Query Session (qrysessn) MultiLoad Sessions State Displays In addition, the display provides the following information. Field DataBase.Table Action Description Identifies the table on which the MultiLoad operation is running. Describes the action being performed in the MultiLoad session. # of WorkRows applied Displays the number of work rows processed in the apply phase. Total # of WorkRows # of NUSI change rows applied Total # of NUSI change rows Displays the total number of rows processed. Number of nonunique secondary index rows processed in the apply phase. Total number of nonunique secondary index rows processed. Application Phase Session for Delete Task Display The following shows an example of the Query Session display for each table during a Delete Task, which includes the name of the database and table, the current action, the number of rows scanned, and the number of rows deleted. State Details : Session involved in MLOAD utility MLoad Phase : Application. Task Running : Delete Task Statements Dispatched Time CPU Usage Accesses :24: ,987 DataBase.Table = SPOOL_RES.WT_TDEM_PAIMT_MED Action = Process Data # of rows scanned = 22,357 # of rows deleted = 245,349 Note: The values shown include both the primary and the fallback count. The Delete Task display for a MultiLoad operation contains the same information as described for the Apply Task display except that it reports the number of rows processed and deleted rather than the rows processed by the apply phase. Active Parent Session in an Acquisition Phase Display The following shows an example display of an active parent session which is part of a MultiLoad operation. State Details : Active Parent Session involved in MLOAD utility MLoad Phase : Acquisition - Data Loading is in progress. Statements Dispatched Time CPU Usage Accesses Row Count :23: ,854 Utilities 265

266 Chapter 8: Query Session (qrysessn) MultiLoad Sessions State Displays If you request detail information, Query Session reports child sessions as well. These are the descriptions of the phase: Data Loading is in progress. Data Loading is complete. The display for active parent sessions involved in MultiLoad operations provides the following information. The column named... Contains the... Statements Dispatched Time CPU Usage Accesses Row Count total number of statements in the current session request. highest statement number dispatched to the AMPs. time that the last step for the highest statement number was sent to the AMPs. accumulated time in thousandths of a second that all AMPs spent processing the current request. total number of segment access calls executed on all AMPs for the session request. total number of rows processed by the MultiLoad task. Inactive Parent Session in an Acquisition Phase Display The following shows an example display of an inactive parent session that is part of a MultiLoad operation. State Details: InActive Parent Session involved in MLOAD Utility MLoad Phase : Acquisition - Data Loading is complete. CPU Usage Accesses Row Count ,673 These are the possible descriptions of the phase: Data Loading is in progress. Data Loading is complete. The display for inactive parent sessions involved in a MultiLoad operation contains the following information. The column named... Contains the... CPU Usage Accesses Row Count accumulated time in thousandths of a second that all AMPs spent processing the current request. total number of segment access calls executed on all AMPs for the session request. total number of rows processed by the MultiLoad task. 266 Utilities

267 Chapter 8: Query Session (qrysessn) FastExport Sessions State Displays Child Session in an Acquisition Phase Display The following shows an example display for child sessions involved in a MultiLoad operation when the long form of the display is requested in response to the Detail Information Needed prompt. State Details: CHILD session involved in MLOAD Acquisition Phase Session # Request # State TimeStamp Row Count Inactive 15:57:10 5, Active 15:57: Child sessions involved in MultiLoad operations display these columns. The column named... Contains the... Session # Request # State TimeStamp Row Count session identifier. number of the request. state of the session, indicating whether the session is active or inactive. time that is updated whenever a request is received from the host, a request is reinitiated to another AMP, or a response is sent to the host. total number of rows loaded by the session. FastExport Sessions State Displays FastExport of data includes sessions under which Teradata SQL statements are executed, as well as sessions used to transfer response data to the host. The Teradata SQL session assumes one of five sequential states: Executing the select Releasing resource locks Vertical data redistribution Horizontal data redistribution Inactive Vertical data redistribution and horizontal data redistribution are processes executed to prepare the response data from a SELECT request for transfer back to the host. Vertical redistribution occurs only if the SELECT contains an ORDER BY clause. The idle state occurs before the select request is transmitted to the Teradata Database system, or while the FastExport sessions are transmitting data to the host. FastExport sessions are children of the Teradata SQL session that executes the select request. A child session exists in one of two states. A child session in the inactive state means that either Utilities 267

268 Chapter 8: Query Session (qrysessn) FastExport Sessions State Displays the select has not completed, or that the host utility has not yet issued a request for this child session in returning response data. A child session in the active state is currently transmitting response data. Like FastLoad and MultiLoad, the FastExport utility executes bulk activities. The Teradata Database system limits the maximum number of load operations (that is, FastExport, FastLoad, or MultiLoad) to the number specified in DBS Control field MaxLoadTasks. Examples of Teradata SQL sessions involved in FastExport activity and examples of the output for a FastExport session are shown in the following sections. Teradata SQL Session - Releasing Locks The following shows an example display of a single FastExport Teradata SQL session in release locks state. Session State Query Results : 00/06/14 18:35:54 Host Session PE DBC User ID DBC State Details : Active PARENT session involved in FastExport FastExport Phase : Vertical redistribution. Statements Dispatched Time CPU Usage Accesses :35: ,922 Detail information for CHILDREN sessions in FastExport Util. Session # Request # State Inactive Inactive Inactive Inactive Teradata SQL Session - Vertical Redistribution The following shows an example display of the Teradata SQL session in the vertical redistribution state. The select request consists of a single SELECT statement. Session State Query Results : 00/06/13 18:38:59 Host Session PE DBC User ID DBC State Details : Active PARENT session involved in FastExport FastExport Phase : Vertical redistribution. Statements Dispatched Time CPU Usage Accesses :37: , Utilities

269 Chapter 8: Query Session (qrysessn) FastExport Sessions State Displays Detail information for CHILDREN sessions in FastExport Util. Session # Request # State Inactive Inactive Inactive Inactive The following example shows that the Teradata Database system continues to process the vertical redistribution phase. Session State Query Results : 00/06/12 18:38:59 Host Session PE DBC User ID DBC State Details : Active PARENT session involved in FastExport FastExport Phase : Horizontal redistribution. Statements Dispatched Time CPU Usage Accesses :42: ,314 Detail information for CHILDREN sessions in FastExport Util. Session # Request # State Inactive Inactive Inactive Inactive The CPU Usage and the Accesses counts have increased, indicating the Teradata Database system is in operation. Teradata SQL Session - Horizontal Redistribution With the Teradata SQL session in the horizontal redistribution state, the display might take the form shown in the following example. Session State Query Results : 00/06/09 18:43:41 Host Session PE DBC User ID DBC State Details : Active PARENT session involved in FastExport FastExport Phase : Horizontal redistribution. Statements Dispatched Time CPU Usage Accesses :42: ,305 Utilities 269

270 Chapter 8: Query Session (qrysessn) FastExport Sessions State Displays Detail information for CHILDREN sessions in FastExport Util. Session # Request # State Inactive Inactive Inactive Inactive FastExport Session - Inactive The following example shows that the FastExport session is inactive, waiting for the select to complete. Session State Query Results : 00/06/08 18:39:28 Host Session PE DBC User ID N/A DBC State Details : Child Session involved in FastExport Utility FastExport Phase : Returning data. Request # State Parent Session Inactive 1069 FastExport Session - Data Transmission The following example shows FastExport returning data. This child session has returned one data block to the host for the first SELECT statement, where the response data contains 69 blocks. Session State Query Results : 00/06/07 18:49:09 Host Session PE DBC User ID N/A DBC State Details : Child Session involved in FastExport Utility FastExport Phase : Returning data. Request # State Statement Blocks Returned Total Block Active FastExport transmission continues. As shown in the following example, the session has returned four data blocks to the host. In this way, the user is able to monitor the progress of the data transmission phase. Session State Query Results : 00/06/06 18:50:52 Host Session PE DBC User ID DBC 270 Utilities

271 Chapter 8: Query Session (qrysessn) FastExport Sessions State Displays State Details : Child Session involved in FastExport Utility FastExport Phase : Returning data. Request # State Statement Blocks Returned Total Block Active Utilities 271

272 Chapter 8: Query Session (qrysessn) FastExport Sessions State Displays 272 Utilities

273 CHAPTER 9 Reconfiguration Estimator (reconfig_estimator) The Reconfiguration Estimator utility, reconfig_estimator, estimates an elapsed time for reconfiguration based upon the number and size of tables on your current Teradata Database system. The Reconfiguration Estimator prompts you for information about the planned upgrade and provides estimates for the following phases: Redistribution Deletion NUSI building Run the Reconfiguration Estimator utility before running the Reconfiguration utility, described in Chapter 10: Reconfiguration Utility (reconfig). Audience Users of Reconfiguration Estimator include the following: Teradata Database system engineers Field engineers Teradata Database system developers User Interfaces reconfig_estimator runs on the following platforms and interfaces: Platform MP-RAS Windows Linux Interfaces Database Window Database Window Database Window Note: After it has been started, Reconfiguration Estimator must be allowed to run to completion. It cannot be stopped using the Database Window stop command. For general information on starting the utilities from different platforms and interfaces, see Appendix B: Starting the Utilities. Utilities 273

274 Chapter 9: Reconfiguration Estimator (reconfig_estimator) User Interfaces Example The following is sample output from Reconfiguration Estimator. The current configuration has: 1 Nodes with 2 AMPs The new configuration will be: 1 Nodes with 4 AMPs The "my.sql" file shows: 105 tables using 3GB of data. The estimated table redistribution time will be: 10 hours and 54 minutes. The estimated table deletion time will be: 7 hours and 8 minutes. The total estimated reconfig time will be: 18 hours and 12 minutes. 274 Utilities

275 CHAPTER 10 Reconfiguration Utility (reconfig) The Reconfiguration and Configuration utilities are used to define the AMPs and PEs that operate together as a Teradata Database. (Configuration is described in an earlier chapter of this manual.) Reconfiguration is the second step of the configuration and reconfiguration process that defines or modifies a Teradata Database system. Reconfiguration implements the Teradata Database system that is described in the new configuration map created in a previous Configuration utility session. The Reconfiguration utility is most often used when adding nodes to an existing configuration. In addition, use the Reconfiguration utility to change the following: Relationships of AMP and PE vprocs to nodes Clustering of AMP vprocs Audience Users of Reconfiguration include the following: Teradata Database system engineers Field engineers Teradata Database system developers User Interfaces reconfig runs on the following platforms and interfaces: Platform MP-RAS Windows Linux Interfaces Database Window Database Window Database Window For general information on starting the utilities from different platforms and interfaces, see Appendix B: Starting the Utilities. Utilities 275

276 Chapter 10: Reconfiguration Utility (reconfig) Before Starting Before Starting Before starting Reconfiguration, verify the following: Hardware is in place, properly configured, and online. Hardware configuration is detailed in the hardware service manuals for your Teradata Database system. Use the Vproc Manager utility to ensure all AMP-to-PE vprocs are online and ready. For more information, see Vproc Manager Utility in Utilities. Run the CheckTable utility CHECK command at the PENDINGOP level to verify that no tables are in pending status. The command is as follows: CHECK ALL TABLES AT LEVEL PENDINGOP SKIPLOCKS PRIORITY = H; Note: Do not use the CHECK command with the PARALLEL option when using the PENDINGOP option and with users logged on. A hang will occur. For more information, see CheckTable Utility in Utilities. Logons are disabled, and the Teradata Database system is in a quiescent state. Online archive logging is not enabled for any database object. Reconfig will not run if online archive logging is enabled. Use the LOGGING ONLINE ARCHIVE OFF statement to turn off logging. You must specify the name of the database or the names of the tables for which logging is enabled. For more information, see SQL Reference: Data Definition Statements. Disabling Logons To disable logons and place the Teradata Database system into a quiescent state, do the following: In the Database Window Supervisor tab or supv window, type: DISABLE LOGONS This command denies user access to the Teradata Database system by disabling logons. The following message appears: Logons disabled. Note: After you exit Reconfiguration, you must enable logons. Enabling Logons After Reconfiguration has completed, you must enable logons. To enable the logons, do the following: Type the following at the command input line and press Enter: ENABLE LOGONS 276 Utilities

277 Chapter 10: Reconfiguration Utility (reconfig) About Reconfiguration About Reconfiguration Typically, you use Reconfiguration to alter the number of AMPs in a Teradata Database system. The new configuration map includes the status of each AMP in a Teradata Database system. AMP status in a new configuration map is shown in the following table. AMP Status... Means that the AMP... Add ChgClust Delete Online is new and is to be added to the current configuration. cluster assignment was modified. is to be deleted from the current configuration. has not been modified. Vprocs Virtual processors (vprocs) are instances of AMP or PE software within the Teradata Database system. Vprocs allow the Teradata Database system to execute multiple instances of AMP or PE software, each instance behaving as though executing in a dedicated processor. Physical Processors The Configuration and Reconfiguration utilities are not responsible for the maintenance of the physical environment in which the Teradata Database system configuration is defined. The AMPs and PEs exist within a previously defined physical configuration. Use the Parallel Upgrade Tool (PUT) to configure parts of the physical configuration, such as creating Logical Units (LUNs) on disk arrays. See your Parallel Upgrade Tool (PUT) User Guide. Configuration Utility Activities Warning: When changing cluster assignments without adding AMPs, ample disk space must be available on all AMPs. If ample space is not available, the Teradata Database system stops. To recover, SYSINIT the Teradata Database system, which results in loss of data. Teradata recommends that currentperm space should be less than 53% of the total maxperm space before starting a change of clusters without adding AMPs. When the Teradata Database system is initialized, System Initializer (SysInit) procedures build a default configuration map that describes the one target AMP involved in SysInit. This configuration is stored in both the current and new configuration maps. When the Teradata Database system is operational, you use Configuration to describe the complete Teradata Database system in the new configuration map area. As the Teradata Database system grows and changes, use Configuration to revise the new configuration map to reflect the following types of changes to the Teradata Database system: Addition and deletion of vprocs and hosts Utilities 277

278 Chapter 10: Reconfiguration Utility (reconfig) About Reconfiguration New Configuration Map Changes to cluster assignments Use the configuration maps to perform these tasks: Store the identification and status of each vproc in the Teradata Database system Identify the AMPs that comprise each AMP cluster Identify each PE and its associated host The Teradata Database system contains these two configuration maps: The current configuration map, which describes the current arrangement and status of vprocs in the Teradata Database system The new configuration map, which includes changes and additions to the configuration The new configuration map serves as input to Reconfiguration. Reconfiguration Utility Activities After Configuration builds a new configuration map, Reconfiguration redefines the Teradata Database system configuration according to the new map. Reconfiguration copies the new configuration map to the current configuration map on each node. MOVE AMP Operation During reconfiguration, data is redistributed among AMPs, if AMPs were added or deleted, or if cluster assignments were changed. Redistribution causes hash bucket assignments to be recalculated. These assignments describe the AMPs responsible for primary data and the AMPs responsible for fallback data. Hash bucket arrays contain hash bucket assignments for each AMP: Primary data rows for the current configuration Fallback data rows for the current configuration Primary data rows for the new configuration Fallback data rows for the new configuration Information that defines the new configuration is used during reconfiguration. In a MOVE AMP operation, Reconfiguration copies all rows from the Move-From AMP to the Move-To AMP. You can move a range of AMPs to another range of AMPs; however, a one-to-one correspondence between the Move-From AMPs and the Move-To AMPs must exist. The following sequence discusses the state of these AMPs during the reconfiguration process and the final Parallel Upgrade Tool (PUT) process that completes the swapping of the disks associated with the Move-From AMPs and the Move-To AMPs. 1 Prior to and during most of the reconfiguration process, the Move-To AMPs are configured as new AMPs, just as if you added them. Move-To AMPs have their own vproc 278 Utilities

279 Chapter 10: Reconfiguration Utility (reconfig) About Reconfiguration numbers and associated disk or disks. PUT sets up the relationship between an AMP and its disk. 2 The file system tracks which disks belongs to which AMPs by inserting the AMP number in the cylinder indexes written to each disk. This allows the file system to verify that multiple AMPs do not write to the same disk or disks. The following example shows the relationship between AMPs and disks when AMP 0 moves to AMP 1. Move AMP 0 to AMP 1 Configuration Before and during Reconfiguration Node 0 AMP 0 (ONLINE) Node 1 AMP 1 (NEW) Disk 0 Cylinder Index says this disk belongs to AMP 0 Disk 1 Cylinder Index says this disk belongs to AMP A073 3 When almost finished, Reconfiguration saves the Teradata Database configuration maps to indicate the new configuration. 4 Reconfiguration notifies the file system to change the Move-To AMPs numbers in their cylinder index to the Move-From AMPs numbers. 5 Reconfiguration sets a control flag to keep Teradata Database in a DOWN state and to initiate a restart. 6 While Teradata Database is in a DOWN state, PUT changes the disk mapping between the Move-From AMPs so that their disk or disks are the disk or disks previously associated with the Move-To AMPs. The previous example showed the relationship between AMPs and disks when AMP 0 moves to AMP 1. The following example shows the moving of AMP 0 to AMP 1 after the Reconfiguration and PUT operations complete. AMP 1 no longer exists and is removed from the configuration. But, AMP 1 was really AMP 0 before the PUT process. AMP 0 now is on a different node. AMP 0 now is associated with Disk 1. Disk 1 now has the vproc number of AMP 0 in the cylinder indexes of disk 1. Utilities 279

280 Chapter 10: Reconfiguration Utility (reconfig) About Reconfiguration Move AMP 0 to AMP 1 Configuration After Reconfiguration and PUT Move AMP Node 1 AMP 0 (ONLINE) Disk 1 Cylinder Index says this disk belongs to AMP 0 If the final PUT step is not completed and Teradata Database is restarted, the following error information appears: The wrong disk(s) are connected to the AMPs. The AMPs are marked FATAL. This error is recoverable if Teradata Database and PDE are brought to a DOWN state to continue the PUT MOVE AMP process. For further details on how and why this occurs, see Fatal AMPs During a Move-AMP Operation on page 280. For additional information on the MOVE AMP command, see Configuration Utility in Utilities. Fatal AMPs During a Move-AMP Operation 1102A075 When Reconfiguration completes a MOVE AMP operation, you need to change the PUT configuration to associate the new disks and AMPs correctly. If you do not do this and you restart Teradata Database, the following occurs: The file system checks the cylinder indexes and finds the wrong disk connected to the wrong AMP. The AMPs are marked FATAL. The following example shows what occurs in this situation. AMP 1 is still new, but Disk 1 contains all information from Disk 0. The cylinder index for Disk 1 says that it belongs to AMP Utilities

281 Chapter 10: Reconfiguration Utility (reconfig) Reconfiguration Utility Process As soon as Teradata Database restarts, the file system makes AMP 1 FATAL instead of NEW. The following message appears: appl 1 S I U 0 0 M 0 0 PDE #PDElogd: Event number (severity 10, category 9) Pdisk 1 opened for PRIMARY vproc 1 belongs to vproc 0 Although AMP 1 might be marked FATAL, AMP 1 is removed from the system when the PUT process is complete. You can ignore this error, take Teradata Database and PDE to a DOWN state, and continue with the PUT MOVE AMP process. Move AMP 0 to AMP 1 Configuration After Reconfiguration, before PUT, Teradata Database up Node 0 AMP 0 (ONLINE) Node 1 AMP 1 (FATAL) Disk 0 Cylinder Index says this disk belongs to AMP 0 Disk 1 Cylinder Index says this disk belongs to AMP A074 Effects on Journal Tables Reconfiguration deletes all journal tables (active, saved, and restored subtables). Timestamps Reconfiguration displays timestamps at the beginning and the end of each phase. Reconfiguration Utility Process This section summarizes the process performed by Reconfiguration commands. The details of command syntax and use are described later in this chapter. As Reconfiguration runs, it performs these functions: Checks the Teradata Database system status to ensure that reconfiguration is possible. Disk storage capacity is checked to ensure that the Teradata Database system has sufficient storage to accommodate the redistributed data in the event of a delete AMP Utilities 281

282 Chapter 10: Reconfiguration Utility (reconfig) Reconfiguration Utility Process reconfiguration. Reconfiguration terminates if the Teradata Database system does not have sufficient storage capacity. After Teradata Database system status is verified, new hash bucket arrays are calculated based on current and new configuration maps. Redistributes primary and fallback data. Unique secondary index subtables, if any, are redistributed also. Deletes rows that were redistributed elsewhere from AMPs on which they formerly resided. Nonunique secondary indexes, if any, are rebuilt. Updates space accounting information, hash bucket arrays, and configuration maps. Reconfiguration functions are completed sequentially in this order: 1 Before starting Reconfiguration, see the following sections: Before Starting on page 276. Disabling Logons on page Start the Reconfiguration utility from Database Window. For general information on starting the utilities from different platforms and interfaces, see Appendix B: Starting the Utilities. 3 Specify whether or not to pause before Reconfiguration enters the irreversible phase. The irreversible phase begins when Reconfiguration reaches a point at which it must run to completion, or the Teradata Database system must be re-initialized by running System Initializer. When the irreversible phase begins depends upon the purpose of the reconfiguration. The beginning of the irreversible phase is identified as one of these named phases: The table redistribution phase for add AMP, delete AMP, and cluster reassignment operations The saving new primary hash map phase for all other operations IF you... THEN Reconfiguration does... type RECONFIG without the WITH PAUSE option type RECONFIG with the WITH PAUSE option not prompt you before the irreversible phase begins. prompt you before the irreversible phase begins. 282 Utilities

283 Chapter 10: Reconfiguration Utility (reconfig) Reconfiguration Utility Process IF you... THEN Reconfiguration does... press the F2 key prompt you whether to pause before the irreversible phase begins: Do you want to pause before irreversible phase. Yes or No? IF you type... Yes No THEN Reconfiguration will... prompt you after the hash maps are created. not prompt you after the hash maps are created and will continue the reconfiguration process. If you interrupt Reconfiguration after the irreversible phase, Reconfiguration restarts automatically to complete the remaining phases when the Teradata Database system is restarted. 4 During the initialization of reconfiguration, the existence of all Teradata Database system table headers on all AMPs is verified. If a table header is missing, the table ID and the corresponding vproc ID from which the header is missing are displayed in the Database Window. At the end of the verification, the following message appears in the application window: DBS Table Header verification failed, the missing header is available on the Database Window. Repair all missing table headers before reattempting Reconfiguration. ***** Depress the ENTER key to reset DBS. At this point, you should switch to the Database Window to obtain a list of missing table headers before resetting the Teradata Database system. Caution: If this error condition occurs, contact the Teradata Support Center for the procedures to fix the missing headers. 5 Before entering the hash map calculation phase, Reconfiguration checks all AMPs for active user sessions. If any users are logged on, Reconfiguration issues an error message and halts. The application window and the Database Window display a message similar to the following: Reconfig stopped, logged on sessions found in DBC.Session Table A message similar to the following appears in the application window, describing which PEs have users logged on: They include the following PEs: 16383, 16382, mmm... 6 Reconfig calculates hash map. 7 If you requested Reconfiguration to pause in Step 3, Reconfiguration prompts with the following: Reconfiguration pauses before the irreversible phase. Do You Want to Abort? Type Y(es) or N(o). Utilities 283

284 Chapter 10: Reconfiguration Utility (reconfig) Reconfiguration Utility Process IF you type... THEN Reconfiguration will... Yes No stop. continue to the next phase. 8 Reconfiguration redistributes tables (including stored procedures, user-defined functions (UDFs), user-defined methods (UDMs), and non-value-ordered hash indexes). When reconfiguration reaches the Table Redistribution phase (the irreversible phase) and begins to change data in the current configuration, you must run the operation to completion. In the table redistribution phase, Reconfiguration verifies that the table to be redistributed exists on all online AMPs before table redistribution is started. This integrity check identifies those database tables that are corrupted between initialization and this phase. If a database table is missing from one or more of the online AMPs, the application window shows this message: Table DBName. TBLName *** is missing from some of the online AMPs *** This table is skipped. 9 Reconfiguration deletes moved rows from tables and rebuilds NUSIs. 10 Reconfiguration saves the following: New primary hash map New fallback hash map Current primary hash map Current fallback hash map Current configuration map New configuration map Backup IDs 11 Reconfiguration deletes new hash maps. 12 Reconfiguration saves bitmap hash table. 13 Reconfiguration updates the following: Disk space Vproc configuration When reconfiguration completes, the Teradata Database system displays this message: Restart DBS due to completion of Reconfiguration. System is about to reset. 284 Utilities

285 Chapter 10: Reconfiguration Utility (reconfig) Reconfiguration Utility Process IF... THEN... reconfiguration is aborted by the Teradata Database system due to a hardware or software error before reconfiguration reaches a terminating state a Teradata Database system restart occurs when Reconfiguration is in the middle of the Hash Map calculation phase a restart occurs after the first message and before the second one you are adding new AMPs before Reconfiguration the reconfiguration session is resumed automatically when the Teradata Database system is restarted. No estimator output displays when Reconfiguration is started automatically, and the estimated time remaining that is displayed from the STATUS command will no longer be correct. the following message appears: Hash Map Calculation Phase Begins. { Reconfig Phase one -- rcophas1 } Hash Map Calculation Phase Ends. Reconfiguration will not start automatically during Teradata Database system start up. a 6140 error message displays if you start Reconfiguration manually after the Teradata Database system comes up. 6140: RECONFIG aborted due to improper disk initialization procedure. In this case, do the following in order and then start Reconfiguration: To start xctl from the command prompt, type the following and press Enter: xctl -nw To access the Debug screen, type the following and press Enter: screen debug The following appears: (0) Start ALL Appls: On (1) Break Stop: Off (2) Start with Debug: Off (3) Do not Reset: On (4) Save Dumps: On (5) Snapshot Crash: Off (6) Dump Type: System (7) Maximum Dumps: -1 (8) Maximum Dump Size: -1 (MB) (9) Maximum FSG Area Dumped: 10 (MB) (A) Auto Dump Clear: On START INDIVIDUAL APPLICATIONS (B) Start Appl1: On (C) Start Appl2: Off (D) Start Appl3: Off Start Appl4: Off To turn Start ALL Appls to Off, type the following and press Enter: 0=Off To write the change, type the following and press Enter: write The following is displayed: XCTL: Control GDO successfully written At the command prompt, type the following and press Enter: quit Utilities 285

286 Chapter 10: Reconfiguration Utility (reconfig) Reconfiguration Utility Process IF... THEN... you are adding new AMPs before Reconfiguration (continued) To restart the Teradata Database system, type the following and press Enter: tpareset -f reason where reason is why you are restarting the Teradata Database system. The following appears: You are about to restart the database on the system xyz where xyz is the name of your Teradata Database system. Do you wish to continue (yes/no) [no]: Note: For additional information, see Stopping and Restarting the System in Database Administration. Type Y and press Enter. To clean all data from the newly added vprocs, start the Database Window. For information, see Graphical User Interfaces: Database Window and Teradata MultiTool Select the Supervisor (Supvr) icon. The Supervisor window appears. Type the following at the command input line and press Enter: start vprocmanager The following appears: Started vprocmanager in window 4 at Wed Mar 28 16:55: To view the status of the Teradata Database system, type the following and press Enter: status dbs The following appears: To start the INITVDISK command, type the following and press Enter: INITVDISK vprocid where vprocid is defined as either a decimal or hexadecimal number in the range of 0 through or 0 through 3FFF, respectively. 286 Utilities

287 Chapter 10: Reconfiguration Utility (reconfig) Reconfiguration Utility Process IF... THEN... you are adding new AMPs before Reconfiguration (continued) Note: A hexadecimal number is specified by appending a trailing X or x (for example, 123X or B6x). For example, assume you want to initialize the Teradata Database file system on vproc 1. You type: initvdisk 1 The following appears: Starting the file system initialization task on 1... The Vdisk associated with Vproc 1 has been initialized. Enter a command, HELP or QUIT: Type the following and press Enter: quit The following appears: Exiting VprocManager... To start xctl from the command prompt, type the following and press Enter: xctl -nw To access the Debug screen, type the following and press Enter: screen debug The following appears: To turn Start ALL Appls to On, type the following and press Enter: 0=On The following is displayed: To write the change, type the following and press Enter: write XCTL: Control GDO successfully written At the command prompt, type the following and press Enter: quit Start the Reconfiguration utility from Database Window. For general information on starting the utilities from different platforms and interfaces, see Appendix B: Starting the Utilities. 14 You must drop and rebuild value-ordered join indexes and value-ordered hash indexes after a Reconfig. Utilities 287

288 Chapter 10: Reconfiguration Utility (reconfig) Reconfiguration Utility Commands Reconfiguration Utility Commands A reconfiguration session consists of reconfiguring the Teradata Database system according to the new configuration map built by the Configuration utility. The following table lists Reconfiguration commands and their functions. Commands RECONFIG (or press F2) STATUS STOP (or press F3) Function Begins a session that changes the Teradata Database system configuration according to the map provided by the Configuration utility. Determines the status of Reconfiguration. Stops Reconfiguration. To display help information on Reconfiguration, press F Utilities

289 Chapter 10: Reconfiguration Utility (reconfig) RECONFIG RECONFIG Purpose The RECONFIG command begins the process of changing the Teradata Database system configuration. Note: A new configuration map must have been produced previously using the Configuration utility. Syntax RECONFIG R WITH DISPLAY ON OFF n TASKS PRIORITY p PAUSE STATISTICS ON OFF 1102B002 where: Syntax element... Specifies... DISPLAY n TASKS whether to enable or disable output of Reconfiguration status (but not statistics): ON enables output. (Default) OFF disables output. the limitation of the number of Reconfiguration sessions running in parallel. n is a number between 1 and 10 inclusive. The default is 10. PRIORITY p the priority string determined by Priority Scheduler. The default is M. Utilities 289

290 Chapter 10: Reconfiguration Utility (reconfig) RECONFIG Syntax element... Specifies... PAUSE STATISTICS whether Reconfiguration is to pause before entering the irreversible phase. Each AMP stores the current phase of reconfiguration. whether to enable or disable output of Reconfiguration statistics: ON enables statistics. (Default) OFF disables statistics. Example 1 To disable statistics collection, type: reconfig with statistics off Example 2 To reconfigure with 10 control tasks and statistics disabled, type: reconfig with 10 tasks statistics off Example 3 To reconfigure with eight control tasks and statistics enabled, type: reconfig with 8 tasks reconfig with statistics on 8 tasks Example 4 To reconfigure with eight control tasks and output display disabled, type: reconfig with 8 tasks display off Example 5 To reconfigure with eight control tasks at low priority and output display disabled, type: reconfig with 8 tasks priority l display off Example 6 To reconfigure with eight control tasks at a user-defined priority of utilprio and output display disabled, type: reconfig with 8 tasks priority utilprio display off Example 7 Reconfiguration output displays the following: Start and end time of each table processed during redistribution Run-time statistics of the table process that includes statistics for all AMPs 290 Utilities

291 Chapter 10: Reconfiguration Utility (reconfig) RECONFIG This information is included with the deletion and NUSI building. The output might become excessive for a large number of tables, so you might want to disable DISPLAY. If you disable DISPLAY, you can still obtain status using the STATUS command. Note: You can disable the table begin/completion output with the RECONFIG WITH DISPLAY OFF command. You can disable the statistics output with the RECONFIG WITH STATISTICS OFF command. Redist Deletion TableSize RowCount NUSICount FB Estimate Estimate Database.Table KB 80 0 Y 00:00:01 00:00:00 DBC.Translation (0000H 003BH) 32.00KB 32 0 Y 00:00:01 00:00:00 DBC.Dbase_V1R4 (0000H 003DH) 48.00KB 32 0 Y 00:00:01 00:00:00 DBC.TVM_V1R5 (0000H 003EH) KB Y 00:00:01 00:00:00 DBC.EventLog (0000H 003FH) 32.00KB 32 0 Y 00:00:01 00:00:00 DBC.Next_V2R2 (0000H 0040H) 32.00KB 32 0 Y 00:00:01 00:00:00 DBC.AccessRights_V1R5 (0000H 0041H) 16.00KB 32 0 Y 00:00:01 00:00:00 DBC.Accounts_V2R4 (0000H 0042H) KB 2,296 0 N 00:00:01 00:00:00 DBC.Acctg (0000H 0043H) 32.00KB 32 0 Y 00:00:01 00:00:00 DBC.Indexes_V2R2 (0000H 0044H) 32.00KB 32 0 Y 00:00:01 00:00:00 DBC.RCEvent (0000H 0046H) 48.00KB 32 0 Y 00:00:01 00:00:00 DBC.TVFields_V1R5 (0000H 0047H) 32.00KB 32 0 Y 00:00:01 00:00:00 DBC.Hosts (0000H 0048H) 16.00KB 32 0 N 00:00:01 00:00:00 DBC.RecoveryLockTable (0000H 0049H) 16.00KB 32 0 N 00:00:01 00:00:00 DBC.RecoveryPJTable (0000H 004AH) 18.00KB 36 0 Y 00:00:01 00:00:00 DBC.DBCInfoTbl (0000H 004BH) 48.00KB 32 0 Y 00:00:01 00:00:00 DBC.SessionTbl (0000H 004CH) 48.00KB 32 0 Y 00:00:01 00:00:00 DBC.Dbase_V1R5 (0000H 004DH) 33.00KB 34 0 Y 00:00:01 00:00:00 DBC.SysSecDefaults (0000H 004EH) 32.00KB 32 0 Y 00:00:01 00:00:00 DBC.OldPasswords (0000H 004FH) 32.00KB 32 0 Y 00:00:01 00:00:00 DBC.InDoubtResLog (0000H 0050H) 32.00KB 32 0 Y 00:00:01 00:00:00 DBC.ReferencingTbls_V2R2 (0000H 0051H) 32.00KB 32 0 Y 00:00:01 00:00:00 DBC.ReferencedTbls_V2R2 (0000H 0052H) 32.00KB 32 0 Y 00:00:01 00:00:00 DBC.TableConstraints_V2R2 (0000H 0053H) 48.00KB 32 0 Y 00:00:01 00:00:00 DBC.AccLogRuleTbl_V2R2 (0000H 0054H) 48.00KB 32 0 Y 00:00:01 00:00:00 DBC.Dbase_V2R2 (0000H 0055H) 48.00KB 32 0 Y 00:00:01 00:00:00 DBC.TVM_V2R2 (0000H 0056H) 32.00KB 32 0 Y 00:00:01 00:00:00 DBC.AccessRights_V2R2 (0000H 0057H) 32.00KB 32 0 Y 00:00:01 00:00:00 DBC.TVFields_V2R2 (0000H 0058H) 32.00KB 32 0 Y 00:00:01 00:00:00 DBC.UnResolvedReferences (0000H 0059H) 32.00KB 32 0 Y 00:00:01 00:00:00 DBC.ConstraintNames_V2R2 (0000H 005AH) KB Y 00:00:01 00:00:00 DBC.Indexes (0000H 005BH)... Utilities 291

292 Chapter 10: Reconfiguration Utility (reconfig) STATUS STATUS Purpose The STATUS command allows you to determine the status of Reconfiguration at any time during the process. Syntax STATUS S HH01A002 Usage Notes Example 1 STATUS is available at any time during Reconfiguration and includes the status of the following: Total number of tables processed for the redistribution, deletion, and NUSI phases Total number of tables remaining to be processed for the redistribution, deletion, and NUSI phases Completion percentage according to the total number of bytes processed Status of each non-idle, parallel reconfiguration control task Completion percentage and name of table being processed for each non-idle, parallel reconfiguration control task The following is an example of STATUS output during hash map calculation. Current reconfig phase: Hash Map Calculation Example 2 The following is an example of STATUS output during redistribution. Current reconfig phase: Redistribution Estimated time remaining: 00:19:21 Redistribution status - tables processed: 152 tables remaining: 26 70% of total bytes processed Deletion/NUSI status - tables processed: 0 tables remaining: 178 0% of total bytes processed 292 Utilities

293 Chapter 10: Reconfiguration Utility (reconfig) STATUS Reconfig task 0 Processed 69% of RKPMED.SIW_XXXX_FB_12 (0000H 04C4H) Reconfig task 1 Processed 69% of RKPMED.SIW_XXXX_FB_7 (0000H 04BFH) Reconfig task 2 Processed 69% of RKPMED.SIW_XXXX_FB_11 (0000H 04C3H) Reconfig task 3 Processed 68% of RKPMED.SIW_XXXX_FB_15 (0000H 04C7H) Reconfig task 4 Processed 69% of RKPMED.SIW_XXXX_FB_8 (0000H 04C0H) Reconfig task 5 Processed 68% of RKPMED.SIW_XXXX_FB_13 (0000H 04C5H) Reconfig task 6 Processed 64% of RKPMED.SIW_XXXX_FB_14 (0000H 04C6H) Reconfig task 7 Processed 69% of RKPMED.SIW_XXXX_FB_9 (0000H 04C1H) Reconfig task 8 Processed 69% of RKPMED.SIW_XXXX_FB_6 (0000H 04BEH) Reconfig task 9 Processed 69% of RKPMED.SIW_XXXX_FB_10 (0000H 04C2H) Example 3 The following is an example of STATUS output during Deletion/NUSI rebuilding. Current reconfig phase: Redistribution Estimated time remaining: 00:19:21 Redistribution status - tables processed: 152 tables remaining: % of total bytes processed Deletion/NUSI status - tables processed: 152 tables remaining: 26 70% of total bytes processed Reconfig task 0 Processed 69% of RKPMED.SIW_XXXX_FB_12 (0000H 04C4H) Reconfig task 1 Processed 69% of RKPMED.SIW_XXXX_FB_7 (0000H 04BFH) Reconfig task 2 Processed 69% of RKPMED.SIW_XXXX_FB_11 (0000H 04C3H) Reconfig task 3 Processed 68% of RKPMED.SIW_XXXX_FB_15 (0000H 04C7H) Reconfig task 4 Processed 69% of RKPMED.SIW_XXXX_FB_8 (0000H 04C0H) Reconfig task 5 Processed 68% of RKPMED.SIW_XXXX_FB_13 (0000H 04C5H) Reconfig task 6 Processed 64% of RKPMED.SIW_XXXX_FB_14 (0000H 04C6H) Reconfig task 7 Processed 69% of RKPMED.SIW_XXXX_FB_9 (0000H 04C1H) Reconfig task 8 Processed 69% of RKPMED.SIW_XXXX_FB_6 (0000H 04BEH) Reconfig task 9 Processed 69% of RKPMED.SIW_XXXX_FB_10 (0000H 04C2H) Utilities 293

294 Chapter 10: Reconfiguration Utility (reconfig) STOP STOP Purpose The STOP command stops Reconfiguration. Syntax STOP S GT10B001 Usage Notes When the STOP command is accepted, Reconfiguration displays this message: Are You Sure? Enter Y(es) or N(o): Type Y to stop or N to continue. Error Messages The application window running Reconfiguration can contain the types of messages displayed in the output subwindow, as shown in the following table. Message Information Prompt Error Description Indicates the status of a command or the result of an operation. OK indicates that a command has been accepted or an operation has completed successfully. Prompts for a response to a request or for confirmation of an action. Composed of a message code and text. All error messages issued by Reconfiguration are described in Messages. 294 Utilities

295 Chapter 10: Reconfiguration Utility (reconfig) Reconfiguration Example Reconfiguration Example The following is a Reconfiguration example. Most of the detailed table redistribution text is eliminated for brevity. / / \ --- / / / / \ \ \ \ \ Release Version RECONFIG Utility (Dec 94) The RECONFIG program provides the user with a facility to redistribute data when the configuration of a DBS is changed by pressing the appropriate function key. System Time (Reconfiguration): 07/03/01 15:20:52. Enter command or Press <F2> for Reconfig command <F3> for Stop command <F4> for Query or Status command <F7> for help reconfig Reconfig will use 16-bit bucket size. DBlk Part Redist Deletion TableSize RowCount NUSICount FB Size Count Estimate Estimate Database.Table KB 2 0 Y 63KB 1 00:00:00 00:00:00 DBC.SW_Event_Log_V2R6 (0000H 0006H) 2.00KB 2 0 Y 63KB 1 00:00:00 00:00:00 DBC.RCConfiguration (0000H 0007H) 2.00KB 2 0 Y 63KB 1 00:00:00 00:00:00 DBC.CollationTbl_V2R6 (0000H 0008H) 2.00KB 4 0 Y 63KB 1 00:00:00 00:00:00 DBC.Global (0000H 0019H) 1.00KB 2 0 N 63KB 1 00:00:00 00:00:00 DBC.TransientJournal (0000H 001AH) 2.00KB 18 0 Y 63KB 1 00:00:00 00:00:00 DBC.Owners (0000H 001BH) 3.00KB 18 0 Y 63KB 1 00:00:00 00:00:00 DBC.Parents (0000H 001CH) KB 5,940 0 Y 63KB 1 00:00:00 00:00:00 DBC.ErrorMsgs (0000H 001EH) KB 6 0 Y 31KB 1 00:00:00 00:00:00 SQLJ.ALTER_JAVA_PATH (0000H 0591H) 6.00KB 6 0 Y 31KB 1 00:00:00 00:00:00 SQLJ.REDISTRIBUTE_JAR (0000H 0592H) 1.00KB 2 0 N 63KB 1 00:00:00 00:00:00 DBC.FIRSTJOURNALTABLE (4000H 0000H) The current configuration has: 1 Nodes with 2 AMPs The new configuration will be: 1 Nodes with 1 AMPs There are 1 AMPs deleted from the current configuration The system has: 198 tables using 18.16MB of data The estimated table redistribution time will be: 0.01 hours. The estimated table deletion time will be: 0.01 hours. This reconfig estimate is based upon 48XX/49XX/52XX OR LATER. Reconfig waiting for Recovery to complete... Recovery has been stopped 07/08/06 13:30:54 Hash Map Calculation Phase Begins 07/08/06 13:30:55 Hash Map Calculation Phase Ends 07/08/06 13:30:55 Table Redistribution Phase Begins 07/08/06 13:30:56 Task 00 Begin redistribution DBC.SW_Event_Log_V2R6 (0000H 0006H). 07/08/06 13:30:56 Task 00 End redistribution DBC.SW_Event_Log_V2R6 (0000H 0006H). Statistics: RowCount ByteCount TotSecs CPUSecs IOCount AllAmps: /08/06 13:30:56 Task 01 Begin redistribution DBC.RCConfiguration (0000H 0007H). 07/08/06 13:30:56 Task 00 Begin redistribution DBC.CollationTbl_V2R6 (0000H 0008H). 07/08/06 13:30:56 Task 00 End redistribution DBC.CollationTbl_V2R6 (0000H 0008H). Statistics: RowCount ByteCount TotSecs CPUSecs IOCount AllAmps: /08/06 13:30:56 Task 01 End redistribution DBC.RCConfiguration (0000H 0007H). Statistics: RowCount ByteCount TotSecs CPUSecs IOCount AllAmps: /08/06 13:30:56 Task 02 Begin redistribution DBC.Global (0000H 0019H). 07/08/06 13:30:56 Task 00 Begin redistribution DBC.TransientJournal (0000H 001AH). 07/08/06 13:30:56 Task 00 End redistribution DBC.TransientJournal (0000H 001AH). Utilities 295

296 Chapter 10: Reconfiguration Utility (reconfig) Reconfiguration Example Statistics: RowCount ByteCount TotSecs CPUSecs IOCount AllAmps: /08/06 13:31:08 Task 07 End redistribution SQLJ.REDISTRIBUTE_JAR (0000H 0592H). Statistics: RowCount ByteCount TotSecs CPUSecs IOCount AllAmps: KB /08/06 13:31:09 Task 00 End redistribution SYS_CALENDAR.CALDATES (0000H 056EH). Statistics: RowCount ByteCount TotSecs CPUSecs IOCount AllAmps: 36, MB /08/06 13:31:09 Task 06 End redistribution DBC.TVFields (0000H 00C2H). Statistics: RowCount ByteCount TotSecs CPUSecs IOCount AllAmps: 7, MB /08/06 13:31:10 Table Redistribution Phase Ends 07/08/06 13:31:10 Old Table Deletion Phase Begins 07/08/06 13:31:10 Task 00 Begin deletion DBC.SW_Event_Log_V2R6 (0000H 0006H). 07/08/06 13:31:10 Task 00 End deletion DBC.SW_Event_Log_V2R6 (0000H 0006H). Statistics: RowCount ByteCount TotSecs CPUSecs IOCount AllAmps: /08/06 13:31:10 Task 01 Begin deletion DBC.RCConfiguration (0000H 0007H). 07/08/06 13:31:10 Task 00 Begin deletion DBC.CollationTbl_V2R6 (0000H 0008H). 07/08/06 13:31:10 Task 00 End deletion DBC.CollationTbl_V2R6 (0000H 0008H). Statistics: RowCount ByteCount TotSecs CPUSecs IOCount AllAmps: /08/06 13:31:10 Task 01 End deletion DBC.RCConfiguration (0000H 0007H). Statistics: RowCount ByteCount TotSecs CPUSecs IOCount AllAmps: /08/06 13:31:11 Task 02 Begin deletion DBC.Global (0000H 0019H). 07/08/06 13:31:11 Task 00 Begin deletion DBC.TransientJournal (0000H 001AH). 07/08/06 13:31:11 Task 00 End deletion DBC.TransientJournal (0000H 001AH). Statistics: RowCount ByteCount TotSecs CPUSecs IOCount AllAmps: /08/06 13:31:19 Task 02 Begin deletion SQLJ.REDISTRIBUTE_JAR (0000H 0592H). 07/08/06 13:31:19 Task 01 Begin deletion DBC.FIRSTJOURNALTABLE (4000H 0000H). 07/08/06 13:31:19 Task 01 End deletion DBC.FIRSTJOURNALTABLE (4000H 0000H). Statistics: RowCount ByteCount TotSecs CPUSecs IOCount AllAmps: /08/06 13:31:19 Task 00 End deletion systemfe.cleanupqcfver (0000H 0544H). Statistics: RowCount ByteCount TotSecs CPUSecs IOCount AllAmps: /08/06 13:31:19 Task 02 End deletion SQLJ.REDISTRIBUTE_JAR (0000H 0592H). Statistics: RowCount ByteCount TotSecs CPUSecs IOCount AllAmps: /08/06 13:31:19 Task 04 End deletion SQLJ.REMOVE_JAR (0000H 0590H). Statistics: RowCount ByteCount TotSecs CPUSecs IOCount AllAmps: /08/06 13:31:20 Old Table Deletion Phase Ends 07/08/06 13:31:20 Saving New Primary Hash Map Phase Begins 07/08/06 13:31:20 Saving New Primary Hash Map Phase Ends 07/08/06 13:31:20 Saving New Fallback Hash Map Phase Begins 07/08/06 13:31:20 Saving New Fallback Hash Map Phase Ends 07/08/06 13:31:20 Saving Current Primary Hash Map Phase Begins 07/08/06 13:31:21 Saving Current Primary Hash Map Phase Ends 07/08/06 13:31:21 Saving Current Fallback Hash Map Phase Begins 07/08/06 13:31:21 Saving Current Fallback Hash Map Phase Ends 07/08/06 13:31:21 Saving Current Configuration Map Phase Begins 07/08/06 13:31:21 Saving Current Configuration Map Phase Ends 07/08/06 13:31:21 Saving New Configuration Map Phase Begins 07/08/06 13:31:21 Saving New Configuration Map Phase Ends 07/08/06 13:31:22 Saving Backup IDs Phase Begins 07/08/06 13:31:22 Saving Backup IDs Phase Ends 07/08/06 13:31:22 Deleting New Hash Maps Phase Begins 07/08/06 13:31:22 Deleting New Hash Maps Phase Ends 07/08/06 13:31:22 Saving Bitmap Hash Table Phase Begins 07/08/06 13:31:22 Saving Bitmap Hash Table Phase Ends 07/08/06 13:31:22 Updating Disk Space Phase Begins 07/08/06 13:31:22 Updating Disk Space Phase Ends 07/08/06 13:31:22 Updating Vproc Configuration Begins 07/08/06 13:31:22 Updating Vproc Configuration Ends System Time (Reconfiguration): 07/08/06 13:31: : Restarting DBS due to completion of reconfiguration. System is about to be reset. 296 Utilities

297 CHAPTER 11 Recovery Manager (rcvmanager) The Recovery Manager utility, rcvmanager, monitors and provides information about the progress of a Teradata Database system in recovery, including transaction rollbacks, because of a Teradata Database system crash or user abort. The recovery process might include one or more of the following: Online Transaction recovery Down AMP recovery of changed data rows Down AMP recovery of Teradata Database system level changes Also, rcvmanager allows you to do the following: Cancel the rollback of one or more specified host and session ID Set the priority level of rollbacks in progress for a specified host and session ID Set priority levels to optimize Teradata Database system recovery Audience Users of rcvmanager include the following: Teradata Database operators Teradata Database system administrators Teradata Database system programmers User Interfaces rcvmanager runs on the following platforms and interfaces: Platform MP-RAS Windows Linux MVS/VM Interfaces Database Window Database Window Database Window Host Utility Console (HUTCNS) Utilities 297

298 Chapter 11: Recovery Manager (rcvmanager) Prerequisites For general information on starting the utilities from different platforms and interfaces, see Appendix B: Starting the Utilities. Prerequisites You can run rcvmanager only while the Teradata Database is in one of the following states: Logon Logon/quiet Logoff Logoff/quiet Startup (if the Teradata Database system has completed voting for transaction recovery) If you attempt to start rcvmanager while the Teradata Database system is not in one of the allowable states, the utility displays the following error information and terminates: RCVMANAGER can only be run when the system is in the LOGON or LOGOFF state or if the system is in the STARTUP state and has completed voting for transaction recovery. The current system is not in one of these allowable states thus preventing RCVMANAGER from operating. RCVMANAGER terminated. Assigning Priority Levels You can assign priority levels to Teradata Database system recovery or table rebuild by using the PRIORITY command feature of rcvmanager. Control over job priority is assigned by selecting one of three priority levels: HIGH MEDIUM LOW For information about these priority levels, see REBUILD/RECOVERY PRIORITY on page 335. Teradata Database system recovery and disk rebuild are primarily I/O intensive tasks. The major portion of the time taken by a given task is involved in setting up for or waiting for completions of a disk or a BYNET message traffic operation. Very little manipulation or computation is required on the data once it is available. If the competing work load of the Teradata Database system can be reasonably characterized, then you can gauge the impact of the priority changes to recovery and rebuild operations. In general, use the following guidelines when assigning priorities: 298 Utilities

299 Chapter 11: Recovery Manager (rcvmanager) Online Transaction Recovery Guideline No work load competition Computeintensive work load Moderate or heavy disk work load I/O saturation Description If there is no competition for resources as in a COLDWAIT restart for recovery, the priority setting of the recovery and rebuild jobs will have no practical effect. If the online Teradata Database system work load is heavily compute intensive, raising the priority of the I/O intensive recovery operations can dramatically improve the recovery (including rebuild). The high recovery will have a relatively minor impact on the online Teradata Database system operations. However, it will provide a better resource utilization and result in better Teradata Database system throughput. Similarly, a low priority of recovery in this work load will dramatically slow down recovery with only a moderate gain in online throughput. If a moderate or heavy amount of disk and/or BYNET usage occurs by the online system, then recovery will show moderate throughput changes by controlling the priority setting but with a larger impact against the Teradata Database system throughput. Memory contention becomes a major component of operation in these cases. As the I/O utilization approaches saturation, there are fewer opportunities to improve throughput or execution time of either the online Teradata Database system or the recovery job. In this case, we are competing for the same resource and that resource is not amenable to manipulation by control over the scheduling priority. Changing Priority Levels for Rollback rcvmanager also allows you to change the priority levels for rollback. To display or set the current Performance Group of the rollback for a particular session, use the ROLLBACK SESSION... PERFORMANCE GROUP command. The priority associated with the specified Performance Group determines the priority of rollback for the specified host and session IDs. For more information, see ROLLBACK SESSION...PERFORMANCE GROUP on page 336. Online Transaction Recovery Online transaction recovery is automatically invoked by a Teradata Database system restart and includes the following processes: Rolling back transactions that were not completed at the time of the crash or restart Completing transactions that were committed Changes made to underlying data by transactions are recorded in the Transient Journal (TJ). AMPs keep track of transactions in progress using the TJ which is stored on each AMP s disk. Utilities 299

300 Chapter 11: Recovery Manager (rcvmanager) Transaction Recovery Sequence IF... THEN... all the modification operations successfully complete on all the AMPs working on behalf of the transaction a transaction does not complete due to a Teradata Database system crash or forced restart that transaction is successful and there is no further concern for recovery of that transaction. those transactions are backed out as part of the Teradata Database system recovery process when the Teradata Database system restarts. Transaction Recovery Sequence The general sequence of a Teradata Database system recovery is as follows: 1 The status of each transaction on each online AMP is determined by the Teradata Database system. All of the online AMPs at the time of the restart work together to determine which transactions were complete, and which ones were not completed. Completed transactions are ignored and incomplete ones are backed out. The process of rolling back incomplete transactions might take some time. Write and exclusive locks are set against all data modified by incomplete transaction. 2 All locks needed for the recovery are set, and the Teradata Database system begins roll back or completion of the transactions. 3 The Teradata Database system accepts work and is operational. Note: If new transactions reference the inconsistent data of to-be-rolled-back transactions, they are blocked until the recovery process restores the data and releases the lock. 4 Down AMP recovery begins. Multiple Recovery Sessions A recovery session is the set of actions to be taken as a result of the Teradata Database system restart for all transactions that were in progress at the time the Teradata Database system restarted. All of the online AMPs at the time of the restart work together to determine which transactions were complete, and which ones were not completed. Completed transactions are ignored and incomplete ones are backed out. If new work or transactions are allowed in during recovery, and another restart occurs, an additional recovery session is created. Then there will be two recovery sessions: The first one that was created for the previous restart The new one that was created for the current work 300 Utilities

301 Chapter 11: Recovery Manager (rcvmanager) Deferred Transaction Recovery Since there is a sequential relationship between these two recovery sets and they are inherently mutually exclusive, they are kept as separate operations. Therefore, if a system crash or user abort occurs and the amount of work to be done in each recovery session is large, then three, four or more recovery sessions may be created. Each session exists until all the incomplete transactions of the session are rolled back. The issue of multiple recovery sessions may be avoided by having all the restarts be COLDWAIT, since the WAIT means to wait for recovery to complete before allowing the Teradata Database system to accept new work from the hosts. Although the recovery proceeds faster, since it is not competing with any other new work for computing resources, the Teradata Database system remains totally unavailable to the database users. Deferred Transaction Recovery If the Teradata Database system crashes, a COLD restart is activated and an online transaction recovery or deferred recovery is started. The only time a deferred recovery is not done is when the operator enters a COLDWAIT restart. Deferred transaction recovery allows new transactions to come in from the connected hosts. The process of bringing the Teradata Database system up after a crash causes the locks to be set. If new transactions should attempt to reference the inconsistent data of the to-be-rolledback transactions, they are blocked until the recovery process restores the data and releases the lock. Down AMP Recovery Down AMP Recovery is a process that handles all changes to entire tables or rows, either fallback and primary, while the AMP is down or offline. Down AMP Recovery updates a recovering AMP with data that the Teradata Database system processed while the AMP was down. The down AMP is considered to be in offline catchup mode. Catchup mode indicates that the AMP is logically offline and in the process of updating its tables so that they are synchronized with the online AMPs in the cluster. In a crash or restart condition, it is possible to lose an AMP from, for example, a CPU board failure without losing its underlying disk data. The remainder of the Teradata Database system can then restart and recover the transactions without the failed AMP. After the down AMP is ready to rejoin the Teradata Database system, the down AMP recovers the lost data by performing the following steps: 1 Restoring the data to a consistent state, relative to the transactions the down AMP was working on at the time of the failure. The down AMP applies the information in its Transient Journal against its underlying data. Moreover, the down AMP must concur with the choice of the rest of the Teradata Database system whether to rollback or commit each transaction. Utilities 301

302 Chapter 11: Recovery Manager (rcvmanager) Down AMP Recovery 2 Updating the restored data to match all changes made to the online Teradata Database system while the AMP was down (Down AMP Recovery) Down AMP Recovery Operations Display Recovering Down AMPs The following display indicates the fields that are referenced in the down AMP recovery operations explanation on the next page. This display is printed out by rcvmanager. For a description of the fields in the following display, see Down/Catchup AMP Recovery Status on page 326. DOWN AMP RECOVERY STATUS at HH:MM:SS MM/DD/YY AMP to be Current Pass Next Pass caught up Pass OJ CJ OJ CJ ,081 - AMP Status: Online Catchup - Not currently executing recovery , ,081 - AMP Status: Offline Catchup - Transaction Recovery: 25,488 TJ Rows , AMP Status: Online Catchup - Change Row Recovery: 26% complete in this pass , ,228 - AMP Status: Offline Catchup - Rebuilding Database1.Table1: 45% complete 0005* ,888 - AMP Status: Offline Catchup - Between passes * - would probably be placed in online catch up if a restart occurred Note: Perform steps one through four only when offline catchup AMPs exist. If an AMP is still physically down, do not perform these steps. To recover a down AMP, do the following: 1 Previously down AMPs that are now available begin their local transaction recovery (referred to as offline catchup AMPs). This step must be completed before going to step 2. 2 The extracted Ordered System Change Journal (OJ) is processed, rebuilding various subtables. 3 The extracted Changed Row Journal (CJ) rows are then processed by sending the changed rows (or notification that the rows were deleted) to the catchup AMP. 4 The OJ entries are applied. Ones which take a significant amount of time are the build operations. 5 Current CJ entries are applied. Each CJ entry represents one row to be updated (insert, delete, update). 6 Online AMPs in the down AMP cluster extract all the current build records from the OJ and CJ, and sort them to eliminate duplicates. Any CJ entries referring to rows in a table which will be rebuilt are deleted. Other OJ operations are sent to the catchup AMP for execution. 7 The Next Pass OJ and CJ entries become the Current Pass entries. 302 Utilities

303 Chapter 11: Recovery Manager (rcvmanager) Down AMP Recovery Recovery Journal 8 Repeat steps 2 through 7 indefinitely. 9 After the AMP is sufficiently caught up, it becomes eligible to become an online catchup AMP on the next restart. This is denoted by displaying an asterisk (*) under the column entitled, AMP to be caught up, in the DOWN AMP RECOVERY STATUS screen of the rcvmanager status display. See the previous display screen. When an AMP in a cluster goes down, and the fallback option is specified for a table, the Down AMP Recovery Journal (RJ) records changes made to the fallback tables that are applicable to the down AMP. The journal is active only during an AMP failure and is only used for fallback tables. The Recovery Journal process for a down AMP is as follows: 1 Operational AMPs in the cluster begin logging entries into the Down AMP RJ. 2 The Down AMP RJ records the changes that should have been made to fallback-protected rows of the inoperative AMP. 3 The changes are applied when the down AMP recovers. Types of Recovery Journal Records The Recovery Journal maintains the following two sets of records: Record Changed Row Journal (CJ) Ordered System Change Journal (OJ) Function Logs changed rows in an AMP cluster by logging pointers to the rows that have been changed, but does not log the actual rows. Logs events such as, building the index, creating a permanent journal, and performing a table rebuild. These types of changes may be termed Teradata Database system-level changes and involve Data Definition Language (DDL) operations, since they affect all AMPs, not only a single row update. Changed Row Journal The CJ recovery needs to match its data against all changes made to the online Teradata Database system while the AMP was down. The most common type of changes includes modifications made to individual rows by Data Manipulation Language (DML) operations of inserting, deleting, and updating rows in pre-existing tables. Each modified row is remembered in the Teradata Database system CJ, which is local to each AMP on which the modification takes place. Since the modification is done only while an AMP is down, the CJ is only populated on AMPs in a cluster while an AMP is down. AMPs are arranged into a group called clusters so that each AMP provides fallback protection to other members within that same group. Utilities 303

304 Chapter 11: Recovery Manager (rcvmanager) Down AMP Recovery Entries stored in the CJ include only the table ID and row ID of the row which was modified. When the down AMP recovers, the actual row is extracted from the fallback or primary subtable; the row image is not stored redundantly in the CJ. Ordered System Change Journal Teradata Database system-level changes are data changes that are applied to the online Teradata Database system while an AMP is down. These changes are called system level because they affect all AMPs, as opposed to a single row update. These changes cover DDL operations such as, DROP TABLE, CREATE TABLE, and CREATE/ DROP INDEX. Other operations include a change to every single row within a table, for example, drop a column. For these types of operations, recovery involves copying every single row of the table, for those rows the AMP owns, over to that down AMP (a table rebuild). Therefore, the majority of the rows found in the OJ are build records that identify tables that need to be built for created tables, or rebuilt when the AMP is recovered. Other OJ records are HUT Lock set and release records, and in-doubt two-phase commit transaction. Deferred Down AMP Recovery The process of Deferred Down AMP Recovery means that while a down AMP remains down and recovering, the rest of the Teradata Database system continues its operations with the connected hosts. The following sections describe the modes: Offline catchup Online catchup Offline Catchup Mode In offline catchup mode, the new transactions for the down AMP are performed by other AMPs in the cluster. Therefore, new change row and Teradata Database system change entries are made while the down AMP is processing the old ones. While the AMP is in catchup mode, the AMP is considered logically offline. Setting a Down AMP to Offline Catchup Mode To set a down AMP to offline catchup mode, do the following: 1 Start the Vproc Manager utility. 2 To list the Teradata Database system logical configuration, type: status; A screen similar to the following appears: DBS LOGICAL CONFIGURATION Vproc Rel. Node Crash Vproc Config Config Cluster/ RvcJrnl/ Number Vproc# ID Movable Count State Status Type Host No. Host Type 0* No 0 Online Online AMP 0 On No 0 Offline Down AMP 0 On No 0 Online Online PE 52 COP * DBS Control AMP DBS State: Logons are enabled - Users are logged on DBS RestartKind: COLD The disable list is empty 304 Utilities

305 Chapter 11: Recovery Manager (rcvmanager) Down AMP Recovery 3 To bring up the downed AMP, type: set 1 = online; If vproc 1 goes into catchup mode, the following message appears: Vproc 1 will begin recovery in the background via the Recovery Control Task 4 To verify that the AMP is in Utility Catchup mode, type: status: While in the offline mode, the AMP has OJ build records to process and/or a large number of CJ rows. This reduces the amount of data that is locked, but any new transactions on the online Teradata Database system creates additional OJ and CJ rows. Since you cannot place an offline AMP into the online Teradata Database system, these passes could continue forever or until the Teradata Database system restarts. A screen similar to the following appears: DBS LOGICAL CONFIGURATION Vproc Rel. Node Crash Vproc Config Config Cluster/ RvcJrnl/ Number Vproc# ID Movable Count State Status Type Host No. Host Type 0* No 0 Online Online AMP 0 On No 0 Utility Catchup AMP 0 On No 0 Online Online PE 52 COP * DBS Control AMP DBS State: Logons are enabled - The system is quiescent DBS RestartKind: COLD The disable list is empty Verifying if an Offline AMP is in Catchup Mode To verify if an offline AMP, for example, is almost in catchup, do the following: 1 Start rcvmanager. 2 To check the offline AMP status, type: list status; One of the following messages appears: Message... Means that the... - AMP Status: Not in recovery - Down - AMP Status: Offline Catchup - Executing miscellaneous Recovery actions - AMP Status: Offline Catchup - Between Passes * - would probably be placed in online catchup if a restart occurs. AMP is still down. AMP is in catchup mode. AMP is in catchup mode, and if a restart occurs, the AMP is placed in online catchup mode. Note: Sufficiently recovered refers to the third message in the table above. If a COLDWAIT restart is performed, the operations are similar to those of Transaction Recovery. In COLDWAIT, the Teradata Database system remains offline with no incoming transactions until all recovering AMPs have fully recovered. After recovery, the AMPs are all set to online status, and the Teradata Database system completes start-up. Utilities 305

306 Chapter 11: Recovery Manager (rcvmanager) Startup/Restart Messages In offline catchup, catchup tries to run faster than the new update transactions coming in online. The other AMPs handle the fallback responsibility for the down AMP, as well as the additional work involved in writing CJ or OJ records. If an AMP is designated to be in offline catchup mode, then you must initiate a COLD restart, but only after the AMP has sufficiently recovered, to bring the offline AMP back online. Online Catchup Mode In online catchup mode, the previously down AMP will also accept transactions, as will the rest of the Teradata Database system. In this mode, all the data that needs updating is locked, so that new data does not operate on the obsolete data. When the down AMP has a small amount to recover, it can be placed into online catchup. To begin online catchup mode, see Verifying if an Offline AMP is in Catchup Mode on page 305. Since the AMP is online and participating in the new transaction coming into the Teradata Database system, no new CJ or OJ entries are being created for it. After all of the residual CJ processing is completed, the Teradata Database system becomes online. Start the VprocManager utility and check the status of the Teradata Database. The Vproc State and Config Status should appear as Online. At this point, the AMP rejoins the other online AMPs automatically without the need of a Teradata Database system restart. Startup/Restart Messages At startup, messages are displayed to report the startup progress and the Teradata Database system status. This report includes some recovery process messages as shown below: H005 Control AMP /02/06 11:35:31 Running DBS Version: /02/06 11:35:31 Running PDE Version: /02/06 11:35:32 Current DBS config maps are synchronized (Version: 11) 98/02/06 11:35:32 New DBS config maps are synchronized (Version: 11) 98/02/06 11:35:32 AMP 0000 has been selected as the Control AMP 98/02/06 11:35:33 Initializing DBS Vprocs 98/02/06 11:35:36 Configuration is operational 98/02/06 11:35:36 Starting AMP partitions 98/02/06 11:35:40 Connection accepted 98/02/06 11:36:02 Voting for transaction recovery 98/02/06 11:36:05 Recovery session 1 contains 77 rows on AMP /02/06 11:36:16 Starting transaction recovery 98/02/06 11:36:18 Completed transaction recovery 98/02/06 11:36:18 Starting PE partitions 98/02/06 11:37:03 System is operational 98/02/06 11:37:05 Users are logged on 98/02/06 11:37:05 Logons are enabled The following table lists and explains these and other messages. 306 Utilities

307 Chapter 11: Recovery Manager (rcvmanager) Startup/Restart Messages Message #... Means AMP mmmm in cluster nnn is back online 2 - AMP mmmm is in offline catchup 3 - AMP mmmm is in online catchup 4 - AMP mmmm not brought online for the following reason(s): 5 - Completed transaction recovery the specified AMP which was offline is now back online. the AMP is in offline catchup mode. the AMP is in online catchup mode. one of the following: Changed row journal count of ZZ,ZZZ,ZZ9 exceeds 3000 rows. At least one long running ordered journal record remains. At least one HUT lock might exist in the cluster. At least one two-phase-commit transaction is in doubt. Transaction Recovery for online AMPs is compete. 6 - Recovering down AMPs the recovery process is updating tables on AMPs that are in offline catchup. Note: If there was no down AMP in catchup recovery mode, this message is not displayed. 7 - Recovery session 1 contains 103 rows on AMP Starting transaction recovery 9 - Startup will wait for recovery to complete 10 - Voting for transaction recovery that AMP 0001 has the largest number of rows in the transient journal for the given recovery session. Other AMPs probably have a similar or less rows for the same recovery session. The count reflects how many rows were in the transient journal at the time of the Teradata Database system restart. It does not necessarily mean a rollback action has to be performed for each row. transaction recovery has started on online AMPs. the user initiated a COLDWAIT restart. the application software is determining if there were any incomplete transactions left from the previous operation. Voting is a process by which each AMP examines the transactions that were in process. Any uncompleted transaction will have to be rolled back. Utilities 307

308 Chapter 11: Recovery Manager (rcvmanager) Restarts Restarts Automatic Restarts Two types of restarts exist: Automatic User-initiated User-Initiated Restarts When a software or hardware failure occurs, the Teradata Database system automatically attempts to bring itself back up into an operational state. This type of restart results in an automatic execution of a Teradata Database system-recovery operation. As part of the restart processing, the Teradata Database system saves the error codes that were generated, reloads Teradata Database system software, and enables logons. Manual restarts are activated by the user. Users can initiate a restart from any of the hardware switches or by one of the following methods: Issue the RESTART command. For information on the RESTART command, see Vproc Manager Utility in Utilities. At the system command line, type the following command: tpareset comment-string where comment-string briefly describes the reason for the restart. Cancelling Rollback on Tables rcvmanager provides a mechanism to cancel or skip the rollback of specified tables during a Teradata Database system restart or an aborted, online transaction. Cancelling the rollback of long-running transactions and unwanted tables improves the availability of Teradata Database system resources and reduces the Teradata Database system startup time after a crash. When the CANCEL ROLLBACK ON TABLE command is executed for a table, the Teradata Database marks the related table header invalid. Only the rollback pertaining to the specified table in the transaction is cancelled. The rollback processing for the rest of the transaction is not impacted. Note: You cannot cancel rollback on a table that is not in the rollback list. Before issuing the CANCEL ROLLBACK ON TABLE command, you should use the LIST ROLLBACK TABLES command to see which tables are undergoing rollback. You can cancel rollback only on tables that appear in this list. Use the CANCEL ROLLBACK ON TABLE command when one of the following occurs: The rollback of a table is likely to take longer than its restoration. The table, such as a temporary table, is unimportant. 308 Utilities

309 Chapter 11: Recovery Manager (rcvmanager) Cancelling Rollback on Tables Caution: Teradata recommends that you use the CANCEL ROLLBACK ON TABLE command with caution because the target table becomes invalid and unusable after executing this command. Teradata highly recommends that you perform a DELETE ALL operation on the table after cancelling rollback on it. The typical process of cancelling rollback on a table is as follows: 1 The rollback is taking too long. 2 You identify a large table(s) that can be restored faster than the rollback will take. 3 You perform a LIST ROLLBACK TABLES to see which tables are undergoing rollback. 4 You perform a CANCEL ROLLBACK ON TABLE. 5 You perform a DELETE ALL and restore the table(s). The only time that you would not restore the table(s) immediately is if you do not need the table(s). You still should perform a DELETE ALL immediately. You have to know what you are going to do about the invalid table prior to performing the CANCEL ROLLBACK ON TABLE. And you will have to do it immediately to get the Teradata database system back online. You can reuse the table only when one of the following occurs: You drop the table and create it again. You restore the table from an archived backup. You perform a DELETE ALL operation on that table if you do not want to lose the DDL associated with the table. When you issue a DELETE ALL, the partially rolled back rows can be removed, and the table is made usable. Before cancelling rollback on tables, see Usage Rules on page 337. To cancel the rollback on tables, do the following: 1 Start rcvmanager. 2 At the command prompt, type: LIST ROLLBACK TABLES; rcvmanager displays the names and details of the tables undergoing rollback. 3 At the command prompt, type: CANCEL ROLLBACK ON TABLE nnnn:mmmm, nnnn:mmmm,...; The table IDs specified must appear on the rollback list from step 2. rcvmanager displays the following: Type the password for user DBC or press the Enter key to return: Note: You need to specify the DBC password only for the first use of the CANCEL ROLLBACK ON TABLE command in a rcvmanager session. For subsequent use of the command, rcvmanager does not ask for the DBC password. 4 Type the password for user DBC or press the Enter key. If logon fails due to an incorrect password or for some other reason, the following message appears: *** Logon failed *** Utilities 309

310 Chapter 11: Recovery Manager (rcvmanager) Recovery Manager Commands Retrieving Tables Teradata Database returns to the RcvManager command prompt. Repeat step 2 if this occurs. If you successfully logon to the Teradata Database system, the following message appears: Rollback will be cancelled for: mmmm:nnnn "DBname"."TableName" Confirm y/n? For other possible messages, see CANCEL ROLLBACK Messages on page Type Y to confirm. For more information on rollbacks, see the following commands: CANCEL ROLLBACK ON TABLE on page 312 LIST CANCEL ROLLBACK TABLES on page 319 LIST ROLLBACK TABLES on page 322 You can perform a single table retrieve operation on tables whose rollback was cancelled. To do so, use the LOCKING request modifier with the READ OVERRIDE option. You cannot perform update operations (UPDATE, INSERT, DELETE, and MERGE requests) on such tables. For more information, see LOCKING Modifier in SQL Reference: Data Manipulation Statements. Recovery Manager Commands After you start rcvmanager, you are prompted to type commands as shown below: Enter command, QUIT; or HELP; : At the prompt of either your application window or your terminal screen, you can type in any valid rcvmanager command. All rcvmanager commands end with a semicolon. rcvmanager does not process a command until rcvmanager detects a semicolon, even if you press Enter. The following table briefly describes each command. Command CANCEL ROLLBACK ON TABLE DEFAULT PRIORITY HELP Description Cancels rollback processing on tables currently undergoing rollback as part of a Teradata Database system recovery or an online, usertransaction abort. Sets the priorities to the default values. Displays the syntax for the commands supported by rcvmanager. 310 Utilities

311 Chapter 11: Recovery Manager (rcvmanager) Recovery Manager Commands Command LIST CANCEL ROLLBACK TABLES LIST LOCKS LIST ROLLBACK TABLES LIST STATUS QUIT REBUILD/RECOVERY PRIORITY ROLLBACK SESSION... PERFORMANCE GROUP Description Displays a report containing the table-id, database name, and table name of the tables whose rollback processing during an online, user-requested abort or during Teradata Database system recovery is cancelled. Displays all locks currently held by transaction recovery. Displays a report with the names and details of the tables undergoing rollback in the Teradata Database system. Displays transaction recovery information and AMP recovery information for unavailable AMPs or detailed information about the recovery process of a specific AMP. Exits rcvmanager. Sets or displays a priority level for use by the Table Rebuild utility and a Teradata Database system recovery operation. Sets or displays the Performance Group of rollbacks for a specified session. The following sections describe each of the Recovery Manger commands in alphabetical order. Utilities 311

312 Chapter 11: Recovery Manager (rcvmanager) CANCEL ROLLBACK ON TABLE CANCEL ROLLBACK ON TABLE Purpose The CANCEL ROLLBACK ON TABLE command allows you to cancel rollback processing on tables currently undergoing rollback as part of a Teradata Database system recovery or an online, user-transaction abort. Note: Before using CANCLE ROLLBACK ON TABLE, you should use the LIST ROLLBACK TABLES command to obtain the table IDs of tables undergoing rollback. CANCLE ROLLBACK ON TABLE will fail for tables that do not appear on this list. Syntax CANCEL ROLLBACK ON TABLE, table_id ; YsRcv006 where: Syntax element... table_id Specifies... the identifier for the table whose rollback is to be cancelled. This is specified in hexadecimal format. You can specify any number of table_ids by separating them with commas. The table_id must be in the rollback tables list, meaning the table specified must be undergoing rollback. For other rules, see Usage Rules on page 337. Usage Notes Caution: When the CANCEL ROLLBACK ON TABLE command is executed for a table, the Teradata Database marks the related table header invalid. Only the rollback pertaining to the specified table in the transaction is cancelled. The rollback processing for the rest of the transaction is not impacted. Use the CANCEL ROLLBACK ON TABLE command when one of the following occurs: The rollback of a table is likely to take longer than its restoration. The table, such as a temporary table, is unimportant. Teradata recommends that you use the CANCEL ROLLBACK ON TABLE command with caution because the target table becomes invalid and unusable after executing this command. 312 Utilities

313 Chapter 11: Recovery Manager (rcvmanager) CANCEL ROLLBACK ON TABLE Teradata highly recommends that you perform a DELETE ALL operation on the table after cancelling rollback on it. The typical process of cancelling rollback on a table is as follows: 1 The rollback is taking too long. 2 You identify a large table(s) that can be restored faster than the rollback will take. 3 You perform a LIST ROLLBACK TABLES to see which tables are undergoing rollback. 4 You perform a CANCEL ROLLBACK ON TABLE. Note: You can cancel rollbacks only on tables whose IDs appear on the rollback list from step 3. 5 You perform a DELETE ALL and restore the table(s). The only time that you would not restore the table(s) immediately is if you do not need the table(s). You still should perform a DELETE ALL immediately. You have to know what you are going to do about the invalid table prior to performing the CANCEL ROLLBACK ON TABLE. And you will have to do it immediately to get the Teradata database system back online. You can reuse the table only when one of the following occurs: You drop the table and create it again. You restore the table from an archived backup. You perform a DELETE ALL operation on that table if you do not want to lose the DDL associated with the table. When you issue a DELETE ALL, the partially rolled back rows can be removed, and the table is made usable. Upon specifying the CANCEL ROLLBACK ON TABLE command for the first time in a rcvmanager session, you are prompted to type the password for user DBC. Although any user can execute this command, the DBC password is required. This is a built-in safeguard to restrict the use of the feature. This command is not instantaneous. It takes effect after reading the Transient Journal (TJ) rows for all the tables specified with the command. You can cancel the rollback on a table even after a part of the transaction rollback is complete on that table. The priority level in effect during a rollback also applies to the aborting of rollback. Usage Rules The following table lists the usage rules that apply to the CANCEL ROLLBACK ON TABLE command. Utilities 313

314 Chapter 11: Recovery Manager (rcvmanager) CANCEL ROLLBACK ON TABLE Rule The table-id specified with the CANCEL ROLLBACK ON TABLE command must exist in the rollback tables list, meaning the table must have been marked for rollback. You can specify any number of tables for cancelling rollback. rcvmanager verifies each table-id. If some of these tables do not exist in the rollback list, rcvmanager reports error messages for the non-existing tables and asks for a single confirmation for cancelling rollback on all the valid tables. Example Example 1: Valid Command Assume that the table with table-id 6712 exists. > CANCEL ROLLBACK ON TABLE 0:6712; Type the password for user DBC or press the Enter key to return: > dbc Rollback will be cancelled for: 0000:6712 "EmployeeDB"."LogTable" Confirm y/n? > y rcvmanager cancels rollback on LogTable. Example 2: Invalid Command Assume that the table with table-id 6708 does not exist in the rollback list. > CANCEL ROLLBACK ON TABLE 0:6708; Table 0:6708 does not exist in rollback list. Enter command, "QUIT;" or "HELP;" : rcvmanager has ignored the command because the table does not exist. You cannot cancel rollback on tables that have any referential integrity constraints. Note: An exception to this rule is the self-referencing table. The table-ids of all referenced and referencing tables are marked with an asterisk (*) in the rollback list generated by the LIST ROLLBACK TABLES command. When you specify multiple tables in the CANCEL ROLLBACK ON TABLE command, rcvmanager verifies each table for referential integrity constraints. If the tables specified for cancelling rollback are associated with join or hash indexes, then rcvmanager lists all such tables and asks for a single confirmation. Upon confirmation (y), the tables, as well as the associated join and hash indexes, are marked as invalid. When you specify multiple tables with the CANCEL ROLLBACK ON TABLE command, and some tables have join or hash indexes and some have errors, then rcvmanager asks for a single confirmation for all the valid tables. Assume three tables T1 (table-id 6710), T2 (table-id 6711) and T3 (table-id 6712) exist in a rollback list, and T2 has a foreign key referencing T1. Assume that T3 has only a selfreference and no constraints that reference other tables. > CANCEL ROLLBACK ON TABLE 0:6710; Entry ignored as table 0:6710 has referential integrity constraint. Enter command, "QUIT;" or "HELP;" : > CANCEL ROLLBACK ON TABLE 0:6711; Entry ignored as table 0:6711 has referential integrity constraint. Enter command, "QUIT;" or "HELP;" : > CANCEL ROLLBACK ON TABLE 0:6712; Rollback will be cancelled for: 0000:6712 "SG"."T3" Confirm y/n? > y rcvmanager cancels rollback only on table T3. Assume that Temp_Table with table-id 6707 is associated with a join index. > CANCEL ROLLBACK ON TABLE 0:6707; Rollback will be cancelled for: 0000:6707 "EmployeeDB"."Temp_Table" The following join and/or hash indexes will be invalidated: "EmployeeDB"."Sal_Join" Confirm y/n? > y 314 Utilities

315 Chapter 11: Recovery Manager (rcvmanager) CANCEL ROLLBACK ON TABLE Rule If the table-id specified with the CANCEL ROLLBACK ON TABLE command was specified previously or more than once in the same command, then rcvmanager reports a message indicating a duplicate entry. When you cancel rollback on a table, it becomes invalid and unavailable for any subsequent transactions. If any user attempts an update on such tables, then the following message appears: "Invalid operation on table table-name." Example Assume that a rollback was cancelled previously on table-id > CANCEL ROLLBACK ON TABLE 0:6712; The following message appears: Table 0:6712 already on the cancel rollback list, input ignored. Enter command, "QUIT;" or "HELP;" In the following example, the INSERT into LogTable fails because rollback on the table was cancelled earlier, and the table is invalid. BTEQ -- Enter your DBC/SQL request or BTEQ command: INSERT INTO EmployeeDB.LogTable; *** Failure 5792 Invalid operation on table 'LogTable'. Statement# 1, Info =0 *** Total elapsed time was 1 second. CANCEL ROLLBACK Messages One or more of the following messages can appear for each table specified with the CANCEL ROLLBACK ON TABLE command, depending on the nature and status of the table: Rollback will be cancelled for: nnnn:mmmm "DBname"."Tablename" Confirm y/n? Table nnnn:mmmm does not exist in rollback list. Table nnnn:mmmm already on the cancel rollback list, input ignored. The following join and/or hash indexes will be invalidated: "DBName"."Join_IndexName" Entry ignored as table nnnn:mmmm has referential integrity constraint. Valid Operations on Rollback-Cancelled Tables Cancelling rollback on a table makes data in the table invalid and unusable. Only the following operations are valid on the tables on which CANCEL ROLLBACK ON TABLE is performed. Utilities 315

316 Chapter 11: Recovery Manager (rcvmanager) CANCEL ROLLBACK ON TABLE To... Use the... delete all the rows in the table and make it valid again drop the table so that you can create it again retrieve a single table for SELECT operations restore the table from an archive using ARC utility take a dump of the table using ARC utility rebuild the table headers DELETE statement with the ALL option. DROP TABLE statement. LOCKING request modifier with the READ OVERRIDE option. RESTORE command. DUMP command. Table Rebuild utility. Note: CheckTable utility skips checking on tables whose rollback you cancel. 316 Utilities

317 Chapter 11: Recovery Manager (rcvmanager) DEFAULT PRIORITY DEFAULT PRIORITY Purpose The DEFAULT PRIORITY command sets the priorities to the default values (that is, REBUILD will be set to MEDIUM and RECOVERY to LOW). Syntax DEFAULT PRIORITY ; GS04A035 Usage Notes If the PRIORITY command has never been executed or a SYSINIT has been performed on the Teradata Database system, the priorities are set to the default values. The priority remains the same until an initial or subsequent PRIORITY command changes it again. When the priority command is entered during a rebuild or recovery operation, several minutes may elapse before the new priorities take effect. When you type the DEFAULT PRIORITY command, the event is logged in the /var/adm/ streams/error.mm-dd file in the Teradata Database system you are working on, and the following messages are displayed. YY/MM/DD HH:MM:SS RECOVERY priority changed to LOW; it was <old priority> YY/MM/DD HH:MM:SS REBUILD priority changed to MEDIUM; it was <old priority> When the default priority command is entered, both messages are generated. Utilities 317

318 Chapter 11: Recovery Manager (rcvmanager) HELP HELP Purpose The HELP command displays the syntax for the commands supported by rcvmanager. Syntax HELP ; GT11A001 Example The HELP command displays information for all the rcvmanager commands: RCVMANAGER provides a means for the user to interact with the recovery sub-system. The syntax of an RCVMANAGER command is: HELP; QUIT; { STATUS [<proc-id>] } { LOCKS } LIST { ROLLBACK TABLES } { CANCEL ROLLBACK TABLES }; { REBUILD } [ Low ] { } PRIORITY [ Medium ] ; { RECOVERY } [ High ] DEFAULT PRIORITY; CANCEL ROLLBACK ON TABLE <table-id> [{,<table-id>}...] ; ROLLBACK SESSION <host>, <session> PERFORMANCE GROUP [<Perf Group Name>] ; Where <Perf Group Name> is the name of a Performance Group. The HELP command displays this help message text. The QUIT command will terminate the RcvManager Utility Utilities

319 Chapter 11: Recovery Manager (rcvmanager) LIST CANCEL ROLLBACK TABLES LIST CANCEL ROLLBACK TABLES Purpose The LIST CANCEL ROLLBACK TABLES command displays a report containing the table-id, database name, and table name of the tables whose rollback processing during an online, userrequested abort or during Teradata Database system recovery is cancelled. Syntax LIST CANCEL ROLLBACK TABLES ; 1102A046 where: Syntax element... Specifies... CANCEL ROLLBACK TABLES to display the list of tables upon which rollback is cancelled. Usage Notes Example This report lists all the tables for which rollback is being cancelled, as the process of cancellation of rollback is not instantaneous. The report is in alphabetical order, by the database name and table name. Note: The LIST ROLLBACK TABLES command report does not include invalid tables, that is, tables on which rollback is being cancelled. Therefore, if all the tables in a session have been specified for rollback cancellation, they appear only in the output of the LIST CANCEL ROLLBACK TABLES command. If no tables on which rollback is cancelled exist, then only the column headings are displayed. The following is sample output of the LIST CANCEL ROLLBACK TABLES command. PENDING CANCEL ROLLBACK TABLES AT 03:02:25 01/11/15 Table ID Name :6707 "Department"."Dept_Details" 0000:6712 "Department"."Temp_Table" Utilities 319

320 Chapter 11: Recovery Manager (rcvmanager) LIST LOCKS LIST LOCKS Purpose The LIST LOCKS command displays all locks currently held by transaction recovery. Syntax LIST LOCKS ; 1102A047 where: Syntax element... Specifies... LOCKS to displays locks held by online transaction recovery. Usage Notes Example The report displays the mode of the lock held (write or exclusive), the object type locked (database, table, row range, or row hash) and the name of the object. The report is sorted alphabetically by object name. For row range and row hash locks, the row information does not display. Only the table within which the row resides is displayed. If rcvmanager is unable to determine the database name associated with an object, rcvmanager displays the database ID in decimal and hex. The same is true if the table name cannot be determined. LIST LOCKS displays only those locks currently held by transaction recovery. You cannot display locks held by online catchup or offline catchup. Only a single report is generated by the LIST LOCKS command. An example of this report is shown below: LOCKS HELD BY ONLINE TRANSACTION RECOVERY at 02:29:16 04/06/16 Lock Lock Object Mode Object Name Write Database "AssetsDB" Write Row hash "Clients"."TurnOver" Write Row hash "EmployeeInfo"."NewHires" 320 Utilities

321 Chapter 11: Recovery Manager (rcvmanager) LIST LOCKS Exclusive Row hash Exclusive Table "SampleDB"."pseudo table" "SampleDB"."SampleTable" Utilities 321

322 Chapter 11: Recovery Manager (rcvmanager) LIST ROLLBACK TABLES LIST ROLLBACK TABLES Purpose The LIST ROLLBACK TABLES command displays a report with the names and details of the tables undergoing rollback in the Teradata Database system. Syntax LIST ROLLBACK TABLES ; 1102A048 where: Syntax element... Specifies... ROLLBACK TABLES to display the list of tables undergoing rollback in the Teradata Database system. Usage Notes The tables undergoing rollback must satisfy the following criteria: The table in a transaction must have more than rows yet to rollback on at least one AMP. The transaction must be in abort status. The report displays only the headings if no rollback is in progress in the Teradata Database system, or if no table satisfies these criteria. The list is in descending order of the Host and Session, and then in alphabetical order by the database name and table name. The list excludes DBC tables and Permanent Journal (PJ) tables. An asterisk (*) appears after the table name if the table has any Referential Integrity constraints. You cannot cancel rollback on such tables. Table names having non-printable characters are displayed in hexadecimal. 322 Utilities

323 Chapter 11: Recovery Manager (rcvmanager) LIST ROLLBACK TABLES The list is in two parts, as shown in the following table. Note: Global Temporary tables and Volatile tables are not listed. This part... online user rollback tables system recovery rollback tables Displays a list of tables in the sessions that are undergoing rollback as part of... user-requested abort. Teradata Database system recovery. The following table explains what information the report columns provide: Column... Host Session User ID Performance Group AMP W/Count TJ Rows Left TJ Row Count TJ Rows Done Time Est. Specifies the... ID of the host machine. session number in which rollback is in progress. ID of the user who has initiated the session. Performance Group associated with the session. This determines the priority at which all transactions in the session perform. See also ROLLBACK SESSION...PERFORMANCE GROUP on page 336. AMP on which the maximum number of Transient Journal rows are left to be processed. maximum number of rows left to be processed in the Transient Journal for the specific session on any AMP. number of rows processed in the Transient Journal for the specific session. estimated time (in hours and minutes) left for the rollback to complete for that session. Example The following is a sample output of the LIST ROLLBACK TABLES command. TABLES BEING ROLLED BACK AT 14:25:34 02/11/15 ONLINE USER ROLLBACK TABLE LIST Host Session User ID Performance Group AMP W/Count :0481 M 1 TJ Rows Left TJ Rows Done Time Est ,478 1,098 01:37 Utilities 323

324 Chapter 11: Recovery Manager (rcvmanager) LIST ROLLBACK TABLES Table ID Name :3883 "rcv_user1"."cr_in001" 0000:388B "rcv_user1"."cr_in002" 0000:3884 "rcv_user1"."cr_ri001"* 0000:3889 "rcv_user1"."cr_ri002"* SYSTEM RECOVERY ROLLBACK TABLE LIST Host Session TJ Row Count ,032 Table ID Name :045A "EmployeeDB"."Parent_Table"* 0005:045B "EmployeeDB"."Temp_Table" * - Referential Integrity table, cannot be used in CANCEL ROLLBACK ON TABLE command. 324 Utilities

325 Chapter 11: Recovery Manager (rcvmanager) LIST STATUS LIST STATUS Purpose The LIST STATUS command generates two reports: Online Transaction Recovery Journal Counts Down/Catchup AMP Recovery Status The first reports transaction recovery information, and the second reports AMP recovery information for unavailable AMPs. Syntax LIST STATUS ; 1102A049 where: Syntax element... Provides... STATUS transaction recovery information and AMP recovery information for unavailable AMPS. The displayed row count of a large sized table will be rounded to the nearest thousand. The recovery build records specify rebuild operations separately for each index of a table, which causes a rebuild of both the primary and fallback data for that index. Hence, the displayed sector count is not the total size for the table as derived from other methods. The sector count that is displayed is the sum of the estimated number of sectors for both primary and fallback rows to be copied over from the other AMPs in the cluster or recreated Non Unique Secondary Index (NUSI) indexes for all index subtables of the table which have an OJ build record. This includes the OJ build records of both the current pass and the next pass. Online Transaction Recovery Journal Counts The Online Transaction Recovery Journal Counts allows the user to monitor transaction recovery processing. It displays information on the transient journal and transactions that were in progress during transaction recovery processing. Utilities 325

326 Chapter 11: Recovery Manager (rcvmanager) LIST STATUS Report Information Example This report displays a list of all active recovery sessions and the maximum number of transaction journal rows remaining to be processed for the AMP that has this maximum count. Since all AMPs must complete processing of a given recovery session before the processing of the next session begins, this information is sufficient to calculate the worst-case count of transaction journal entries to be scanned. You can use this count as a rough guide to recovery processing time. However, because this is only a rough guide, you must also take into consideration the following variables when estimating the time involved in the recovery process: The amount of work required by recovery to process a given transaction journal row can vary by orders of magnitude; that is, some rows can be processed in a fraction of a second, whereas others can take hours to process. The transaction journal may contain many rows which require no recovery processing. The online transaction recovery journal counts are updated by each AMP every time a checkpoint is taken. Thus, every time an AMP performs checkpoint, its online transaction recovery journal count is decreased by 1000, and a later LIST STATUS command may display different results. If no recovery sessions are active, the report title is printed without any contents. ONLINE TRANSACTION RECOVERY JOURNAL COUNTS at 13:49:28 98/02/06 Recovery AMP Session Count W/Count , , Note: A new recovery session is created for each restart that is not a COLDWAIT restart. Down/Catchup AMP Recovery Status The example report contains three sets of data lines (together with a column header) for each AMP participating in the down AMP recovery process. The first data line is explained by the column headers. The second and third data lines indicate the status. The following table describes the Header and first-line data. 326 Utilities

327 Chapter 11: Recovery Manager (rcvmanager) LIST STATUS Data AMP to be caught up Description Indicates the AMP number to be caught up. In addition to the processor number, this column might contain one of the following notations: Notation... Indicates that... * this AMP may be placed in online catchup if the Teradata Database system restarts. If the displayed information is no longer valid by the time the Teradata Database system restarts, the AMP might remain in offline catchup. [1] one or more host utility locks are held in the cluster of the recovering AMP and that the data on the AMP cannot be recovered because there is a conflict between the host utility lock and the recovery locking requirements. [2] one or more 2 Phase Commit (2PC) in-doubt sessions exist within the cluster of the recovering AMP. Pass Current Pass Next Pass Indicates the number of the recovery pass. At the beginning of a recovery pass all rows in the OJ and CJ are extracted. This is the total number of rows to be processed during that pass. If additional changes are sent to the AMP during the processing of the current pass, they are queued up for the next pass. When the processing of rows of the current pass is complete, the pass number is incremented and the rows for the next pass are extracted from the OJ and CJ and processed. The OJ column contains the number of rows in the ordered Teradata Database system change journal to be processed during the current recovery pass. The CJ column contains the number of rows in the changed row journal to be processed during the current recovery pass. The OJ column contains the number of rows in the ordered Teradata Database system change journal to be processed during the next recovery pass. The CJ column contains the number of rows in the changed row journal to be processed during the next recovery pass. If there are transactions that are updating user tables, these counts will go up as a result of those updated transactions. Subsequent displays could show an increase in the count. The following table describes the second data line (AMP Status). Data Online Catchup Description This AMP is online during recovery processing and accepts new work. Locks are applied against all objects that need to be updated before new work is accepted. In this status, the OJ count is usually zero and no new OJ or CJ entries are created. Utilities 327

328 Chapter 11: Recovery Manager (rcvmanager) LIST STATUS Data Offline Catchup Not In Recovery Description This AMP is logically (not physically) offline during recovery processing. No new work is accepted by this AMP. Read locks are applied on the online AMPs in the cluster only against the specific data of an object that has to be updated. This AMP is not running down AMP recovery; it is physically offline. The following table describes the third data line (AMP Recovery Status Line). Data Transaction Recovery: ZZZ,ZZZ,ZZ9 TJ Rows Rebuilding Table [DBase.Table]: Z9% complete in this pass Change Row Recovery: Z9% complete in this pass Between Passes Miscellaneous OJ Processing Down Not currently executing recovery Description Specifies the number of rows in the transaction recovery journal to be processed in this recovery pass. The transaction recovery journal contains the before images of all change objects affected by every transaction. Transaction recovery is the first step of the first recovery pass only. Each Z represents a digit and 9 represents any non-zero value. Specifies the name of the table being rebuilt and the percentage of completion. Tables are rebuilt as a result of DDL changes (that is, drop or add a column) to a table, or a Multiload operation has affected a table while an AMP was down. This is caused by DML changes to the tables. This step of recovery is entered when DML (for example insert update, or delete) changes have been made to tables in a down AMP. While an AMP is down, the other AMPs in the cluster modify their fallback rows for the down AMP, and also modify their own rows for which the down AMP has fallback responsibility. The state of between passes arises since there is a five minute pause between passes. Primarily, this is intended to allow current operations, including any new work creating CJ and OJ entries, to finish and release their locks, so that recovery will not compete with online operations. Indicates that time is spent processing the various short running OJ entries, for example, releasing host utility locks. Indicates that this AMP is not involved in the recovery process. However, statistics are maintained to indicate how much accumulated work remains to be recovered before the AMP can become operational. Indicates that the AMP has not yet reached the point of starting Transaction Recovery or extracting OJ logs. The AMP is neither at the very early stage in recovery or has not yet started it. (The AMP might be down.) Example The Down AMP Recovery Status report generates the information shown in the following screen example. 328 Utilities

329 Chapter 11: Recovery Manager (rcvmanager) LIST STATUS DOWN AMP RECOVERY STATUS AT 12:27:25 99/10/13 AMP to be Current Pass Next Pass caught up Pass OJ CJ OJ CJ ,531 - AMP Status: Not in recovery - Down Utilities 329

330 Chapter 11: Recovery Manager (rcvmanager) LIST STATUS proc-id LIST STATUS proc-id Purpose The LIST STATUS command with the proc-id option specified as mmmm provides additional detailed information about the recovery process of a specific AMP. Syntax LIST STATUS ; proc-id 1102A060 where: Syntax element... Provides... STATUS proc-id transaction recovery information and AMP recovery information for unavailable AMPs. The displayed row count of a large sized table will be rounded to the nearest thousand. The recovery build records specify rebuild operations separately for each index of a table, which causes a rebuild of both the primary and fallback data for that index. Hence, the displayed sector count is not the total size for the table as derived from other methods. The sector count that is displayed is the sum of the estimated number of sectors for both primary and fallback rows to be copied over from the other AMPs in the cluster or recreated Non Unique Secondary Index (NUSI) indexes for all index subtables of the table which have an OJ build record. This includes the OJ build records of both the current pass and the next pass. additional detailed information about the recovery process of a specific AMP including the list of tables needing to be rebuilt. The LIST STATUS proc-id option is only allowed for processors that are in down AMP recovery (offline catchup) or the AMPs listed in the LIST STATUS display. No additional detail information is provided for AMPs that are in online catchup, since no build records exist for these AMPs. 330 Utilities

331 Chapter 11: Recovery Manager (rcvmanager) LIST STATUS proc-id Usage Notes The following additional information is reported: Status Pass number Current pass count Next pass count A list of tables that need to be rebuilt, which also includes the following information: Total rows Total bytes Rebuild speed in bytes per second Estimated rebuild time Note: All tables that need to be rebuilt will display in the list. The tables for which an OJ build record exists An estimated sector count of that table The LIST STATUS proc-id command is only allowed for processors that are in down AMP recovery (offline catchup), or the AMPs listed in the LIST STATUS display. No additional detail information is provided for AMPs that are in online catchup since no build records exist for these AMPs. The following table shows the information contained in the columns under the TABLES TO BE REBUILT report. Data Row Count Status Description The number of rows in the table to be rebuilt. Displays up to six possible states where the recovery process may be when LIST STATUS proc-id is executed. The possible values in this column can be the following: Value Blank Multiload Target Table in Apply Locked Description Indicates that the table might be or will be rebuilt. Indicates that the table is a target table of a MultiLoad job. In this case the OJ build record is discarded since the likelihood is that the AMP will be online before the MultiLoad job finishes. If this is the case, MultiLoad will force a rebuild of the table while the AMP is online. If the MultiLoad job completes before the AMP is online, a new OJ build record is generated, meaning the rebuild will occur in a later pass. Indicates that the table is currently locked by an EXCLUSIVE lock and that a valid sector count cannot be taken. Unless the lock is part of a drop table operation, the table will eventually be rebuilt in the next pass. Utilities 331

332 Chapter 11: Recovery Manager (rcvmanager) LIST STATUS proc-id Data Description Status (continued) Non-Fallbacked Indicates that a non-fallback table has been marked for a rebuild operation. Since all non-fallback tables are deleted during rebuild operation, the sector count associated with this table is meaningless. Table Rebuild Restore Indicates that this OJ build record is for a table that is currently being rebuilt. This OJ build record will be discarded. Indicates that a table may have an OJ build record for it, but it is currently the target of a (not necessarily active) restore operation. In this case, the OJ build record is discarded. Name The number of rows in the table to be rebuilt. Note: If the LIST STATUS proc-id command is executed while creating an index on a table that is to be rebuilt, then the time to rebuild the index is not added to the estimated rebuild time for that table. Example 1 This example shows a typical down AMP recovery status report, which displays the total rows, total bytes, and the rebuild speed in bytes per second. DOWN AMP RECOVERY STATUS AT 12:27:25 99/10/13 AMP to be Current Pass Next Pass caught up Pass OJ CJ OJ CJ ,531 - AMP Status: Not in recovery - Down TABLES TO BE REBUILT Row Count Status Name ,598 "RESCRIBE"."Rescribe11" 897,598 "RESCRIBE"."Rescribe12" 897,598 "RESCRIBE"."Rescribe13" 897,598 "RESCRIBE"."Rescribe14" ,590,392 total rows. 2,582,240KB total bytes. 7,680KB is the rebuild speed in bytes per second. The estimated rebuild time is 5.60 minutes. 332 Utilities

333 Chapter 11: Recovery Manager (rcvmanager) LIST STATUS proc-id Example 2 This example shows the output returned when the first table rebuild has not completed and an estimate rebuild time cannot be given due to insufficient data. TABLES TO BE REBUILT Row Count Status Name ,216 "RESCRIBE"."Rescribe10" 161,216 "RESCRIBE"."Rescribe30" 161,216 "RESCRIBE"."Rescribe20" 161,216 "RESCRIBE"."Rescribe12" 161,216 "RESCRIBE"."Rescribe32" 161,216 "RESCRIBE"."Rescribe22" 161,216 "RESCRIBE"."Rescribe14" ,128,512 total rows. There is insufficient data to estimate the rebuild time. Utilities 333

334 Chapter 11: Recovery Manager (rcvmanager) QUIT QUIT Purpose The QUIT command exits rcvmanager. Syntax QUIT ; GT11A004 Usage Notes You can only type this command when rcvmanager is prompting for a command. You cannot abort a rcvmanager command in progress. 334 Utilities

335 Chapter 11: Recovery Manager (rcvmanager) REBUILD/RECOVERY PRIORITY REBUILD/RECOVERY PRIORITY Purpose The REBUILD/RECOVERY PRIORITY command sets or displays a priority level for use by the Table Rebuild utility and a Teradata Database system recovery operation. Syntax REBUILD RECOVERY PRIORITY HIGH MEDIUM LOW ; GT11A005 Usage Notes Setting a priority will apply to future and currently running operations. The PRIORITY command takes the following forms. Both priorities are independent of each other and can hold different values at any period of time. That is, recovery initiated rebuilds will use recovery priority and not rebuild priority. If you type the command without specifying high, medium, or low, the current priority setting is displayed. The REBUILD PRIORITY command applies to any Table Rebuild started from the console, automatic table rebuild due to disk error recovery, and MLOAD rebuild of target tables for non-participant online AMPs. The REBUILD PRIORITY command sets a priority for the rebuild utility. You can select HIGH, MEDIUM, or LOW level priority. If you do not explicitly set a priority, default rates exist and will be used. If you do not type a new priority, the current priority setting is displayed. The RECOVERY PRIORITY command sets a priority for the Teradata Database system recovery operation. You can select HIGH, MEDIUM, OR LOW level priority. If you do not explicitly set a priority, the current priority setting is displayed. The priority settings are saved in the Recovery Status system table. Utilities 335

336 Chapter 11: Recovery Manager (rcvmanager) ROLLBACK SESSION...PERFORMANCE GROUP ROLLBACK SESSION...PERFORMANCE GROUP Purpose The ROLLBACK SESSION... PERFORMANCE GROUP command sets or displays the Performance Group of rollbacks for a specified session. Syntax ROLLBACK SESSION host_id,session_id A A PERFORMANCE GROUP Perf_Group_Name ; 1102A140 where: Syntax element... Specifies the... host_id session _id Perf_Group_Name identifiers for the host and session whose Performance Group you want to see or set. You must specify both these identifiers in the order mentioned: host_id followed by a comma and session _id. The session _id maximum is The session _id must be in the rollback list, that is, at least one of the tables in the LIST ROLLBACK TABLES list must be from the session specified. For other rules, see Usage Rules on page 337. name of a Performance Group whose priority level you want to apply to rollback operations in the specified session. (Optional) The Teradata Database system will execute rollbacks in the specified session at the priority level associated with this Performance Group. You can specify one of the pre-defined Performance Groups: L (low), M (medium), H (high) or R (rush). The default priority is R. Any Performance Group other than these has to be explicitly defined for usage. If you do not specify a Perf_Group_Name, then the current Performance Group of the session is displayed. For details on Performance Groups, see Chapter 6: Priority Scheduler (schmon, xschmon). 336 Utilities

337 Chapter 11: Recovery Manager (rcvmanager) ROLLBACK SESSION...PERFORMANCE GROUP Usage Notes Rollback processing runs at the priority defined for the session, that is, the priority associated with the Performance Group for the session. If no priority is specified, rollback runs at R priority by default. The ROLLBACK SESSION... PERFORMANCE GROUP command allows you to change the priority. By reducing the priority of less important rollbacks, you can increase the Teradata Database system resource availability for other processes in the Teradata Database system. The ROLLBACK SESSION... PERFORMANCE GROUP command affects the Performance Group and priority only for the rollback process, not for the user session. If the DBS Control General field RollbackPriority is set to TRUE, the rollback process runs with the priority with which the recent request of the transaction was submitted. Here the ROLLBACK SESSION... PERFORMANCE GROUP command can override the DBS Control Rollback Priority field setting and change the priority of the rollback at any point of time. Usage Rules The following usage rules apply to the ROLLBACK SESSION... PERFORMANCE GROUP command: Rule The host-id and the session-id specified with the ROLLBACK SESSION...PERFORMANCE GROUP command must be in the rollback tables list generated by the LIST ROLLBACK TABLES command from rcvmanager. This indicates that rollback is in progress in that session. You either can display or change the Performance Group. If you specify a host-id or a session-id that does not exist in the rollback list, rcvmanager displays a message, and the command is ignored. If you do not specify a Performance Group with the ROLLBACK SESSION... PERFORMANCE GROUP command, then the output displays the current Performance Group setting for the specified host-id and session-id. Example Example 1: Valid Command The Performance Group H specified in the following command takes effect for the named host-id and session-id. > ROLLBACK SESSION 52, 1664 PERFORMANCE GROUP H; ROLLBACK SESSION PERFORMANCE GROUP command completed successfully. Example 2: Non-valid Command The following command does not take effect because the host-id and session-id are not in the rollback list and are not valid. > ROLLBACK SESSION 1, 1005 PERFORMANCE GROUP; No rollback in progress in host 1, session Enter command, "QUIT;" or "HELP;" In this example, no new Performance Group name is specified. rcvmanager displays the current Performance Group for the session. > ROLLBACK SESSION 52, 1664 PERFORMANCE GROUP; Current rollback Performance Group for host 52 session 1664 is M. Utilities 337

338 Chapter 11: Recovery Manager (rcvmanager) ROLLBACK SESSION...PERFORMANCE GROUP Rule When you execute the ROLLBACK SESSION... PERFORMANCE GROUP command, an event is logged in the Teradata Database system, even if the specified Performance Group is the same as the current Performance Group. If you specify an invalid Performance Group name, no event is logged. Note: On Windows, you can view the updated event log using the Event Viewer application. When you specify a user-defined Performance Group name, the equivalent priority for that Performance Group is obtained to change the priority of the rollback for the specified host-id and session-id. If the specified Performance Group is not valid, rcvmanager reports a message, and the command is ignored. Example The following example displays the event log entry after successful execution of the rcvmanager command. > ROLLBACK SESSION 52, 1664 PERFORMANCE GROUP H; ROLLBACK SESSION PERFORMANCE GROUP command completed successfully. 02/01/31 15:34:28 Rollback Performance Group for 52, 1664 changed to H; it was M. In this example, the Performance Group name is not valid. > ROLLBACK SESSION 52, 1664 Performance Group InvPrfGrp; The specified Performance Group name is invalid. Enter command, "QUIT;" or "HELP;" : 338 Utilities

339 CHAPTER 12 Resource Check Tools (dbschk, nodecheck, syscheck) Resource Check Tools are designed to assist in the following: Identifying a slowdown or hang of Teradata Database Providing Teradata Database system statistics to help you determine the cause of the slow down or hang Audience Users of Resource Check Tools include the following: Field engineers Teradata Database system administrators Teradata Support Center personnel Resource Check Tools Utilities Resource Check Tools include several components, as shown in the following table. Component dbschk nodecheck syscheck syscheckrc Description A standalone tool that monitors the Teradata Database response time. A standalone tool that displays local, node-level resources only. Provides summary data to syscheck for analysis or provides detailed output to the nodecheck log file, which is used later for analysis when called from syscheck. A standalone tool that analyzes relevant Teradata Database system data from the local node. A file containing user-defined parameters for syscheck and nodecheck. These parameters specify alert and warn threshold levels for evaluating system performance. Utilities 339

340 Chapter 12: Resource Check Tools (dbschk, nodecheck, syscheck) dbschk dbschk Purpose dbschk monitors Teradata Database response time. If the response time indicates the database is slow or unresponsive, dbschk runs a specified program or script, and logs an event. The factory default settings for dbschk options can be changed using command-line options. Settings specified on the command line can be optionally saved as new default settings for dbschk. New defaults persist across sessions, and are propagated to all nodes of MPP systems. The -reset option restores the factory default settings. Syntax dbschk -h -l -reset -delay sleep_seconds -job job_program -logfile file -logflush flush_seconds -n iterations -power switch -rate attempts -save -timeout wait_seconds -trigger trigger_program 1102C141 where: Syntax element... -delay sleep_seconds Description Sets the time that dbschk waits between successful executions of the all-amp requests to Teradata Database. sleep_seconds in a positive integer that specifies the number of seconds dbschk waits. The factory default is 1200 seconds. Note: Setting a very low value for -delay can adversely affect system performance. -h Displays a short description of dbschk and the command-line options. 340 Utilities

341 Chapter 12: Resource Check Tools (dbschk, nodecheck, syscheck) dbschk Syntax element... -job job_program Description Specifies the program or script dbschk runs to check Teradata Database response time. The specified program or script should generate an all-amp request. Note: job_program should specify the complete path to the program or script, and any optional command-line parameters you wish to use to start the program. If job_options includes any space characters, enclose the entire job_options specification within double-quotes. Default dbschk settings are used by all nodes of MPP systems. If you use the -save option to store the current -job setting as a custom default, ensure that the specified program or script exists on all nodes. -l Displays the current default and factory default dbschk settings. The current default settings are used when dbschk is run with no command-line options. -logfile file -logflush flush_seconds Specifies log file dbschk will use. All dbschk program output is directed to this file. If the file does not exist, dbschk will create it. Note: file should specify the complete path to the log file. If the path includes any space characters (for example, Program Files ), enclose the entire file specification within double-quotes. To have dbschk output displayed on screen, specify file as stdout. If you do not specify a -logfile on the command line, dbschk will use the file specified as the current default logfile. Use the -l option to see the current dbschk default values. The factory default log file locations are listed below. MP-RAS: /tmp/dbschk.log Linux: /var/opt/teradata/tdtemp/dbschk.log Windows: \Program Files\NCR\Tdat\TdTemp\dbschk.log Note: Instances of dbschk log to the logfile that is in effect when they are started. Multiple instances of dbschk can share the same log, or use different logs. For example, an instance of dbschk can be started automatically when Teradata Database starts and set to log to a file, while other instances of dbschk can be run from the command-line using the -logfile option to have the dbschk output directed to the screen (stdout). Specifies the time after which the log file is flushed and overwritten with new output from dbschk. flush_time is a positive integer that specifies the number of seconds between log flushes. The factory default is 3600 seconds. Note: Setting a very low a value for -logflush can adversely affect system performance. Setting a very high value can result in a very large log file. Utilities 341

342 Chapter 12: Resource Check Tools (dbschk, nodecheck, syscheck) dbschk Syntax element... Description -n iterations Specifies the number of times dbschk runs. If -n is not specified, dbschk runs continuously until stopped by the user. iterations is a positive integer greater than zero. -power switch -rate attempts -reset -save -timeout wait_seconds Determines whether dbschk can run. switch can be OFF or ON. OFF prevents dbschk from running both from the command line and automatically the next time Teradata Database starts. This is the default. ON allows dbschk to run from the command-line. If the -save option is used to make ON the new default -power setting, dbschk will be started automatically whenever Teradata Database starts. OFF and ON can be entered in upper, lower, or mixed case. 0 can be used as a substitute for OFF, and 1 can be used as a synonym for ON. Specifies the number of times that dbschk executes an all-amp request and waits for a response before running the program specified by the -trigger parameter. attempts is a positive integer. The factory default is 5. Restores the dbschk factory default settings. To see the factory default settings, use the -l option. Note: The default dbschk settings are global to the system. They are used when dbschk is run from any node of MPP system. Saves the settings that are specified on the command line as new default values for subsequent runs of dbschk from any node of the system. If the -save parameter is not specified on the command line, other command-line parameters are only in effect for the current run of dbschk. When -save is included on the command-line, dbschk does not check database responsiveness, but instead only saves the current commandline settings as new dbschk default values. Note: The default dbschk settings are global to the system. They are used when dbschk is run from any node of MPP system. If you use the -save option to store current -job or -trigger settings as defaults, ensure the specified programs or scripts exist on all nodes of the system. Specifies how long dbschk waits for a response from Teradata Database after running the program specified by the -job option. Once the time specified by -timeout has elapsed with no response from the database, dbschk runs -job again. As long as there is no response from the database, dbschk continues trying -job the number of times specified by the -rate parameter before running the program specified by the -trigger parameter. wait_seconds is a positive integer. The factory default is 300 seconds. Note: Setting a very low a value for -timeout is impractical, and can adversely affect system performance. 342 Utilities

343 Chapter 12: Resource Check Tools (dbschk, nodecheck, syscheck) dbschk Syntax element... -trigger trigger_program Description Specifies a program or script to run if there is no response from Teradata Database after dbschk has tried the number of times specified by -rate, and, for each attempt, has waited the time period specified by the -timeout parameter. Note: Default dbschk settings are used by all nodes of MPP systems. If you use the -save option to store the current -trigger setting as a custom default, ensure that the specified program or script exists on all nodes. Usage Notes Example 1 Parameters set on the dbschk command line are valid only for the current session unless the -save parameter is used. To see the current and factory default settings, use dbschk -l. When dbschk starts, if the log file is 5MB or larger, dbschk flushes the current log entries to a new file that has.old appended to the original log file name. Logging continues to the original log file. For example, when an original log file named myfile.log grows to 5MB, the entries are moved from myfile.log to myfile.log.old, and logging continues to myfile.log. The next time myfile.log reaches 5MB, the information is flushed again to myfile.log.old, overwriting the information that was in the.old file. The following example uses the -l option to display the current dbschk default settings. > dbschk -l Current default values : power : ON timeout : 120 seconds rate : 3 trials delay : 600 seconds logflush : 1200 seconds job : csp -mode list -source table logfile : D:\Program Files\NCR\Tdat\TdTemp\dbschk.log trigger : pdestate -a Factory default values : power : OFF timeout : 300 seconds rate : 5 trials delay : 1200 seconds logflush : 3600 seconds job : csp -mode list -source table logfile : D:\Program Files\NCR\Tdat\TdTemp\dbschk.log trigger : pdestate -a Utilities 343

344 Chapter 12: Resource Check Tools (dbschk, nodecheck, syscheck) dbschk Example 2 The following example runs dbschk with the -save option, setting the default values to allow dbschk to run and to send dbschk output to the computer screen. >dbschk -save -power ON -logfile stdout Current default values : power : ON timeout : 300 seconds rate : 5 trials delay : 1200 seconds logflush : 3600 seconds job : csp -mode list -source table logfile : stdout trigger : pdestate -a Factory default values : power : OFF timeout : 300 seconds rate : 5 trials delay : 1200 seconds logflush : 3600 seconds job : csp -mode list -source table logfile : D:\Program Files\NCR\Tdat\TdTemp\dbschk.log trigger : pdestate -a Do you want to save the new settings as dbschk default values? (y/n): y New settings saved... (dbschk): Normal termination - OK Example 3 The following example runs dbschk to check database responsiveness. The command-line settings cause dbschk to run two times, waiting five seconds between runs. >dbschk -n 2 -delay 5 (dbschk): current default values : power : ON timeout : 300 seconds rate : 5 trials delay : 5 seconds logflush : 3600 seconds job : csp -mode list -source table logfile : stdout trigger : pdestate -a Factory default values: power : OFF timeout : 300 seconds rate : 5 trials delay : 1200 seconds logflush : 3600 seconds job : csp -mode list -source table logfile : /var/opt/teradata/tdtemp/dbschk.log trigger : pdestate -a csp: Searching for dumps in Teradata database Crashdumps on the local system csp: 3 dumps found, 3 dumps to process csp: Sel ID (date-time-token) Nodes Event Instigator csp: csp: * 2007/05/24-09:23: /13/(12351) csp: * 2007/05/24-09:23: /13/(12191) csp: * 2007/05/24-09:15: /0/(11215) 344 Utilities

345 Chapter 12: Resource Check Tools (dbschk, nodecheck, syscheck) dbschk (dbschk): retstatus = 1010, status = 0, childpid = 1010 (dbschk): Sample Query finished normally, response time=3 seconds, (dbschk): sleep 5 seconds before restart. csp: Searching for dumps in Teradata database Crashdumps on the local system csp: 3 dumps found, 3 dumps to process csp: Sel ID (date-time-token) Nodes Event Instigator csp: csp: * 2007/05/24-09:23: /13/(12351) csp: * 2007/05/24-09:23: /13/(12191) csp: * 2007/05/24-09:15: /0/(11215) (dbschk): retstatus = 1020, status = 0, childpid = 1020 (dbschk): Sample Query finished normally, response time=2 seconds, (dbschk): Normal termination - OK Utilities 345

346 Chapter 12: Resource Check Tools (dbschk, nodecheck, syscheck) nodecheck nodecheck Purpose nodecheck is a command-line diagnostic tool that finds node-level resource values on the local node. nodecheck provides summary data by node to syscheck for analyses or provides detailed output to the nodecheck log file, which is used later for analysis by syscheck. Syntax nodecheck -D -f log -h -I -L -r rscfile -t n log -v FF07D399 where: Syntax element... Description -D Displays threshold values for -nodeonly and -timercontrol tunables in syscheckrc format. Use this option to redirect the output to quickly create a syscheckrc file that you can customize. Then use the -r rscfile option to read from that customized syscheckrc file. -f log Overrides the default log file location as specified in the -L option. The -f option must be used with the -L option. The directory path must previously exist. If you specify a file, that file is written. If you specify a directory, then the default filename specified in the -L option is written to that directory. -h Provides basic help on command line options. -I Lists threshold values for -nodeonly and -timercontrol tunables. 346 Utilities

347 Chapter 12: Resource Check Tools (dbschk, nodecheck, syscheck) nodecheck Syntax element... Description -L Logs the output to a file in the /tpi-data directory on the node where nodecheck is run. The default log filename is nodecheck with an extension indicating the TPA cyclecount at the time of the run (for example, nodecheck.2). You can specify a specific log filename or location using the -f log option. Additional tools are executed during logging mode, but their output is sent only to the resulting file. -r rscfile Specifies an additional resource file whose values will override those in the default syscheckrc file (and optional syscheckrc file, if one exists). For information on the syscheckrc file, see syscheckrc File on page t Directs nodecheck to read node-level resource data from one of the following previously created log files. IF you use... THEN nodecheck reads data from... n log the /tpi-data/nodecheck.n file, where n indicates the TPA cyclecount at the time of the run. a user-defined path or filename that contains the log information. -v Displays the current resource values on the local node, evaluates the resource values, and notifies you of the status of all tunable resources, regardless of level. Usage Notes If you invoke nodecheck without any options, then nodecheck does the following: Displays the current resource values on the local node Evaluates the resource values Notifies you of resources which have reached WARN or ALERT levels The defined node-level resource names and values are located in the -nodeonly section of the syscheckrc configuration file. The syscheckrc file is read and processed at the following locations: Utilities 347

348 Chapter 12: Resource Check Tools (dbschk, nodecheck, syscheck) nodecheck On... syscheckrc is stored in the... Linux /usr/pde/etc directory (default) /pde directory (optional) MP-RAS /usr/ntos/etc directory (default) /ntos directory (optional) The configuration file also specifies the PDE tools that are used to extract the values of the node-level resources. Caution: Teradata does not recommend you modify the values for the PDE tools (under the -testdriver section), since this might cause program failure or unexpected results. The -testdriver section in the second path (Teradata Configuration directory) is ignored but processed at the first path and in a user-specified syscheckrc file. For more information on the -testdriver section of the syscheckrc file, see Testdriver Section on page 365. Windows Program Files\NCR\TDAT\LPDE\etc directory (default). Program Files\NCR\TDAT\tdConfig directory (optional). Creating a Log File Note: When executed through syscheck, nodecheck will only read and process the local syscheckrc file. This means that changes to the -timercontrol section must be propagated to all nodes in order for nodecheck to run similarly on each node. For information on the -timercontrol section, see Timercontrol Section on page 366. For more information on the syscheckrc file, see syscheckrc File on page 364. To run a single instance of nodecheck, creating a log file for later analysis, do the following: type: Example 1 - MP-RAS nodecheck -L -f log where log is the eventual location (a user-defined path or filename) that contains the log information. nodecheck will still print and evaluate the current resources. The following is an example of running nodecheck with no options. nodecheck Reading Node Resources... please wait... FreeMemory(Pages) and FreeSwap(Blocks) /usr/sbin/sar -r 2 5 FREEMEM FREESWAP Inuse Vproc Pages /usr/ntos/bin/puma -p Count Vproc Utilities

349 Chapter 12: Resource Check Tools (dbschk, nodecheck, syscheck) nodecheck Example 2 - Windows Available AMP Worker Tasks /usr/ntos/bin/puma -c Count Vproc BNS reject% for different Message types /usr/ntos/bin/tdnstat -a 5 2 SBR_FCount% Message Type 0 RXGRPSEG 0 RXP2PSEG 0 RXGRPREC 0 RXP2PREC SegTblFull% Message Type 0 RXGRPSEG 0 RXP2PSEG PDE Msg Daemon Queue length /usr/ntos/bin/puma -D msgevcount/d MSGEVCOUNT 0 BNS Block Queue /usr/ntos/bin/puma -D *BSCp/3d BNSBLKQ 0 Evaluating results... please wait... No tunables show status of WARN or ALERT nodecheck Reading Node Resources... please wait... FreeMemory(Pages) and FreeSwap(Blocks) e:\progra~1\ncr\tdat\lpde\bin/sar.exe -r 1 1 FREEMEM 1185 FREESWAP PDE Msg Daemon Queue length e:\progra~1\ncr\tdat\lpde\bin/pdeglobal.exe msg -knode MSGEVCOUNT 0 Utilities 349

350 Chapter 12: Resource Check Tools (dbschk, nodecheck, syscheck) nodecheck Example 3 - MP-RAS Example 4 - Windows BNS Block Queue e:\progra~1\ncr\tdat\lpde\bin/puma.exe -D BlockStats/d BNSBLKQ 0 Available AMP Worker Tasks e:\progra~1\ncr\tdat\lpde\bin/puma.exe -c Count Vproc BNS reject% for different Message types e:\progra~1\ncr\tdat\lpde\bin/tdnstat.exe -a 1 1 SBR_FCount% Message Type 0 RXGRPREC 0 RXGRPSEG 0 RXP2PREC 0 RXP2PSEG SegTblFull% Message Type 0 RXGRPSEG 0 RXP2PSEG Evaluating results... please wait... No tunables show status of WARN or ALERT The following is an example of running syscheck with the -D option to display -nodeonly and -timercontrol tunables in syscheckrc format. nodecheck -D -nodeonly AMPWT WARN -0 ALERT -0 BNSBLKQ WARN 500 ALERT 100 FREEMEM WARN ALERT -500 FREESWAP WARN ALERT MSGEVCOUNT WARN 100 ALERT 300 RXMSGFC WARN 90 ALERT 100 SEGTBLFULL WARN 80 ALERT 100 VPRPAGES WARN -2 ALERT -0 -timercontrol SARSAMPLE 5 SARSLEEP 2 TDNSTATSAMPLE 2 TDNSTATSLEEP 5 nodecheck -D -nodeonly AMPWT WARN -0 ALERT -0 BNSBLKQ WARN 500 ALERT 100 FREEMEM WARN ALERT -500 FREESWAP WARN ALERT MSGEVCOUNT WARN 100 ALERT 300 RXMSGFC WARN 90 ALERT 100 SEGTBLFULL WARN 80 ALERT 100 -timercontrol SARSAMPLE 1 SARSLEEP 1 TDNSTATSAMPLE 1 TDNSTATSLEEP Utilities

351 Chapter 12: Resource Check Tools (dbschk, nodecheck, syscheck) nodecheck Example 5 - MP-RAS Example 6 - Windows Example 7 - MP-RAS The following is an example of running syscheck with the -I option to display -nodeonly and -timercontrol tunables. nodecheck -I Tunable WARN ALERT AMPWT <=0 <=0 BNSBLKQ >=500 >=100 FREEMEM <=1000 <=500 FREESWAP <=2000 <=1000 MSGEVCOUNT >=100 >=300 RXMSGFC >=90 >=100 SEGTBLFULL >=80 >=100 VPRPAGES <=2 <=0 Tunable Value SARSAMPLE 5 SARSLEEP 2 TDNSTATSAMPLE 2 TDNSTATSLEEP 5 nodecheck -I Tunable WARN ALERT AMPWT <=0 <=0 BNSBLKQ >=500 >=100 FREEMEM <=1000 <=500 FREESWAP <=2000 <=1000 MSGEVCOUNT >=100 >=300 RXMSGFC >=90 >=100 SEGTBLFULL >=80 >=100 Tunable Value SARSAMPLE 1 SARSLEEP 1 TDNSTATSAMPLE 1 TDNSTATSLEEP 1 The following is an example of running nodecheck with the -L option. nodecheck -L Writing to log file: /tpi-data/nodecheck.969 Reading Node Resources... please wait... FreeMemory(Pages) and FreeSwap(Blocks) /usr/sbin/sar -r 2 5 FREEMEM FREESWAP Inuse Vproc Pages /usr/ntos/bin/puma -p Count Vproc Utilities 351

352 Chapter 12: Resource Check Tools (dbschk, nodecheck, syscheck) nodecheck Example 8 - Windows Available AMP Worker Tasks /usr/ntos/bin/puma -c Count Vproc BNS reject% for different Message types /usr/ntos/bin/tdnstat -a 5 2 SBR_FCount% Message Type 0 RXGRPSEG 0 RXP2PSEG 0 RXGRPREC 0 RXP2PREC SegTblFull% Message Type 0 RXGRPSEG 0 RXP2PSEG PDE Msg Daemon Queue length /usr/ntos/bin/puma -D msgevcount/d MSGEVCOUNT 0 BNS Block Queue /usr/ntos/bin/puma -D *BSCp/3d BNSBLKQ 0 Evaluating results... please wait... No tunables show status of WARN or ALERT nodecheck -L Writing to log file: e:\progra~1\ncr\tdat\tdconfig\tmp\tpidata\nodecheck.22 Reading Node Resources... please wait... FreeMemory(Pages) and FreeSwap(Blocks) e:\progra~1\ncr\tdat\lpde\bin/sar.exe -r 1 1 FREEMEM 975 FREESWAP PDE Msg Daemon Queue length e:\progra~1\ncr\tdat\lpde\bin/pdeglobal.exe msg -knode MSGEVCOUNT 0 BNS Block Queue e:\progra~1\ncr\tdat\lpde\bin/puma.exe -D BlockStats/d BNSBLKQ Utilities

353 Chapter 12: Resource Check Tools (dbschk, nodecheck, syscheck) nodecheck Available AMP Worker Tasks e:\progra~1\ncr\tdat\lpde\bin/puma.exe -c Count Vproc BNS reject% for different Message types e:\progra~1\ncr\tdat\lpde\bin/tdnstat.exe -a 1 1 SBR_FCount% Message Type 0 RXGRPREC 0 RXGRPSEG 0 RXP2PREC 0 RXP2PSEG SegTblFull% Message Type 0 RXGRPSEG 0 RXP2PSEG Evaluating results... please wait... Resource Current Current Threshold Vproc Number/ Description Level Value Value Message Type FreeMemory(Pages) WARN 975 <=1000 Example 9 - MP-RAS The following is an example of running nodecheck with the -v option. nodecheck -v Reading Node Resources... please wait... FreeMemory(Pages) and FreeSwap(Blocks) /usr/sbin/sar -r 2 5 FREEMEM FREESWAP Inuse Vproc Pages /usr/ntos/bin/puma -p Count Vproc Available AMP Worker Tasks /usr/ntos/bin/puma -c Count Vproc Utilities 353

354 Chapter 12: Resource Check Tools (dbschk, nodecheck, syscheck) nodecheck BNS reject% for different Message types /usr/ntos/bin/tdnstat -a 5 2 SBR_FCount% Message Type 0 RXGRPSEG 0 RXP2PSEG 0 RXGRPREC 0 RXP2PREC SegTblFull% Message Type 0 RXGRPSEG 0 RXP2PSEG PDE Msg Daemon Queue length /usr/ntos/bin/puma -D msgevcount/d MSGEVCOUNT 0 BNS Block Queue /usr/ntos/bin/puma -D *BSCp/3d BNSBLKQ 0 Evaluating results... please wait... Resource Current Current Threshold Vproc Number Description Level Value Value Message Type FreeMemory(Pages) OK FreeSwap(Blocks) OK Available Vproc Pages OK Available Vproc Pages OK 29 0 Available Vproc Pages OK 29 1 Available Vproc Pages OK 29 2 Available Vproc Pages OK 29 3 Available Vproc Pages OK 29 4 Available Vproc Pages OK 29 5 Available Vproc Pages OK 29 6 Available Vproc Pages OK 29 7 Available Vproc Pages OK 29 8 Available Vproc Pages OK 29 9 Available Vproc Pages OK Available Vproc Pages OK Available Vproc Pages OK Available Vproc Pages OK Available AMP Worker Tasks OK 39 0 Available AMP Worker Tasks OK 40 1 Available AMP Worker Tasks OK 40 2 Available AMP Worker Tasks OK 40 3 Available AMP Worker Tasks OK 40 4 Available AMP Worker Tasks OK 40 5 Available AMP Worker Tasks OK 40 6 Available AMP Worker Tasks OK 40 7 Available AMP Worker Tasks OK 40 8 Available AMP Worker Tasks OK 40 9 BNS Msg Reject%(FC) OK 0 RXGRPSEG BNS Msg Reject%(FC) OK 0 RXP2PSEG BNS Msg Reject%(FC) OK 0 RXGRPREC BNS Msg Reject%(FC) OK 0 RXP2PREC BNS Msg Reject%(SEGTBLFULL) OK 0 RXGRPSEG BNS Msg Reject%(SEGTBLFULL) OK 0 RXP2PSEG PDE Msg Daemon Queue Length OK 0 BNS Block Queue Length OK Utilities

355 Chapter 12: Resource Check Tools (dbschk, nodecheck, syscheck) nodecheck Example 10 - Windows Example 11 - MP-RAS >nodecheck -v Reading Node Resources... please wait... FreeMemory(Pages) and FreeSwap(Blocks) e:\progra~1\ncr\tdat\lpde\bin/sar.exe -r 1 1 FREEMEM 1192 FREESWAP PDE Msg Daemon Queue length e:\progra~1\ncr\tdat\lpde\bin/pdeglobal.exe msg -knode MSGEVCOUNT 0 BNS Block Queue e:\progra~1\ncr\tdat\lpde\bin/puma.exe -D BlockStats/d BNSBLKQ 0 Available AMP Worker Tasks e:\progra~1\ncr\tdat\lpde\bin/puma.exe -c Count Vproc BNS reject% for different Message types e:\progra~1\ncr\tdat\lpde\bin/tdnstat.exe -a 1 1 SBR_FCount% Message Type 0 RXGRPREC 0 RXGRPSEG 0 RXP2PREC 0 RXP2PSEG SegTblFull% Message Type 0 RXGRPSEG 0 RXP2PSEG Evaluating results... please wait... Resource Current Current Threshold Vproc Number/ Description Level Value Value Message Type FreeMemory(Pages) OK 1192 FreeSwap(Blocks) OK PDE Msg Daemon Queue Length OK 0 BNS Block Queue Length OK 0 Available AMP Worker Tasks OK 55 0 Available AMP Worker Tasks OK 56 1 BNS Msg Reject%(FC) OK 0 RXGRPREC BNS Msg Reject%(FC) OK 0 RXGRPSEG BNS Msg Reject%(FC) OK 0 RXP2PREC BNS Msg Reject%(FC) OK 0 RXP2PSEG BNS Msg Reject%(SEGTBLFULL) OK 0 RXGRPSEG BNS Msg Reject%(SEGTBLFULL) OK 0 RXP2PSEG The following is an example of running nodecheck with the -v option and reading output from a previously generated log file. The TPA cyclecount is specified to gain access to the recently created default log file. nodecheck -t 969 -v Reading from log file: /tpi-data/nodecheck.969 FreeMemory(Pages) and FreeSwap(Blocks) /usr/sbin/sar -r 2 5 FREEMEM FREESWAP Utilities 355

356 Chapter 12: Resource Check Tools (dbschk, nodecheck, syscheck) nodecheck Inuse Vproc Pages /usr/ntos/bin/puma -p Count Vproc Available AMP Worker Tasks /usr/ntos/bin/puma -c Count Vproc BNS reject% for different Message types /usr/ntos/bin/tdnstat -a 5 2 SBR_FCount% Message Type 0 RXGRPSEG 0 RXP2PSEG 0 RXGRPREC 0 RXP2PREC SegTblFull% Message Type 0 RXGRPSEG 0 RXP2PSEG PDE Msg Daemon Queue length /usr/ntos/bin/puma -D msgevcount/d MSGEVCOUNT 0 BNS Block Queue /usr/ntos/bin/puma -D *BSCp/3d BNSBLKQ 0 Evaluating results... please wait... Resource Current Current Threshold Vproc Number Description Level Value Value Message Type FreeMemory(Pages) OK FreeSwap(Blocks) OK Available Vproc Pages OK Available Vproc Pages OK 29 0 Available Vproc Pages OK 29 1 Available Vproc Pages OK 29 2 Available Vproc Pages OK 29 3 Available Vproc Pages OK 29 4 Available Vproc Pages OK Utilities

357 Chapter 12: Resource Check Tools (dbschk, nodecheck, syscheck) nodecheck Available Vproc Pages OK 29 6 Available Vproc Pages OK 29 7 Available Vproc Pages OK 29 8 Available Vproc Pages OK 29 9 Available Vproc Pages OK Available Vproc Pages OK Available Vproc Pages OK Available Vproc Pages OK Available AMP Worker Tasks OK 39 0 Available AMP Worker Tasks OK 40 1 Available AMP Worker Tasks OK 40 2 Available AMP Worker Tasks OK 40 3 Available AMP Worker Tasks OK 40 4 Available AMP Worker Tasks OK 40 5 Available AMP Worker Tasks OK 40 6 Available AMP Worker Tasks OK 40 7 Available AMP Worker Tasks OK 40 8 Available AMP Worker Tasks OK 40 9 BNS Msg Reject%(FC) OK 0 RXGRPSEG BNS Msg Reject%(FC) OK 0 RXP2PSEG BNS Msg Reject%(FC) OK 0 RXGRPREC BNS Msg Reject%(FC) OK 0 RXP2PREC BNS Msg Reject%(SEGTBLFULL) OK 0 RXGRPSEG BNS Msg Reject%(SEGTBLFULL) OK 0 RXP2PSEG PDE Msg Daemon Queue Length OK 0 BNS Block Queue Length OK 0 Example 12 - Windows The following is an example of running nodecheck with the -L and -f options and writing output to a log file. nodecheck -L -f mylog Writing to log file: mylog Reading Node Resources... please wait... FreeMemory(Pages) and FreeSwap(Blocks) e:\progra~1\ncr\tdat\lpde\bin/sar.exe -r 1 1 FREEMEM 1498 FREESWAP PDE Msg Daemon Queue length e:\progra~1\ncr\tdat\lpde\bin/pdeglobal.exe msg -knode MSGEVCOUNT 0 BNS Block Queue e:\progra~1\ncr\tdat\lpde\bin/puma.exe -D BlockStats/d BNSBLKQ 0 Available AMP Worker Tasks e:\progra~1\ncr\tdat\lpde\bin/puma.exe -c Count Vproc BNS reject% for different Message types e:\progra~1\ncr\tdat\lpde\bin/tdnstat.exe -a 1 1 SBR_FCount% 0 RXGRPREC 0 RXGRPSEG 0 RXP2PREC Message Type 0 RXP2PSEG SegTblFull% Message Type Utilities 357

358 Chapter 12: Resource Check Tools (dbschk, nodecheck, syscheck) nodecheck Example 13 - Windows 0 RXGRPSEG 0 RXP2PSEG Evaluating results... please wait... No tunables show status of WARN or ALERT The following is an example of running nodecheck with the -t option and reading input from a previously generated log file. nodecheck -t mylog Reading from log file: mylog FreeMemory(Pages) and FreeSwap(Blocks) e:\progra~1\ncr\tdat\lpde\bin/sar.exe -r 1 1 FREEMEM 1498 FREESWAP PDE Msg Daemon Queue length e:\progra~1\ncr\tdat\lpde\bin/pdeglobal.exe msg -knode MSGEVCOUNT 0 BNS Block Queue e:\progra~1\ncr\tdat\lpde\bin/puma.exe -D BlockStats/d BNSBLKQ 0 Available AMP Worker Tasks e:\progra~1\ncr\tdat\lpde\bin/puma.exe -c Count Vproc BNS reject% for different Message types e:\progra~1\ncr\tdat\lpde\bin/tdnstat.exe -a 1 1 SBR_FCount% Message Type 0 RXGRPREC 0 RXGRPSEG 0 RXP2PREC 0 RXP2PSEG SegTblFull% Message Type 0 RXGRPSEG 0 RXP2PSEG Evaluating results... please wait... No tunables show status of WARN or ALERT Messages nodecheck displays the following types of messages. The message... Appears... Error Warning nodecheck encounters any error to extract the resource value. An Error message could occur if nodecheck cannot find or execute the related PDE tool to extract the resource value. If STDERR output exists, it displays. invalid information is found during processing of the syscheckrc file or for other reasons. 358 Utilities

359 Chapter 12: Resource Check Tools (dbschk, nodecheck, syscheck) syscheck syscheck Purpose syscheck monitors the system for signs of congestion that might lead to system slowdowns or perceived hangs and notifies you when Warning or Alert thresholds are reached. Syntax syscheck -D -h -I -L -n nl -r rscfile -t n -v FF07D398 where: Syntax element... Description -D Displays threshold values for -nodeonly and -timercontrol tunables in syscheckrc format. Use this option to redirect the output to quickly create a copy of the syscheckrc file you can customize. Then use the -r rscfile option to read from your customized syscheckrc file. syscheck will not take into account the -timercontrol section of the custom syscheckrc file you indicate with the -r rscfile option. Since syscheck executes nodecheck locally as well as on each remote node, modifications to the default and custom syscheckrc files on the local node will be considered for that local spawn of nodecheck. That is, where syscheck is concerned, -timercontrol changes are local, and -nodeonly changes global. Where nodecheck is concerned, all changes take effect locally. For more information, see Timercontrol Section on page 366 and Nodeonly Section on page h Provides basic help on command line options. -I Lists threshold values for -nodeonly and -timercontrol tunables. Utilities 359

360 Chapter 12: Resource Check Tools (dbschk, nodecheck, syscheck) syscheck Syntax element... Description -L Logs the output to a file in the /tpi-data directory on each node where nodecheck is run. The default log filename is nodecheck with an extension indicating the TPA cyclecount at the time of the run (for example, nodecheck.2). You can specify a specific log filename or location using the -f log option. Additional tools are executed during logging mode, but their output is sent only to the resulting file. For more information, see nodecheck on page n nl Specifies the list of nodes on which nodecheck is invoked. By default, nodecheck is invoked on all live TPA nodes. Note: Separate the nodes in the list by commas. -r rscfile Specifies an additional resource file whose values will override those in the default syscheckrc file (and optional syscheckrc file, if one exists). Note: syscheck will not take into account the -timercontrol section of the custom resource file you indicate with the -r rscfile option. Since syscheck executes nodecheck locally as well as on each remote node, modifications to the default and optional syscheckrc file on the local nodes will be considered for that local spawn of nodecheck. That is, where syscheck is concerned, -timercontrol changes are local, and nodeonly changes are global. Where nodecheck is concerned, all changes take effect locally. For more information, see syscheckrc File on page t n Directs nodecheck to read node-level resource data from a previously created log file (with a default name) on each node. nodecheck reads the data from the /tpi-data/nodecheck.n file, where n indicates the TPA cyclecount at the time of the run. -v Displays all the resource values for each node, evaluates the resource values, and notifies you of the status of all tunable resources, regardless of level. Usage Notes syscheck does not automatically reset the system when any threshold is reached. The DBA or operator decides when to reset the system if the congestion persists. syscheck is a system-wide tool (as compared to nodecheck, which is node-only tool) and does the following in this order: 360 Utilities

361 Chapter 12: Resource Check Tools (dbschk, nodecheck, syscheck) syscheck IF you invoke syscheck... THEN syscheck... without any options spawns an instance of nodecheck on all live TPA nodes. compares the nodecheck results from each node against threshold values indicated in the local syscheckrc file, which are located on the machine where you run syscheck. displays the current resource values on the local node. evaluates the resource values. notifies you of resources which have reached WARN or ALERT levels. with the -v option spawns an instance of nodecheck on all live TPA nodes. compares the nodecheck results from each node against threshold values indicated in the local syscheckrc file, which are located on the machine where you run syscheck. displays the current resource values on the local node. evaluates the resource values. notifies you of the status of all tunable resources, regardless of level. syscheck also checks the Teradata PDE and Database states on the node on which you execute syscheck, informing you if either is not in a fully functional state. The defined node-level resource names and threshold values for alerts and warnings are located in the -nodeonly section of the syscheckrc configuration file. For more information, see syscheckrc File on page 364. Example 1 - Linux, MP-RAS, and Windows The following is an example of running syscheck with no options. syscheck Processing resource values for WARN/ALERT status... please wait... NODE ID: localhost Resource Current Current Threshold Vproc Number Description Level Value Value Message Type FreeMemory(Pages) WARN 992 <=1000 Example 2 - Linux, MP-RAS, and Windows The following is an example of running syscheck with the -D option to display -nodeonly and -timercontrol tunables in syscheckrc format. syscheck -D -nodeonly AMPWT WARN -0 ALERT -0 BNSBLKQ WARN 500 ALERT 100 FREEMEM WARN ALERT -500 FREESWAP WARN ALERT MSGEVCOUNT WARN 100 ALERT 300 RXMSGFC WARN 90 ALERT 100 Utilities 361

362 Chapter 12: Resource Check Tools (dbschk, nodecheck, syscheck) syscheck SEGTBLFULL WARN 80 ALERT 100 VPRPAGES WARN -2 ALERT -0 -timercontrol SARSAMPLE 1 SARSLEEP 1 TDNSTATSAMPLE 1 TDNSTATSLEEP 1 Example 3 - Linux, MP-RAS, and Windows The following is an example of running syscheck with the -I option to display -nodeonly and -timercontrol tunables. Note: On Windows output, the Tunable VPRPAGES will not appear. syscheck -I Tunable WARN ALERT AMPWT <=0 <=0 BNSBLKQ >=500 >=100 FREEMEM <=1000 <=500 FREESWAP <=2000 <=1000 MSGEVCOUNT >=100 >=300 RXMSGFC >=90 >=100 SEGTBLFULL >=80 >=100 VPRPAGES <=2 <=0 Tunable Value SARSAMPLE 1 SARSLEEP 1 TDNSTATSAMPLE 1 TDNSTATSLEEP 1 Example 4 - Linux, MP-RAS, and Windows The following is an example of running syscheck with the -L option. syscheck -L Processing resource values for WARN/ALERT status... please wait... NODE ID: localhost No tunables show status of WARN or ALERT Example 5 - MP-RAS The following is an example of running syscheck with the -v option. syscheck -v Processing resource values for any status... please wait... NODE ID: localhost Resource Current Current Threshold Vproc Number Description Level Value Value Message Type FreeMemory(Pages) OK 1166 FreeSwap(Blocks) OK Available Vproc Pages OK Available Vproc Pages OK Utilities

363 Chapter 12: Resource Check Tools (dbschk, nodecheck, syscheck) syscheck Available Vproc Pages OK Available Vproc Pages OK Available Vproc Pages OK Available AMP Worker Tasks OK 39 0 Available AMP Worker Tasks OK 40 1 BNS Msg Reject%(FC) OK 0 RXGRPSEG BNS Msg Reject%(FC) OK 0 RXP2PSEG BNS Msg Reject%(FC) OK 0 RXGRPREC BNS Msg Reject%(FC) OK 0 RXP2PREC BNS Msg Reject%(SEGTBLFULL) OK 0 RXGRPSEG BNS Msg Reject%(SEGTBLFULL) OK 0 RXP2PSEG PDE Msg Daemon Queue Length OK 0 BNS Block Queue Length OK 0 Example 6 - Linux and Windows syscheck -v Example 7 - MP-RAS Processing resource values for any status... please wait... NODE ID: localhost Resource Current Current Threshold Vproc Number/ Description Level Value Value Message Type FreeMemory(Pages) OK 3158 FreeSwap(Blocks) OK PDE Msg Daemon Queue Length OK 0 BNS Block Queue Length OK 0 Available AMP Worker Tasks OK 55 0 Available AMP Worker Tasks OK 56 1 BNS Msg Reject%(FC) OK 0 RXGRPREC BNS Msg Reject%(FC) OK 0 RXGRPSEG BNS Msg Reject%(FC) OK 0 RXP2PREC BNS Msg Reject%(FC) OK 0 RXP2PSEG BNS Msg Reject%(SEGTBLFULL) OK 0 RXGRPSEG BNS Msg Reject%(SEGTBLFULL) OK 0 RXP2PSEG The following is an example of running nodecheck to read output from a logfile that was just created. The TPA cyclecount is specified to gain access to the recently created default logfile. syscheck -t 24 Logfile to be processed: /tpi-data/nodecheck.24 Processing resource values for WARN/ALERT status... please wait... NODE ID: localhost Example 8 - Windows No tunables show status of WARN or ALERT syscheck -t 22 -v Logfile to be processed: e:\progra~1\ncr\tdat\tdconfig\tmp\tpidata\nodecheck.22 Processing resource values for any status... please wait... Utilities 363

364 Chapter 12: Resource Check Tools (dbschk, nodecheck, syscheck) syscheck syscheckrc File NODE ID: localhost Resource Current Current Threshold Vproc Number/ Description Level Value Value Message Type FreeMemory(Pages) OK 3207 FreeSwap(Blocks) OK PDE Msg Daemon Queue Length OK 0 BNS Block Queue Length OK 0 Available AMP Worker Tasks OK 55 0 Available AMP Worker Tasks OK 56 1 BNS Msg Reject%(FC) OK 0 RXGRPREC BNS Msg Reject%(FC) OK 0 RXGRPSEG BNS Msg Reject%(FC) OK 0 RXP2PREC BNS Msg Reject%(FC) OK 0 RXP2PSEG BNS Msg Reject%(SEGTBLFULL) OK 0 RXGRPSEG BNS Msg Reject%(SEGTBLFULL) OK 0 RXP2PSEG syscheckrc is a text file that contains system, kernel, and Teradata Database-specific parameters. When these parameters are exceeded, your system resources may run low, resulting in poor performance. Although not mandatory, all copies of syscheckrc should be identical on all nodes. However, each copy of syscheckrc must correspond to the specific node on which syscheckrc resides. Caution: Do NOT modify the default syscheckrc file. To create a custom syscheckrc file, see Creating a syscheckrc File on page 367. The default syscheckrc file is read and processed at the following locations. On... Linux MP-RAS Windows The default syscheckrc file is located in the... /usr/pde/etc directory. /usr/ntos/etc directory. Program Files\NCR\TDAT\LPDE\etc directory. Default syscheckrc File Example syscheck reads and parses the resource files at startup. Resource files have a line-oriented syntax: A line starting with a # is a comment. A line containing only comments or white space (spaces or tabs) is ignored. Each line can have a single resource entry that has name and value strings separated by white space. The following is an example of the default syscheckrc file. #-testdriver: ## This section is provided as a tool for GSC to provide test input ## to syscheck and nodecheck. This section is not meant for 364 Utilities

365 Chapter 12: Resource Check Tools (dbschk, nodecheck, syscheck) syscheck ## modification by the customer. NOTE: Modification of this ## section can yield unexpected errors or results. To override a ## tool that is used in nodecheck or syscheck, uncomment the ## appropriate line and provide a different path or executable for ## the tool. # SAR %PDE_BIN\sar.exe # PUMA %PDE_BIN\puma.exe # TDNSTAT %PDE_BIN\tdnstat.exe # BLMSTAT blmstat.exe # VPROCMANAGER %PDE_BIN\vprocmanager.exe # PDESTATE %PDE_BIN\pdestate.exe # PCL %PDE_BIN\pcl.exe # MPPLIST %PDE_CFG\mpplist # NETECHO %PDE_BIN\tdinfo.exe # NODECHECK %PDE_BIN\nodecheck.bat # CONTROLGDO %PDE_BIN\controlgdo.exe # PDEGLOBAL %PDE_BIN\pdeglobal.exe -nodeonly: This section defines node-only parameters AMPWT WARN -0 ALERT -0 BNSBLKQ WARN 500 ALERT 100 FREEMEM WARN ALERT -500 FREESWAP WARN ALERT MSGEVCOUNT WARN 100 ALERT 300 RXMSGFC WARN 90 ALERT 100 SEGTBLFULL WARN 80 ALERT 100 VPRPAGES WARN -2 ALERT -0 -timercontrol # used to override behavior of sar and tdnstat in nodecheck # i.e. sar.exe -r SARSLEEP SARSAMPLE # values need to be integers >= 1 SARSLEEP 2 SARSAMPLE 5 TDNSTATSLEEP 5 TDNSTATSAMPLE 2 Testdriver Section The -testdriver section maps to the executables of each node and is different, depending on the platform. Caution: Do NOT modify the -testdriver section. If you modify the -testdriver section, nodecheck and syscheck might fail. Nodeonly Section The -nodeonly section allows you to define the WARN and ALERT threshold levels for each system resource. If the threshold value is negative, then the condition (either WARN or ALERT) will be triggered when that system resource attribute falls below that value. Otherwise, the condition is triggered when the attribute rises above that value. The default syscheckrc file contains default values. You should never edit the default syscheckrc file itself. You can customize the warning and alert levels in a custom syscheckrc Utilities 365

366 Chapter 12: Resource Check Tools (dbschk, nodecheck, syscheck) syscheck file. For more information on creating your own customized syscheckrc file, see Creating a syscheckrc File on page 367. The following table describes each system resource attribute. System Resource Attribute AMPWT WARN XXX ALERT XXX BNSBLKQ WARN XXX ALERT XXX FREEMEM WARN XXX ALERT XXX FREESWAP WARN XXX ALERT XXX MSGEVCOUNT WARN XXX ALERT XXX RXMSGFC WARN XXX ALERT XXX VPRPAGES WARN XXX ALERT XXX SEGTBLFULL WARN XXX ALERT XXX Description Warning and alert threshold level for available (or running out) of AMP work tasks (AWTs). Warning and alert threshold level for BNS services in BNS block queue. Warning and alert threshold levels for freemem pages. Warning and alert threshold levels for freeswap blocks. Warning and alert threshold levels for message count in PDE message event queue. Warning and alert threshold for percentage of message count being flow controlled at the receiver side. Warning and alert threshold level for available pages in virtual address of the PDE vproc. (MP-RAS only) Warning and alert threshold for percentage occupation of multi-segment table entries. 100% indicates that the multi-packet messages are naked or all the multi-packet segment table slots are currently occupied. Timercontrol Section The -timercontrol section allows you to adjust the sample number and sleep time. Currently, only two tools use these parameters: System Activity Reporter (SAR) TDNSTAT utility The value must be an integer greater than or equal to one. For the -timercontrol section to work on all nodes, you must provide a modified optional syscheckrc file on each node. 366 Utilities

367 Chapter 12: Resource Check Tools (dbschk, nodecheck, syscheck) syscheck Creating a syscheckrc File A custom (modified) syscheckrc file provides a permanent way to override the default syscheckrc resource file settings. Teradata recommends that you use a naming convention for resources, such as an uppercase name. You can create an optional syscheckrc file whose values will override those in the default syscheckrc file. The file must be placed in a specific location to be read by syscheck and nodecheck. If a syscheckrc file exists at the specified location, it will be read automatically by syscheck and nodecheck. The default and optional syscheckrc files are read from the following locations: On... syscheckrc is stored in the... Linux /usr/pde/etc directory (default). /pde directory (optional). MP-RAS /usr/ntos/etc directory (default). /ntos directory (optional). The configuration file also specifies the PDE tools that are used to extract the values of the node-level resources. Caution: Teradata does not recommend you modify the values for the PDE tools (under the -testdriver section), since this might cause program failure or unexpected results. The -testdriver section in the second path (Teradata Configuration directory) is ignored but processed at the first path and in a user-specified syscheckrc file. For more information on the -testdriver section of the syscheckrc file, see Testdriver Section on page 365. Windows Program Files\NCR\TDAT\LPDE\etc (default). Program Files\NCR\TDAT\tdConfig (optional). To create an optional syscheckrc file: 1 Copy the default syscheckrc file to the appropriate optional location noted above. (You can also use the -D option of nodecheck or syscheck and redirect the output to capture the default settings.) 2 Use a text editor to modify your new file. Custom syscheckrc File Example The following is an example of a custom-modified syscheckrc file on MP-RAS. On Linux and Windows, VPRPAGES would not appear. nodecheck -D -nodeonly AMPWT WARN -3 ALERT -0 BNSBLKQ WARN 300 ALERT 600 FREEMEM WARN -500 ALERT -250 FREESWAP WARN ALERT -500 MSGEVCOUNT WARN 200 ALERT 400 RXMSGFC WARN 75 ALERT 100 Utilities 367

368 Chapter 12: Resource Check Tools (dbschk, nodecheck, syscheck) syscheck SEGTBLFULL WARN 75 ALERT 100 VPRPAGES WARN -1 ALERT -0 -timercontrol SARSAMPLE 1 SARSLEEP 1 TDNSTATSAMPLE 1 TDNSTATSLEEP 1 You can also specify a customized resource configuration file for syscheck and nodecheck to use by specifying the -r option with the configuration file s path and filename when you start syscheck or nodecheck. The values in this file will override the values in the default and optional syscheckrc files. You should follow the same basic copy-and-edit steps to create this file as noted above for creating an optional syscheckrc file. 368 Utilities

369 CHAPTER 13 RSS Monitor (rssmon) The RSS Monitor utility, rssmon, provides per-node, real-time PDE resource usage information on MP-RAS systems. Because the Resource Sampling Subsystem (RSS) collects a wide-range of resource usage data, rssmon allows the selection of relevant data fields from a specific RSS table to be examined for PDE resource usage monitoring purposes. The following applies to the statistical data displayed by rssmon: At every associated ResUsage collection interval, the data display is refreshed with new statistics. Data is collected by the Resource Sampling Subsystem (RSS) of PDE. Data is organized into seven logical tables. For more information about the logical tables, see Monitoring Configuration File on page 370. Note: An additional table is reserved for future use. For additional information about RSS, the logical tables and their usage, and the specific statistical data fields in each table, see Resource Usage Macros and Tables. Audience Users of rssmon include the following: Field engineers Teradata Database administrators Teradata Database system administrators User Interfaces rssmon runs on the following platforms and interfaces: Platform MP-RAS Interfaces Command line Note: rssmon is located in the /usr/ntos/bin directory For general information on starting the utilities from different platforms and interfaces, see Appendix B: Starting the Utilities. Utilities 369

370 Chapter 13: RSS Monitor (rssmon) Syntax Syntax rssmon -f config-file -S output-file 1102B001 where: Syntax element... Specifies... -f config-file a configuration file for PDE resource usage monitoring. You can use either a customized file or one of the following standard files supplied with rssmon in /usr/ntos/bin: ipmadata.cfg ivprdata.cfg scpudata.cfg shstdata.cfg sldvdata.cfg spmadata.cfg svprdata.cfg Note: If the configuration file is not in the current working directory when you execute the rssmon command, then you must specify a correct full or relative path name with the -f flag. -S output-file an output file to which rssmon logs resource usage data. (If you do not specify the -S option, the default does not save to the output file.) A complete set of data, corresponding to the specified configuration file, is written to output-file at the end of each RSS collection interval (not the logging interval). Without this option in the command, no record is saved. To exit rssmon, from the rssmon window, type: q Monitoring Configuration File To use rssmon, you must specify a monitoring configuration file. The function of the configuration file is to define the layout and content of the rssmon display. The file also defines the content of the output file, if you specified the -S flag when you started rssmon. The configuration file that you specify can be one of the following: One of the seven standard configuration files, provided with rssmon utility A customized configuration file that you create 370 Utilities

371 Chapter 13: RSS Monitor (rssmon) Standard Configuration Files Standard Configuration Files The seven standard configuration files supplied with rssmon correspond to the seven logical ResUsage tables. Each file defines the layout, such as column format, and selects as its content all of the fields that are available for its corresponding logical ResUsage table. The following standard files are supplied with rssmon: ipmadata.cfg ivprdata.cfg scpudata.cfg shstdata.cfg sldvdata.cfg spmadata.cfg svprdata.cfg Customized Configuration Files By creating and then specifying a customized configuration file, you can have rssmon display a different layout and content rather than the ones provided in the standard configuration files. For example, you can select tabular rather than columnar format. You can select only those fields you are interested in rather than all available fields. In addition, you can specify more than one ResUsage table. If you do this, only the first table will appear in the rssmon display. But all of the selected fields from all of the specified tables will appear in the output file, if you specified one. To create a customized configuration file, rename and modify one of the standard files by using any text editor (such as vi) and save the new file. Customizing a Configuration File To customize a configuration file, do the following: 1 Line 1 Specify the output format (that is, the format you want to use for displaying ResUsage Data) by selecting one of the following: table If you specify table, ResUsage data is displayed horizontally with one resource (that is, vproc, device, and so on) per row using the tabular format. For example, the table format allows you to see data for all vprocs at one time, as shown in the following display. vpr msgworkqlenavg dblockblocksavg dblocksheldavg cpuuservpart00 cpuuservpart Utilities 371

372 Chapter 13: RSS Monitor (rssmon) Customized Configuration Files Press <cursor keys> to scroll. list If you specify list, ResUsage data is displayed vertically in columnar format. When one column is filled, data continues onto a second column. For example, the columnar format displays data for only one vproc at a time, as shown in the following display. --- PDE ResUsage vpr 0 cpuuservpart msgworkqlenavg 1 cpuuservpart dblockblocksavg 0.00 cpuuservpart dblocksheldavg 0.00 cpuuservpart cpuuservpart cpuuservpart cpuuservpart cpuuservpart cpuuservpart cpuuservpart cpuuservpart cpuuservpart cpuuservpart cpuuservpart cpuuservpart cpuuservpart cpuuservpart cpuuservpart vcpuuservpart cpuuservpart cpuuservpart cpuuservpart Press <cursor keys> to scroll. 2 Line 2 Leave this line blank. 3 Line 3 Specify the ResUsage table to be displayed using keywords as follows: Keyword ipmadata ivprdata scpudata shstdata sldvdata spmadata svprdata ResUsage Table Name ResUsageIpma ResUsageIvpr ResUsageScpu ResUsageShst ResUsageSldv ResUsageSpma ResUsageSvpr Note: The remainder of the file lists the ResUsage fields from the corresponding table to be displayed. 4 Lines 4 through n Specify the selected field names for the ResUsage table, in any order you choose. Note: You must spell out the field names in lowercase letters. 5 Line n+1 Leave a blank line between different table entries. 6 Lines n+2 Specify the keyword for the next ResUsage table. You can specify multiple tables as long as they report ResUsage data for the same resource type. Note: You must spell out the field names in lowercase letters. 372 Utilities

373 Chapter 13: RSS Monitor (rssmon) Displaying ResUsage Data Example table svprdata msgworkqlenavg cpuuservpart00 cpuuservpart01 cpuuservpart02 cpuuservpart03 Displaying ResUsage Data For information on table usage and a complete list of fields for each table, see Resource Usage Macros and Tables. The following table lists the keyboard cursor keys you can use to scroll through the resource usage statistics displays. You can use one of the alternatives listed if one of the following occurs: Your terminal is not defined properly. The keyboard does not have a cursor keypad. The cursor keys are not operational. Cursor Key/ Key Combinations Left Arrow or < (Shift+Comma) Right Arrow or > (Shift+Period) Up Arrow or Comma (,) Down Arrow or Period (.) Effect on the rssmon Display Moves to the previous set of fields, if any, for the currently displayed resource. Moves to the next set of fields, if any, for the currently displayed resource. Moves to the previous resource, if any. For example, the next CPU if displaying Scpu data or the next vproc if displaying Svpr data. Moves to the next resource, if any. For example, the next CPU if displaying Scpu data or the next vproc if displaying Svpr data. Utilities 373

374 Chapter 13: RSS Monitor (rssmon) Displaying ResUsage Data 374 Utilities

375 CHAPTER 14 Show Locks (showlocks) The Show Locks utility, showlocks, provides information about Host Utility (HUT) locks placed on databases and tables by the Archive/Recovery (ARC) utility during database operations. These locks might interfere with application processing and should be released after utility processing is complete. Showlocks also displays information about locks placed during a Teradata Database system failure. Audience Users of Showlocks include the following: Teradata Database operators Teradata Database administrators Teradata Database system administrators Teradata Database system programmers User Interfaces showlocks runs on the following platforms and interfaces: Platform MP-RAS Windows Linux MVS/VM Interfaces Database Window Database Window Database Window Host Utility Console (HUTCNS) For general information on starting the utilities from different platforms and interfaces, see Appendix B: Starting the Utilities. Utilities 375

376 Chapter 14: Show Locks (showlocks) Host Utility Locks Host Utility Locks You can release HUT locks either by submitting a separate RELEASE LOCK SQL command, or by using the RELEASE LOCK option of the appropriate command. For example, ARCHIVE, ROLLBACK, RESTORE, BUILD, and ROLLFORWARD. HUT locks placed by the Archive/Recovery utility differ from locks placed by other operations or transactions. HUT locks have the following characteristics: Archive/Recovery locks are associated with the currently logged-on user who entered the command, rather than with a batch job or transaction. Only the AMPs that are participating in the Archive/Recovery operation are locked. Archive/Recovery locks placed at one level of an object never conflict with a utility lock at another level that was placed on the same object for the same user. The locking modes and levels are applied as follows: A Read lock is placed on an object being dumped. Locks are placed at the cluster level during a CLUSTER dump. If a table being dumped is defined for an after-image permanent journal (and the appropriate option was selected on the DUMP command), a group Read lock is placed on the table rows. A Write lock is placed on all tables involved in ROLLFORWARD and ROLLBACKWARD recovery operations. A Write lock is placed on a journal table that is being deleted. A Write lock is placed on a permanent journal table that is being restored. An Exclusive lock is placed on any object being restored that is not a journal table. Archive/Recovery locks remain active until you release them. Note: If Archive/Recovery locks are not specifically released, they are automatically reinstated following a Teradata Database or client system restart. Interpreting the Showlocks Display The Showlocks display provides this information: Summary of the showlocks function Name of the databases and tables on which locks are placed Username that placed each lock Lock mode: read, write, exclusive, or access Number of the AMPs on which the locked database or table resides 376 Utilities

377 Chapter 14: Show Locks (showlocks) Interpreting the Showlocks Display Showlocks reports All AMPs rather than individual AMP numbers when the locked database or table resides on all AMPs. Information is provided for only the most restrictive lock a user has placed on an object. An example of a complete Showlocks display is shown below. / / \ --- / / / / \ \ \ \ \ Release Version Show Locks Utility (May 95) This program queries all AMPs and reports all Host Utility locks. which currently exist at both the data base level and the table level. For each lock which is found, an entry will appear on your console which includes the following information: - Data Base Name - Table Name (if applicable) - User Name of user who placed lock - Lock Mode - AMP Number accounting.invoice USER ADMIN MODE Read AMP All AMPs parts USER PETERS MODE Read AMP 24 personnel.employee USER ACCMGR MODE Excl AMP 27 service USER DBC MODE Excel AMP 3 --ShowLocks Processing Complete-- In the previous example, exclusive locks are placed on the employee table in the personnel database and on the entire service database. One read lock is placed on the parts database, and another read lock on the invoice table in the accounting database. Also, the following locks are applied. Username... Placed the lock on the... ADMIN invoice table that resides on all AMPs. PETERS parts database which resides on AMP 24. ACCMGR portion of the employee table that resides on AMP 27. DBC portion of the service database that resides on AMP 3. When no locks are found, Showlocks reports this message: There are currently no host utility locks in the DBS. Utilities 377

378 Chapter 14: Show Locks (showlocks) Conflicts Conflicts If a host utility lock that conflicts with Showlocks is in place when Showlocks is executed, the Teradata Database system displays this message: Unable to proceed due to xxxx lock on yyyy where: Syntax element... Is... xxxx yyyy either a Write or Exclusive lock. DBC, DBC.TVM, or DBC.DBase. After reporting a conflict, Showlocks terminates. 378 Utilities

379 CHAPTER 15 System Initializer (sysinit) The System Initializer utility, sysinit, does the following: Initializes the Teradata Database Creates or updates the DBS Control Record and other Globally Distributed Objects (GDOs) Initializes or updates configuration maps Allows you to set the hash function value in the DBS Control Record Audience Users of System Initializer include the following: Field engineers Teradata Database system developers Teradata Database system engineers User Interfaces sysinit runs on the following platforms and interfaces: Platform MP-RAS Windows Linux Interfaces Database Window Database Window Database Window sysinit completes after you respond to the last prompt in the user dialog. You can terminate sysinit early by entering Quit in response to certain prompts. In either case, sysinit displays a message indicating that sysinit is complete or was terminated. For a description of these prompts and messages, see Running System Initializer on page 381. For general information on starting the utilities from different platforms and interfaces, see Appendix B: Starting the Utilities. Utilities 379

380 Chapter 15: System Initializer (sysinit) Initializing Teradata Database with System Initializer Initializing Teradata Database with System Initializer New Systems Running sysinit is part of the overall Teradata Database system initialization process. sysinit handles Teradata Database system configuration differently, depending on the following: The Teradata Database is being initialized for the first time The Teradata Database was initialized previously When used in a new Teradata Database system, sysinit initializes a configuration that includes all the vprocs defined in a vprocconfig GDO. On a new, uninitialized, Teradata Database system (or on a corrupted Teradata Database system whose configuration map cannot be read), sysinit creates a full configuration based on the vprocconfig GDO. All the vprocs are set online. If a problem exists with any vproc, then a 0 PE, 1 AMP configuration is created. If a full configuration was created, then you are given options later for selecting a particular configuration for the new and old config maps. Previously Initialized Systems Warning: You must use sysinit with caution in a previously initialized Teradata Database system because sysinit will destroy all user and dictionary data currently in the Teradata Database system. On a previously initialized Teradata Database system, sysinit retains the current configuration map and prompts you to do one of the following: Retain the current configuration in the new configuration map Select a different configuration for the current and the new configuration maps Globally Distributed Objects GDOs are a fixed set of named objects that is kept consistent across all nodes and vprocs in a Teradata Database system. A GDO is shared by all vprocs and presents the same picture of its state to all of them. GDOs frequently store system settings and configuration information that is shared by all nodes of the system. sysinit initializes several Teradata Database GDOs automatically. Depending on the state of the DBS Control Record and the current configuration when sysinit is run, sysinit prompts you for certain information, such as the hash function and locale (Japanese support). For information on these prompts, see Running System Initializer on page Utilities

381 Chapter 15: System Initializer (sysinit) Running System Initializer Configuration Maps Configuration maps define the current/new configuration of the Teradata Database system vprocs. A configuration map does the following: Stores the identification and status of each vproc in the Teradata Database system Identifies the AMPs that constitute each AMP cluster Identifies each PE and its associated host The Teradata Database system contains two configuration maps, as follows: The current configuration map, which describes the current arrangement and status of vprocs in the Teradata Database system The new configuration map, which describes changes and additions to the configuration sysinit can create a new configuration map and keep or revise a current map. For the new configuration maps initialized by sysinit from the current configuration, the current configuration can retain one AMP and all existing PEs. The new configuration can retain one or all AMPs and all existing PEs. Running System Initializer Warning: Running sysinit on a previously initialized Teradata Database system destroys all existing data and deletes all tables. 1 Start sysinit. The following message appears: W A R N I N G This program will destroy all user and dictionary data on the system. SYSINIT Master AMP Vproc is 0 at 11:25:42 on 00/04/14 If the Teradata Database system is running, sysinit displays the following message also: The DBS is currently running!!! SYSINIT cannot execute while the DBS is running. Would you like to restart the system without the DBS (YES/NO)? 2 At the prompt, answer one of the following: IF you answer... THEN sysinit... YES does the following: Implicitly sets the Start DBS flag to Off in the PDE control parameters GDO Automatically restarts the Teradata Database system Displays the following message and exits: SYSINIT terminated without updating disks. You will have to start sysinit again. Utilities 381

382 Chapter 15: System Initializer (sysinit) Running System Initializer IF you answer... THEN sysinit... NO displays the following message and exits: Set the "Start DBS" flag to "Off" using the XCTL utility program and restart the system prior to running SYSINIT again. sysinit terminated without updating disks. 3 In this case, you must terminate sysinit, type: NO 4 Use ctl (Linux or Windows) or xctl (MP-RAS) to set the Start DBS flag to OFF. For information, see Control GDO Editor (ctl) and Xctl Utility in volumes one and three of Utilities. 5 Restart sysinit. The following message appears: W A R N I N G This program will destroy all user and dictionary data on the system. A display indicating the console AMP vproc number, the current time, and the current date, as shown below: SYSINIT Master AMP Vproc is 0 at 11:25:42 on 00/04/14 6 sysinit attempts to read the DBS Control Record GDO. The DBS Control Record is a GDO that contains the global variables that the Teradata Database system needs, including the hash function value. sysinit handles the DBS Control Record differently, depending on whether the Teradata Database system was initialized previously or is being initialized for the first time. IF the DBS Control Record GDO... THEN sysinit displays the following message... is corrupted or does not exist does exist A new DBS Control Record will be initialized to default values. If a new DBS Control Record is used, the file system tunables in the GDO are the default values. indicating: The existing DBS CONTROL GDO will be used. If an existing DBS Control record is used, the action depends on the current values for the File System tunables and the value of Disk Blocks Per Cylinder. For an explanation of the File System tunables, their definition, and how to change their values, see DBS Control Utility in Utilities. If the DBS Control Record exists, the Teradata Database system was previously initialized. In this case, sysinit keeps the current values in the DBS Control Record, but you can change the current values for the hash function or the locale attribute later. 382 Utilities

383 Chapter 15: System Initializer (sysinit) Running System Initializer Note: sysinit supports old hashing functions. After starting sysinit, the following message appears and prompts you for action: The HashFuncDBC value in the DBSCONTROL GDO is International Universal Hash is recommended for all new installations Do you wish to use Universal Hash (YES/NO/QUIT)? IF you answer... THEN sysinit displays the following... YES Enable Japanese language support (YES/NO/QUIT)? IF you answer... THEN you get... And... YES NO Japanese support standard support object names can contain characters from the JIS X 0201, and JIS X 0208 standard. The object names are stored in the Data Dictionary as UNICODE. The object names are processed internally by the database as KANJI1. The default server character set for all users is UNICODE. Japanese language support makes Japanese characters and functions available. Enabling Japanese Language Support might impact Teradata Database system performance. object names can contain LATIN characters The object names are stored in the Data Dictionary as UNICODE. The object names are processed internally by the database as LATIN The default server character set for non-dbc users is LATIN. The default server character set for user DBC is UNICODE. Utilities 383

384 Chapter 15: System Initializer (sysinit) Running System Initializer IF you answer... THEN sysinit displays the following... NO Enter hash function 1 Universal Hash - Japanese/no Japanese support 2 Kanji Hash - Japanese support 3 International Hash - no Japanese support Type the hash setting you want (for example: 2). The locale is set based on the hash setting: For Kanji hash (2), Japanese language support is enabled. For International hash (3), Japanese language support is not enabled. 7 sysinit attempts to read the current configuration map. IF a valid configuration map... THEN sysinit... does not exist or is corrupted does exist initializes the configuration to a full configuration based on vprocconfig GDO and displays the following: Config Map will be initialized. retains the current configuration and displays the following message: The current configuration map has been read. 8 sysinit displays a message about destroying user and dictionary data and prompts you to confirm this action, as shown below: SYSINIT is about to destroy all user and dictionary data. Are you sure that you want to do this? (YES/NO/QUIT)? IF you answer... YES NO or QUIT THEN sysinit displays the following message Deleting all tables... before terminating: SYSINIT terminated without updating disks. 9 If you answer YES, sysinit checks to see if AMP vproc 0 is defined or if the hardware required to run AMP vproc 0 is available. If not, one of the following messages is displayed before sysinit terminates: or AMP vproc 0 is not operational. SYSINIT terminated without updating disks. AMP vproc 0 is not defined. SYSINIT terminated without updating disks. 384 Utilities

385 Chapter 15: System Initializer (sysinit) Running System Initializer sysinit will not initialize any AMPs that are not operational, that is, their VprocState is NONODE. The following message is displayed if any are found: The following AMPs are defined in the current configuration map and the physical hardware required to run them is not available. Hence, they will not be initialized by SYSINIT. nnnn nnnn nnnn... where nnnn nnnn nnnn... represent the vproc numbers of the AMPs in question. 10 For a previously initialized Teradata Database system where sysinit was able to read the current configuration, sysinit first displays the current number of AMPs and PEs, as follows: Accessing the current configuration map... The current configuration map includes: 4 PE(s) and 8 AMP(s) 11 If more than one AMP and one PE exist, sysinit displays four options for the current and new configuration maps, as follows: The current configuration map includes: 4 PE(s) and 8 AMP(s) Enter a value for the current/new configuration maps: 1 for current: 4 PE(s) and 8 AMP(s) new: 4 PE(s) and 8 AMP(s) 2 for current: 4 PE(s) and 1 AMP(s) new: 4 PE(s) and 1 AMP(s) 3 for current: 0 PE(s) and 1 AMP(s) new: 4 PE(s) and 8 AMP(s) 4 for current: 0 PE(s) and 1 AMP(s) new: 0 PE(s) and 1 AMP(s) 12 Type a value for the current/new configuration maps (for example: 1): 1 13 sysinit displays the following messages to confirm your selection: Updating the new configuration to: 4 PE(s) and 8 AMP(s) Updating the current configuration to: 4 PE(s) and 8 AMP(s) Updating current hash maps Before terminating, sysinit prompts you for the following action: Would you like to continue with startup (YES/NO)? IF you answer... THEN the following message appears... YES if you previously set the Start ALL Appls flag in XCTL to Off: The CONTROL GDO has 'Start ALL applications' turned off. This will prevent the database application from starting. Would you like to turn it on (YES/NO)? Note: This applies only to MP-RAS. Utilities 385

386 Chapter 15: System Initializer (sysinit) Running System Initializer IF you answer... THEN the following message appears... IF you answer... THEN sysinit... YES NO turns on the Start DBS flag and quits. displays the following message and quits: Don t forget to reset the Start DBS flag to On using the XCTL utility program prior to restarting the system. NO Don't forget to set the "Start DBS" flag to "On" using XCTL utility program prior to restarting the system. SYSINIT complete. After displaying the message, sysinit quits. Configuration and Reconfiguration Utilities Examples After the Teradata Database system is initialized, run the Configuration and Reconfiguration utilities to define the AMPs and PEs that will operate together as a Teradata Database system. The Configuration utility adds, changes, modifies, or displays vprocs or hosts in the new configuration map. The Reconfiguration utility then redefines the Teradata Database system configuration according to the new map. For more information, see Chapter 7: Configuration utility in Utilities Volume 3, and in Chapter 10 Reconfiguration Utility (reconfig) in Utilities Volume 2. Example 1 This example shows that after the user started sysinit, a message stating that the Teradata Database system is running appears, and sysinit terminates. / / \ --- / / / / \ \ \ \ \ Release Version SYSINIT Utility (June 2000) 386 Utilities

387 Chapter 15: System Initializer (sysinit) Running System Initializer ********************************************************************* ********************************************************************* ***** *** ***** W A R N I N G *** ***** *** ***** This program will destroy all user and dictionary data on *** ***** the system. *** ***** *** ********************************************************************* ********************************************************************* SYSINIT Master AMP Vproc is 0 at 10:40:47 on 07/04/14.+ The DBS is currently running!!! SYSINIT cannot execute while the DBS is running. Would you like to restart the system without the DBS (YES/NO)? no Set the "Start DBS" flag to "Off" using the XCTL utility program and restart the system prior to running SYSINIT again. SYSINIT terminated without updating disks. Example 2 The following example shows a complete sysinit session, including prompts, user responses, and messages. The example assumes a previously configured Teradata Database with an existing DBS Control Record and an existing current configuration map. Universal Hash is accepted. / / \ --- / / / / \ \ \ \ \ Release 12x Version 12x SYSINIT Utility (June 2000) *********************************************************************** *********************************************************************** ***** ***** ***** W A R N I N G ***** ***** ***** ***** This program will destroy all user and dictionary data on ***** ***** the system. ***** ***** ***** *********************************************************************** *********************************************************************** SYSINIT Master AMP Vproc is 0 at 16:32:15 on 07/10/22. The existing DBSCONTROL GDO will be used. System is being initialized to 20-bit hash buckets. Utilities 387

388 Chapter 15: System Initializer (sysinit) Running System Initializer The HashFuncDBC value in the DBSCONTROL GDO is Universal Universal hash is recommended for all new installations Do you wish to use Universal Hash (YES/NO/QUIT)? yes Enable Japanese language support (YES/NO/QUIT)? no SYSINIT is about to destroy all user and dictionary data!!! Are you sure that you want to do this (YES/NO/QUIT)? yes Deleting all tables... Accessing the current configuration map... The current configuration map includes: 1 PE(s) and 4 AMP(s) Enter a value for the current/new configuration maps: 1 for current: 1 PE(s) and 4 AMP(s) new: 1 PE(s) and 4 AMP(s) 2 for current: 1 PE(s) and 1 AMP(s) new: 1 PE(s) and 1 AMP(s) 3 for current: 0 PE(s) and 1 AMP(s) new: 1 PE(s) and 4 AMP(s) 1 4 for current: 0 PE(s) and 1 AMP(s) new: 0 PE(s) and 1 AMP(s) Updating the new configuration to: 1 PE(s) and 4 AMP(s) Updating the current configuration to: 1 PE(s) and 4 AMP(s) Updating current hash maps... Would you like to continue with start up (YES/NO)? yes SYSINIT complete. 388 Utilities

389 APPENDIX A How to Read Syntax Diagrams This appendix describes the conventions that apply to reading the syntax diagrams used in this book. Syntax Diagram Conventions Notation Conventions The following table defines the notation used in this section: Item Definition / Comments Letter An uppercase or lowercase alphabetic character ranging from A through Z. Number A digit ranging from 0 through 9. Do not use commas when typing a number with more than three digits. Word Variables and reserved words. IF a word is shown in... THEN it represents... UPPERCASE LETTERS lowercase letters lowercase italic letters lowercase bold letters UNDERSCORED LETTERS a keyword. Syntax diagrams show all keywords in uppercase, unless operating system restrictions require them to be in lowercase. If a keyword is shown in uppercase, you can type it in uppercase or mixed case. a keyword that you must type in lowercase, such as a UNIX command. a variable such as a column or table name. You must substitute a proper value. a variable that is defined immediately following the diagram that contains the variable. the default value. This applies both to uppercase and to lowercase words. Utilities 389

390 Appendix A: How to Read Syntax Diagrams Syntax Diagram Conventions Item Spaces Punctuation Definition / Comments Use one space between items, such as keywords or variables. Type all punctuation exactly as it appears in the diagram. Paths The main path along the syntax diagram begins at the left, and proceeds, left to right, to the vertical bar, which marks the end of the diagram. Paths that do not have an arrow or a vertical bar only show portions of the syntax. The only part of a path that reads from right to left is a loop. Paths that are too long for one line use continuation links. Continuation links are small circles with letters indicating the beginning and end of a link: A A Required Items When you see a circled letter in a syntax diagram, go to the corresponding circled letter and continue. Required items appear on the main path: FE0CA002 SHOW FE0CA003 If you can choose from more than one item, the choices appear vertically, in a stack. The first item appears on the main path: SHOW CONTROLS VERSIONS FE0CA Utilities

391 Appendix A: How to Read Syntax Diagrams Syntax Diagram Conventions Optional Items Optional items appear below the main path: SHOW CONTROLS FE0CA004 If choosing one of the items is optional, all the choices appear below the main path: SHOW CONTROLS VERSIONS FE0CA006 Abbreviations You can choose one of the options, or you can disregard all of the options. If a keyword or a reserved word has a valid abbreviation, the unabbreviated form always appears on the main path. The shortest valid abbreviation appears beneath. SHOW CONTROLS CONTROL FE0CA042 In the above syntax, the following formats are valid: SHOW CONTROLS SHOW CONTROL Loops A loop is an entry or a group of entries that you can repeat one or more times. Syntax diagrams show loops as a return path above the main path, over the item or items that you can repeat. (, 3, 4 cname ) JC01B012 Utilities 391

392 Appendix A: How to Read Syntax Diagrams Syntax Diagram Conventions The following rules apply to loops: IF... THEN... there is a maximum number of entries allowed there is a minimum number of entries required a separator character is required between entries a delimiter character is required around entries the number appears in a circle on the return path. In the example, you may type cname a maximum of 4 times. the number appears in a square on the return path. In the example, you must type at least three groups of column names. the character appears on the return path. If the diagram does not show a separator character, use one blank space. In the example, the separator character is a comma. the beginning and end characters appear outside the return path. Generally, a space is not needed between delimiter characters and entries. In the example, the delimiter characters are the left and right parentheses. Excerpts Sometimes a piece of a syntax phrase is too large to fit into the diagram. Such a phrase is indicated by a break in the path, marked by terminators on either side of the break. A name for the excerpted piece appears between the break marks in boldface type. The named phrase appears immediately after the complete diagram, as illustrated by the following example. LOCKING excerpt A A HAVING con where_cond excerpt, cname, col_pos JC01A Utilities

393 APPENDIX B Starting the Utilities This appendix describes how to start Teradata Database utilities. Teradata offers several user interfaces from which the utilities may be started: Interface Command line Database Window (DBW) Teradata MultiTool Host Utility Console (HUTCNS) Supported Platforms MP-RAS, Windows, Linux MP-RAS, Windows Windows, Linux MVS, VM Note: Not all utilities support all the user interfaces. For a listing of supported user interfaces for each utility, see the documentation for that utility. Once started, some utilities present their own interactive command-line or graphical user interfaces. These utilities let you browse and enter information until you explicitly exit the utility. Other utilities simply present information about the current state of Teradata Database and exit automatically. Utilities 393

394 Appendix B: Starting the Utilities MP-RAS MP-RAS On MP-RAS, the utilities can be run from Database Window (DBW) and from the command line. Starting Utilities from Database Window On MP-RAS, DBW is an X client program that requires an X server to be running on the local machine. DBW supports standard X Windows display forwarding. To ensure that the graphical user interface displays properly, you can use the standard -display option to specify the host name or IP address of the local machine. To start a utility from Database Window 1 Open DBW from the MP-RAS command line by typing: xdbw display displayspec & where displayspec is the name or IP address of the local machine, followed by a colon and the server number, typically 0 or 0.0. For example: xdbw -display myworkstation.mycompany.com:0.0 & or xdbw -display :0.0 & The DBW main window opens. 394 Utilities

395 Appendix B: Starting the Utilities MP-RAS 2 Click the supvr button to open the Supervisor (supv) window. 3 Under Enter a command type: start utilityname [options] where utilityname is the name of the utility, and options can include any of the available command-line options and arguments of that utility. utilityname is not case-sensitive. The following message appears: Started 'utilityname' in window x where x is the number of one of the four available application windows DBW provides. Each utility started runs in one of the four application windows. The title bar of the application window and the corresponding button in the DBW main window change to reflect the name of the running utility. When the utility stops running, the application window and main window button revert to the default text title (that is, Appl1, Appl2, and so forth). Note: Up to four utilities can be run concurrently in DBW. The message All Interactive Partitions are busy!! indicates that all four application windows are occupied. In this case, one of the four running utilities must be quit before another can be started. For more information on Database Window, and on options available with the START command, see Graphical User Interfaces: Database Window and Teradata MultiTool. Utilities 395

396 Appendix B: Starting the Utilities MP-RAS Starting Utilities from the Command Line To start a utility from the command line On the command line type: utilityname [options] where utilityname is the name of the utility, and options can include any of the available command-line options and arguments of that utility. X Windows GUIs Some utilities on MP-RAS offer X Windows (X11) based graphical user interfaces. These utilities, whose program names generally begin with x, are launched from the MP-RAS command line. Use the X Windows -display option to specify the name or IP address and display server screen (typically 0 or 0.0) when starting these utilities. For example: xdbw -display myworkstation.mycompany.com:0.0 & or xdbw -display :0.0 & 396 Utilities

397 Appendix B: Starting the Utilities Windows Windows On Windows, the utilities can be run from Database Window, Teradata MultiTool, and from the Teradata Command Prompt. Starting Utilities from Teradata MultiTool Many of the Teradata Database utilities can be started from Teradata MultiTool. To start a utility from Teradata MultiTool 1 Start Teradata MultiTool from Windows by clicking Start>Programs>Teradata Database>Teradata MultiTool. The Teradata MultiTool window opens. Teradata MultiTool provides a tabbed graphical interface to the Teradata Console Subsystem (CNS), Database Window (DBW), and these utilities: Control GDO Editor (CTL), Database Initialization Program (DIP), and VProc Manager. To start these utilities, choose them from the MultiTool Tools menu. Many of the other Teradata Database utilities can be started from DBW in MultiTool. 2 Open DBW from Teradata MultiTool by clicking: Tools>Database Window (DBW) Database Window opens to the Supervisor tab. Utilities 397

398 Appendix B: Starting the Utilities Windows 3 On the Command: input line of the Supervisor tab type: start utilityname [options] where utilityname is the name of the utility, and options can include any of the available command-line options and arguments of that utility. utilityname is not case-sensitive. The utility starts in the first available Application tab, which comes to the front of the DBW tabs. The name of the tab changes to reflect the name of the utility. Note: Up to four utilities can be run concurrently in DBW. The message All Interactive Partitions are Busy!! appears if all four application tabs are occupied. In this case, one of the four running utilities must be quit before another can be started. For more information on Database Window, and on options available with the START command, see Graphical User Interfaces: Database Window and Teradata MultiTool. Starting Utilities from Database Window On Windows, Teradata Database includes a stand-alone version of Database Window that can run without Teradata MultiTool. This version of Database Window opens separate windows, rather than tabs, for input and output. To start a utility from Database Window 1 Open Database Window (DBW) from the Windows Start menu by clicking: Start>Programs>Teradata Database>Database Window 398 Utilities

399 Appendix B: Starting the Utilities Windows The DBW main window opens. 2 Click the Supvr button to open the Supervisor (supv) window. 3 Under Enter a command type: start utilityname [options] where utilityname is the name of the utility, and options can include any of the available command-line options and arguments of that utility. utilityname is not case-sensitive. The following message appears: Started 'utilityname' in window x where x is the number of one of the four available application windows DBW provides. Utilities 399

400 Appendix B: Starting the Utilities Windows Each utility started runs in one of the four application windows. The title bar of the application window and the corresponding button in the DBW main window change to reflect the name of the running utility. When the utility stops running, the application window and main window button revert to the default text title (that is, Appl1, Appl2, and so forth). Note: DBW can run up to four utilities concurrently. If you see the following message, you must quit one of the four running utilities before starting another. CNSSUPV start: All Interactive Partitions are busy!! For more information on Database Window, and on options available with the START command, see Graphical User Interfaces: Database Window and Teradata MultiTool. Starting Utilities from the Teradata Command Prompt The Teradata Command Prompt is a Windows command line that has been modified for use with Teradata. Teradata adds certain directories to the PATH environment variable on your computer, which allows most command-line utilities to be run by typing their name at the Teradata Command Prompt. To start a utility from the Teradata Command Prompt 1 Start the Teradata Command Prompt from Windows by clicking: Start>Programs>Teradata Database>Teradata Command Prompt 2 Type: utilityname [options] where utilityname is the name of the utility, and options can include any of the available command line options and arguments of that utility. utilityname is not case-sensitive. You can also use the Windows start command to open the utility in a separate command window. For example: C:\Documents and Settings\Administrator> start lokdisp 400 Utilities

401 Appendix B: Starting the Utilities Linux Linux On Linux, the utilities can be run from Teradata MultiTool, Database Window, and from the command line. Note: When starting a Linux session, run tdatcmd from the command line to set up the Teradata environment. It is only necessary to run tdatcmd (located by default in /usr/pde/bin) once per Linux session. It adds certain directories to the PATH environment variable on the local computer, which allows most command-line utilities to be run by typing their name. Starting Utilities from Teradata MultiTool Many of the Teradata Database utilities can be started from Teradata MultiTool. To start a utility from Teradata MultiTool 1 If not already done, set up the Teradata environment by typing: tdatcmd at the Linux command line. 2 Open Teradata MultiTool by typing one of the following: From the console of the Linux system, or if telnetting directly to it, type: multitool -autodisplay & In other cases type: multitool -display displayspec & where displayspec is the name or IP address of the local machine, followed by a colon and the server number, typically 0 or 0.0. For example: multitool -display myworkstation.mycompany.com:0.0 & or multitool -display :0.0 & The Teradata MultiTool window opens. Utilities 401

402 Appendix B: Starting the Utilities Linux Teradata MultiTool provides a tabbed graphical interface to the Teradata Console Subsystem (CNS), Database Window (DBW), and these utilities: Control GDO Editor (CTL), Database Initialization Program (DIP), and VProc Manager. To start these utilities, choose them from the MultiTool Tools menu. Many of the other Teradata Database utilities can be started from DBW in MultiTool. 3 Open DBW from Teradata MultiTool by clicking Tools>Database Window (DBW) Database Window opens. 402 Utilities

403 Appendix B: Starting the Utilities Linux 4 On the Command: input line of the Supervisor tab type: start utilityname [options] where utilityname is the name of the utility, and options can include any of the available command-line options and arguments of that utility. utilityname is not case-sensitive. The utility starts in the first available Application tab, which comes to the front of the DBW tabs. The name of the tab changes to reflect the name of the utility. DBW can run up to four utilities concurrently. If an attempt is made to run a fifth utility, a message appears stating All Interactive Partitions are Busy!! In this case, quit one of the four running utilities before starting another. For more information on Database Window, and on options available with the START command, see Graphical User Interfaces: Database Window and Teradata MultiTool. Starting Utilities from Database Window On Linux, Teradata Database includes a stand-alone version of Database Window (DBW) that can run without Teradata MultiTool. This version of Database Window opens separate windows, rather than tabs, for input and output. This version of Database Window is an X client program that requires an X server to be running on the local machine. DBW supports standard X Windows display forwarding. To ensure that the graphical user interface displays properly, you can use the standard -display option to specify the host name or IP address of the local machine. To Start a utility from Database Window 1 If not already done, set up the Teradata environment by typing: tdatcmd at the Linux command line. 2 Open DBW from the Linux command line by typing: xdbw display displayspec & where displayspec is the name or IP address of the local machine, followed by a colon and the server number, typically 0 or 0.0. For example: xdbw -display myworkstation.mycompany.com:0.0 & or xdbw -display :0.0 & The DBW main window opens. Utilities 403

404 Appendix B: Starting the Utilities Linux 3 Click the Supvr button to open the Supervisor (supv) window. 4 Under Enter a command type: start utilityname [options] where utilityname is the name of the utility, and options can include any of the available command-line options and arguments of that utility. utilityname is not case-sensitive. The following message appears: Started 'utilityname' in window x 404 Utilities