What would you do if you knew? Teradata Debugger for C/C++ UDF User Guide Release B K January 2016

Transcription

1 What would you do if you knew? Teradata Debugger for C/C++ UDF User Guide Release B K January 2016

2 The product or products described in this book are licensed products of Teradata Corporation or its affiliates. Teradata, Active Data Warehousing, Active Enterprise Intelligence, Applications-Within, Aprimo Marketing Studio, Aster, BYNET, Claraview, DecisionCast, Gridscale, MyCommerce, QueryGrid, SQL-MapReduce, Teradata Decision Experts, "Teradata Labs" logo, Teradata ServiceConnect, Teradata Source Experts, WebAnalyst, and Xkoto are trademarks or registered trademarks of Teradata Corporation or its affiliates in the United States and other countries. Adaptec and SCSISelect are trademarks or registered trademarks of Adaptec, Inc. AMD Opteron and Opteron are trademarks of Advanced Micro Devices, Inc. Apache, Apache Avro, Apache Hadoop, Apache Hive, Hadoop, and the yellow elephant logo are either registered trademarks or trademarks of the Apache Software Foundation in the United States and/or other countries. Apple, Mac, and OS X all are registered trademarks of Apple Inc. Axeda is a registered trademark of Axeda Corporation. Axeda Agents, Axeda Applications, Axeda Policy Manager, Axeda Enterprise, Axeda Access, Axeda Software Management, Axeda Service, Axeda ServiceLink, and Firewall-Friendly are trademarks and Maximum Results and Maximum Support are servicemarks of Axeda Corporation. Data Domain, EMC, PowerPath, SRDF, and Symmetrix are registered trademarks of EMC Corporation. GoldenGate is a trademark of Oracle. Hewlett-Packard and HP are registered trademarks of Hewlett-Packard Company. Hortonworks, the Hortonworks logo and other Hortonworks trademarks are trademarks of Hortonworks Inc. in the United States and other countries. Intel, Pentium, and XEON are registered trademarks of Intel Corporation. IBM, CICS, RACF, Tivoli, and z/os are registered trademarks of International Business Machines Corporation. Linux is a registered trademark of Linus Torvalds. LSI is a registered trademark of LSI Corporation. Microsoft, Active Directory, Windows, Windows NT, and Windows Server are registered trademarks of Microsoft Corporation in the United States and other countries. NetVault is a trademark or registered trademark of Dell Inc. in the United States and/or other countries. Novell and SUSE are registered trademarks of Novell, Inc., in the United States and other countries. Oracle, Java, and Solaris are registered trademarks of Oracle and/or its affiliates. QLogic and SANbox are trademarks or registered trademarks of QLogic Corporation. Quantum and the Quantum logo are trademarks of Quantum Corporation, registered in the U.S.A. and other countries. Red Hat is a trademark of Red Hat, Inc., registered in the U.S. and other countries. Used under license. SAP is the trademark or registered trademark of SAP AG in Germany and in several other countries. SAS and SAS/C are trademarks or registered trademarks of SAS Institute Inc. Simba, the Simba logo, SimbaEngine, SimbaEngine C/S, SimbaExpress and SimbaLib are registered trademarks of Simba Technologies Inc. SPARC is a registered trademark of SPARC International, Inc. Symantec, NetBackup, and VERITAS are trademarks or registered trademarks of Symantec Corporation or its affiliates in the United States and other countries. Unicode is a registered trademark of Unicode, Inc. in the United States and other countries. UNIX is a registered trademark of The Open Group in the United States and other countries. Other product and company names mentioned herein may be the trademarks of their respective owners. The information contained in this document is provided on an "as-is" basis, without warranty of any kind, either express or implied, including the implied warranties of merchantability, fitness for a particular purpose, or non-infringement. Some jurisdictions do not allow the exclusion of implied warranties, so the above exclusion may not apply to you. In no event will Teradata Corporation be liable for any indirect, direct, special, incidental, or consequential damages, including lost profits or lost savings, even if expressly advised of the possibility of such damages. The information contained in this document may contain references or cross-references to features, functions, products, or services that are not announced or available in your country. Such references do not imply that Teradata Corporation intends to announce such features, functions, products, or services in your country. Please consult your local Teradata Corporation representative for those features, functions, products, or services available in your country. Information contained in this document may contain technical inaccuracies or typographical errors. Information may be changed or updated without notice. Teradata Corporation may also make improvements or changes in the products or services described in this information at any time without notice. To maintain the quality of our products and services, we would like your comments on the accuracy, clarity, organization, and value of this document. Please 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 2016 by Teradata. All Rights Reserved.

3 Table of Contents Preface...5 Purpose... 5 Audience... 5 Revision History... 5 Supported Releases... 5 Additional Information...6 Related Links...6 Related Documentation...6 Customer Education... 6 Product Safety Information...6 Chapter 1: Introduction...7 Teradata Debugger for C/C++ UDF Overview... 7 Capabilities... 7 Recommended Test Environment... 8 Debug Configuration Types... 8 Working with Online Help... 9 Setting the Key Binding... 9 Chapter 2: Configuring a Debug Session...11 Running a UDF Query in Debug Mode Adding the Debugger Port Debug Configurations...11 Project and Source Code Management Linking a Source Folder to a Project...13 Creating a Remote Debug Configuration Creating a Local Debug Configuration Starting a Debug Session Teradata Debugger for C/C++ UDF User Guide, Release

4 Table of Contents Chapter 3: Working with the Debugger...17 Editor View Displaying Source Code Setting a Line Breakpoint Setting a Function Breakpoint Setting a Conditional Breakpoint Debug View...19 Basic Debug View Functions...20 Teradata Debug View Functions...20 Aborting a Query Adding a UDF...21 Holding and Unholding UDF Threads...21 Locating the Current Thread Secondary Breakpoints Teradata Watchpoint View...22 Opening the Teradata Watchpoint View Adding a Watchpoint Removing a Watchpoint Teradata Map View Opening the Teradata Map View...24 Console View Monitoring the Backend Teradata Debugger for C/C++ UDF User Guide, Release 15.10

5 Preface Purpose The Teradata Debugger for C/C++ UDF User Guide describes how to use the Teradata Debugger for C/C++ UDF Eclipse plug-in to debug Teradata Database user-defined functions (UDFs), user-defined methods (UDMs), and external stored procedures. Audience This guide is intended for use by: Teradata Database administrators Developers of C/C++ user-defined functions, user-defined methods, and external stored procedures Revision History Date Release Description January Initial release Supported Releases The Teradata Debugger for C/C++ UDF Eclipse plug-in supports Teradata Database release and later releases. Teradata Debugger for C/C++ UDF User Guide, Release

6 Preface Additional Information Related Links URL Description Use Teradata At Your Service to access Orange Books, technical alerts, and knowledge repositories, view and join forums, and download software packages. External site for product, service, resource, support, and other customer information. Related Documentation Documents are located at Title Teradata Debugger for C/C++ UDF Installation Guide Publication ID B Describes how to install the Teradata Debugger for C/C++ UDF Eclipse plug-in. SQL External Routine Programming B Describes how to program Teradata Database user-defined functions (UDFs), user-defined methods (UDMs), and external stored procedures. SQL Data Control Language B Describes the Teradata SQL Data Control Language (DCL) statements used to manage access to the database objects and data in the system. Customer Education Teradata Customer Education delivers training for your global workforce, including scheduled public courses, customized on-site training, and web-based training. For information about the classes, schedules, and the Teradata Certification Program, go to Product Safety Information This document may contain information addressing product safety practices related to data or property damage, identified by the word Notice. A notice indicates a situation which, if not avoided, could result in damage to property, such as equipment or data, but not related to personal injury. Example Notice: Improper use of the Reconfiguration utility can result in data loss. 6 Teradata Debugger for C/C++ UDF User Guide, Release 15.10

7 CHAPTER 1 Introduction Teradata Debugger for C/C++ UDF Overview The Teradata Debugger for C/C++ UDF Eclipse plug-in (referred to hereafter as the Debugger) provides a full-featured graphical user interface to the Teradata UDF Debugger (referred to as tdgdb). Prior to the introduction of this plug-in, users could only run the tdgdb executable from a Linux command line. The command line option is still available for those users who prefer it. The Debugger provides an integrated Teradata Database debugging environment that enhances the information available from tdgdb and frees users from having to remember tdgdb commands. The Debugger supports external routines running in secure or protected mode. It does not support routines running in unprotected mode. UDFs that are intended to run in unprotected mode can be debugged in secure or protected mode and then altered to run in unprotected mode when they are working properly. The Debugger enables users to debug the following external routines from a Windows, SLES11, or Mac OS client machine: User-defined functions (UDFs), including scalar, aggregate, table functions, and table operators User-defined methods (UDMs) External stored procedures that do not use Call-Level Interface Version 2 (CLIv2) The Debugger documentation uses the term UDFs to refer collectively to UDFs, UDMs, and external stored procedures. Capabilities Debugging external routines poses challenges in a Teradata Database environment. Due to the massively parallel nature of Teradata Database, external routines can run in multiple processes on multiple nodes. Standard debuggers, such as GDB, require users to attach to each UDF server process manually, in separate debugging sessions. The Teradata UDF Debugger (tdgdb) attaches automatically to every UDF server process associated with a SQL request and controls those UDFs from a single debugging session. Teradata Database users can debug a UDF within a SQL session if they have the necessary permissions, which are documented in the SQL Data Control Language publication, B Security is provided so that multiple users can concurrently debug their UDFs running on the same Teradata Database system. Users can only debug the UDFs running in Teradata Debugger for C/C++ UDF User Guide, Release

8 Chapter 1 Introduction their own SQL sessions. Nothing from other sessions is visible, and the debugger encrypts its message traffic to deter eavesdropping. The Debugger enables users to perform most of the operations that GDB provides, but some functionality is optimized for a parallel environment. For example, when a breakpoint is hit in one UDF thread, all UDF threads in that debugger session are stopped. Step commands are performed on the current thread, while the rest of the UDF threads remain suspended. When the Resume command is entered, all threads resume execution, with the exception of threads that have been explicitly held via the Hold command. Users can perform basic debug operations including: Setting and displaying breakpoints Displaying variables and modifying their values Watching variables or memory locations Stepping through code Suspending, resuming, and terminating a debug session Displaying the function call stack Displaying the source code In addition, the Debugger provides functionality for new GDB commands including: Listing the UDFs available for debugging Joining UDFs to a debugger session Aborting the current database request Recommended Test Environment Notice: Debugging on a production system is not recommended. The Debugger is intended for use only on development or test systems. Running it in a production environment raises the risk of debugging activities impacting critical workloads in a number of ways. Potential impacts on workloads include, but are not limited to, skewed performance measurement due to long-running UDFs, database locks held by UDFs being debugged, and additional memory consumption due to debugger processing. Debug Configuration Types Teradata Debugger for C/C++ UDF offers two debug configurations, each corresponding to a different method of running Teradata UDF Debugger (tdgdb) to debug UDFs. Method Remote: Run tdgdb on the Teradata Database system Requirements A Linux account has been created on Teradata Database. Note that root privileges are not required to run Teradata UDF Debugger (tdgdb). SSH port 22 is open on the Teradata Database system. 8 Teradata Debugger for C/C++ UDF User Guide, Release 15.10

9 Chapter 1 Introduction Method Local: Run tdgdb on the local machine Requirements Teradata UDF Debugger (tdgdb) is available on the local machine. Teradata UDF Debugger port 6276 is open on the Teradata Database system. You must select one of these two types when you configure a debugging session. Working with Online Help Eclipse online help includes extensive documentation for a variety of users and purposes. This user guide focuses on documenting what is different and specific to the Debugger. The contents of this user guide are available in Eclipse's online help by searching for "CUDB." In addition, you can view context-sensitive online Help by pressing the F1 key. Setting the Key Binding Pressing the F1 key should display context-sensitive help. If it does not, use the procedure below to set the key binding. 1 From the Window menu, select Preferences > General > Keys. 2 From the Command list, click Dynamic Help. 3 In the Binding box, enter F1. 4 Click OK. Teradata Debugger for C/C++ UDF User Guide, Release

10 Chapter 1 Introduction 10 Teradata Debugger for C/C++ UDF User Guide, Release 15.10

11 CHAPTER 2 Configuring a Debug Session Running a UDF Query in Debug Mode The UDF must be installed and the session debug feature enabled on Teradata Database prior to running the query. You also need appropriate privileges. If you are the creator of the UDF, you already have all the required privileges to debug the UDF. If you are debugging a UDF created by another user, you must have EXECUTE and DROP privileges on the UDF in order to be able to see its source code. 1 Type set session debug function FunctionName on;, where FunctionName is replaced by the actual name of the UDF you want to debug. For example, type: set session debug function udf_add on; 2 Type the query line as usual. For example, type: sel udf_add(1,2); After the two lines are submitted the query is suspended in debug hold mode, pending attachment to the Debugger. Adding the Debugger Port If you are using Teradata UDF Debugger (tdgdb) on your local machine to connect to the Debugger server on Teradata Database, port 6276 must be open on the Teradata Database server. 1 Add the following line to /etc/services on your local system: udfdbg 6276/tcp # PDE UDF Debugger Debug Configurations The Debug Configurations dialog box enables you to create, manage, and run debug configurations. The pane on the left side lists the debugging configuration types, and you can click each type to open up a list of the defined configurations of that type. There are two types of Teradata C/C++ UDF debugging configurations listed. You must first select a configuration type in order to create the configuration. Teradata Debugger for C/C++ UDF User Guide, Release

12 Chapter 2 Configuring a Debug Session Teradata Debugger for C/C++ UDF (Local), for debugging UDFs using local Teradata UDF Debugger (tdgdb) Teradata Debugger for C/C++ UDF (Remote), for debugging UDFs using an SSH connection The toolbar buttons at the top of the left pane enable you to create and manage debug configurations. Icon Description Creates a new debug configuration Duplicates the selected configuration Deletes the selected configuration When you create or duplicate a configuration, the configuration fields display in the right pane. You must enter a Name for each configuration you create. This name is displayed as the launch name in the Debug view. Use the Connect tab to configure connection settings. Field Connection New Edit Teradata Server Teradata Username Teradata Password TDGDB Debugger Project Change session/udf Description Lists SSH connection names. Select the connection to be used in the debug configuration, or click New to create a new connection. Enables creation of a new SSH connection. Clicking this button opens the New Connection dialog box. Designate a Host name and Connection name and click Finish to create a new connection. Enables you to edit the selected SSH connection. Clicking this button opens the Properties dialog box for the selected SSH connection. Modify the information in the fields as needed, and click Finish to save the changes. The target Teradata Database server for configurations that connect using Teradata UDF Debugger (tdgdb) on the local machine. The Teradata Database username. This username must be the same as the username that submits the query to call the UDF to debug. The password of the Teradata Database user. Enables you to enter or browse to the location on your local machine where Teradata UDF Debugger (tdgdb) is installed. Enables you to select the project that contains the UDF source code. Indicates whether you want to debug a new UDF session or name (selected) or debug the same one as the last time (deselected). Use the Source tab to designate one or more source lookup paths. Button Add Description Enables you to add a path, directory, path, folder, or project 12 Teradata Debugger for C/C++ UDF User Guide, Release 15.10

13 Chapter 2 Configuring a Debug Session Button Edit Remove Restores Default Description Modifies the content of the selected source container Removes the selected lookup path Restores the default lookup path Project and Source Code Management When debugging, the source code of the UDF must be accessible. The Debugger provides two options for managing the project and source code: Project-less debugging The Debugger creates a default project called "defaultudf" if you leave the Project box empty when creating a new configuration using the Debug Configurations view. You can then add the source code lookup path using the Source tab in the Debug Configurations view before running the debugger or at the initial debug stop. New project creation You can create a new C/C++ project in the C/C++ perspective of Eclipse, and either create the source file in the project or link the source folder to the project. Linking a Source Folder to a Project If you create an Eclipse project for use with the Debugger, you can link the folder with the source code to it. If you choose not do this, you can still specify a source lookup path when you designate a debug configuration. 1 In the Project Explorer view, right-click the new project name and select Properties. 2 In the left panel, under C/C++ General, click Paths and Symbols. 3 Click the Source Location tab, and then Link Folder. 4 Select the Link to folder in the file system check box. 5 Click Browse, navigate to the folder, and click OK to close the New Folder dialog box. 6 Click OK to close the Properties dialog box. Creating a Remote Debug Configuration Use the Debug Configurations dialog box to designate connection and source settings for your debug configurations. 1 In the Eclipse toolbar, click and select Debug Configurations. 2 In the left pane, select the Teradata Debugger for C/C++ UDF (Remote) launch configuration type. Teradata Debugger for C/C++ UDF User Guide, Release

14 Chapter 2 Configuring a Debug Session 3 Click. The launch configuration fields are displayed in the right panel. 4 Enter a Name for the debug configuration. The name is displayed as the launch name in the Debug view. 5 Configure the connection to Teradata Database by doing the following: a b c d e f Click New to open the New Connection dialog box. Enter the Host name or IP address of the target Teradata Database system. Enter the Connection name that is unique to the profile. [Optional] Enter a Description. [Optional] Select Verify host name to verify that a host of the given name or IP address exists. Click Finish. 6 Enter the Teradata Username for the target Teradata Database. This user name must be the same as the one that submits the query that calls the UDF to debug. 7 Enter the Teradata Password for the Teradata Database user. 8 Click the Save password check box if you want the password to be retained. By default, it is not selected. 9 For the Project field, do one of the following: Leave the field blank. When you launch the configuration, the Debugger automatically creates a project, assigning it the name defaultudf. Click Select to choose the project that contains the UDF source code. 10 For the Change session/udf check box, do one of the following: If you want to debug a new UDF session or name, select the check box. If you want to debug the same one as the last time, clear the check box. 11 Click Apply. Creating a Local Debug Configuration Use the Debug Configurations dialog box to designate connection and source settings for your debug configurations. 1 In the Eclipse toolbar, click and select Debug Configurations. 2 In the left pane, select the Teradata Debugger for C/C++ UDF (Local) launch configuration type. 3 Click. 14 Teradata Debugger for C/C++ UDF User Guide, Release 15.10

15 Chapter 2 Configuring a Debug Session The launch configuration fields are displayed in the right panel. 4 Enter a Name for the debug configuration. The name is displayed as the launch name in the Debug view. 5 Enter the Teradata Server name. 6 Enter the Teradata Username for the target Teradata Database. This user name must be the same as the one that submits the query that calls the UDF to debug. 7 Enter the Teradata Password for the Teradata Database user. 8 Click the Save password check box if you want the password to be retained. By default, it is not selected. 9 Enter the path of the location on your local machine where the TDGDB Debugger is installed or click Browse and navigate to it. 10 For the Project field, do one of the following: Leave the field blank. When you launch the configuration, the Debugger automatically creates a project, assigning it the name defaultudf. Click Select to choose the project that contains the UDF source code. 11 For the Change session/udf check box, do one of the following: To debug a new UDF session or name, select the check box. To debug the same UDF as the last time, clear the check box. 12 Click Apply. Starting a Debug Session Prerequisite: You must have executed the Set Session Debug Function command for the UDF and submitted the query that calls it. You must have created a debug configuration with all the required information. 1 In the Eclipse toolbar, click and select Debug Configurations. 2 Select the Connection from the list. 3 Click Debug. If this is the first time using a new SSH connection to a Teradata Database system in an Eclipse session, an Enter Password dialog box opens. Otherwise the UDF Sessions and Names dialog box opens. a For a new SSH connection, enter the User ID and system Password in the Enter Password dialog box and click OK. 4 In the UDF Sessions and Names dialog box, select the UDF to debug from the list. You may need to click to update the list. Teradata Debugger for C/C++ UDF User Guide, Release

16 Chapter 2 Configuring a Debug Session 5 [Optional] Select the Debug all UDFs in this session check box to debug any UDFs other than the selected one later in the same SQL session. 6 Click Debug. The session is at the initial debug stop, and the Debug view display all UDF threads in the current debug session. 16 Teradata Debugger for C/C++ UDF User Guide, Release 15.10

17 CHAPTER 3 Working with the Debugger Editor View The Editor view displays the source C or C++ code of the UDF so that you can set breakpoints and view the code as the Debugger navigates through it. It includes a syntax highlighting feature and integrates with the basic debug functions. The Editor view does not contain a toolbar itself, but you can use the following basic debug buttons in the main Eclipse toolbar and follow the code in the Editor as it is executed. Toolbar Button Action Description Step Into Step Over Step Return Executes the current line, including any routines, and proceeds to the next statement. Executes the current line, following execution inside a routine. Continues execution to the end of the current routine, then follow execution to the routine's caller. In addition the context menu displayed when you right-click enables you to perform the following Debugger activities. Context Menu Graphic Label Run to Line Move to Line Resume at Line Add Teradata Watchpoint Description Places a temporary breakpoint at the selected line and continues execution of the code until that breakpoint, unless another breakpoint is reached before that line. Skips over (does not execute) the code from the current line until the selected line, at which point execution halts. Skips over (does not execute) the code from the current line until the selected line, at which point execution continues. Adds a special breakpoint that stops the execution of the UDF whenever the watched address is written to, read from, or executed. The Editor view is associated with the Outline view that shows the structure of the active C or C++ file. The Outline view is updated when you edit the file. Teradata Debugger for C/C++ UDF User Guide, Release

18 Chapter 3 Working with the Debugger Displaying Source Code You can open the source code for the UDF before beginning the debug session so that the code is displayed in the Editor view and you can set breakpoints. 1 Click File > Open File. 2 Navigate to and select the UDF source code file. 3 Click Open. The source file is displayed in the Editor view. Setting a Line Breakpoint You can set a line breakpoint on an executable line of the UDF so that the execution suspends before that line of code executes. 1 Open the source file to display it in the Editor view. 2 Right-click in the vertical blue area to the left of the line number at which you want to set a breakpoint, and select one of the following: Option Add Breakpoint Description Opens a dialog box that enables you to designate breakpoint properties and sets the breakpoint. Toggle Breakpoint Sets the breakpoint using default properties. Click again to remove the breakpoint. A line breakpoint symbol appears to the left of the line number to indicate that a breakpoint is set, and the breakpoint is listed in the Breakpoints view. Setting a Function Breakpoint You can set a breakpoint at the beginning of a function. 1 Open the source file to display it in the Editor view. 2 In the associated Outline view, right-click on the function where you want to set a breakpoint, and select Toggle Breakpoint. A function breakpoint symbol appears to the left of the line number to indicate that a breakpoint is set, and the breakpoint is listed in the Breakpoints view. Setting a Conditional Breakpoint You can set a conditional breakpoint so that the value of an expression is evaluated when the breakpoint is reached and execution stopped if the condition is true. 1 Open the source file to display it in the Editor view. 18 Teradata Debugger for C/C++ UDF User Guide, Release 15.10

19 Chapter 3 Working with the Debugger 2 Do one of the following: Option Create a new conditional breakpoint Add a condition to an existing breakpoint Description a. Right-click in the vertical blue area to the left of the line number and select Add Breakpoint. b. Enter the expression in the Condition box. c. Click OK. a. Right-click on the breakpoint icon and select Breakpoint Properties. b. In the left pane, select Common. c. Enter the expression in the Condition box. d. Click OK. A conditional breakpoint symbol appears to the left of the line number to indicate that a conditional breakpoint is set, and the breakpoint is listed in the Breakpoints view. Debug View The Debug view shows the target debugging information in a tree hierarchy. As the UDF code is executed, each virtual processor (vproc) and process being used is displayed, with their associated threads and tasks displayed underneath. When a breakpoint is hit, all UDF threads in the debug session will be stopped. The thread that reaches the breakpoint first is identified as the primary thread, and is displayed as the Current Thread with the notation Suspended: Breakpoint. Any other threads that would have reach a breakpoint when being stopped are labeled as Secondary Breakpoint threads, and are highlighted in light green. The Debug view has a toolbar with buttons for three special Debugger functions. Toolbar Button Action Description Locate Current Thread Abort Query Add UDF Locates and selects the current thread in the view. Due an Eclipse CDT limitation, this action might not work when a stack frame entry was selected beforehand. Aborts the current database request. Adds an additional UDF to the current session while the debug session is suspended or in debug stop. In addition you can Hold and Unhold specific threads from running when execution is resumed by selecting those commands from the context menu that opens when you rightclick within the Debug view. Teradata Debugger for C/C++ UDF User Guide, Release

20 Chapter 3 Working with the Debugger Basic Debug View Functions The Debug view enables you to perform many common debug functions. You can access these functions using the toolbar at the top of the Eclipse interface, by right-clicking open a context menu, or by displaying the Debug Toolbar from the View menu of the Debug view. Resume Suspend Terminate Step Into Step Over Step Return Continues the execution of all UDF processes/threads except those that were held. Halts execution of all UDF processes/threads. Ends the UDF debug session. Executes the current line of the active thread, including any routines, and proceeds to the next statement. All other threads remain suspended. Executes the current line, following execution inside a routine. Continues execution to the end of the current routine for the active thread, then follows execution to the routine's caller. All other threads remain suspended. Teradata Debug View Functions In addition to the basic debug functions, the Debug view enables you to perform some other functions that are very helpful in debugging UDFs running in a Teradata Database environment. You can right-click within the view to select these actions from the context menu. Abort Query Add UDF Hold Unhold Aborts the current database request while the debug session is suspended or in debug stop. Adds additional UDFs to the current session while the debug session is suspended or in debug stop. Holds the selected thread so that it does not execute when execution is resumed. Releases the selected thread so that it executes when execution is resumed. 20 Teradata Debugger for C/C++ UDF User Guide, Release 15.10

21 Chapter 3 Working with the Debugger Locate the Current Thread Aborting a Query Locates and selects the current thread in the view. Due an Eclipse CDT limitation, this action might not work when a stack frame entry was selected beforehand. You can abort the current database request while the debug session is suspended or in debug stop. After this function is executed, the debug session remains in debug stop. If more than one database session is attached to the debugging session, the Abort Query command ends debugging of any active SQL requests from all joined sessions, but only aborts the request for the current UDF. Database sessions can then restart queries to continue debugging their UDFs. 1 In the Debug view toolbar, click. Adding a UDF You can add additional UDFs to the current session while the debug session is suspended or in debug stop. 1 In the Debug view toolbar, click. 2 In the UDF Sessions and Names dialog box, select the UDF to debug from the list and click Debug. 3 [Optional] Add breakpoints for the new UDF. 4 Click. The Debug view displays the threads of all UDFs that are being debugged. Holding and Unholding UDF Threads You can use the Hold command to control which UDF threads run when Resume commands are submitted. Threads that are held do not execute, but other threads continue to do so. You can use the Unhold command to release the hold so that the thread will run again when execution is resumed. You can use Hold and Unhold together. For example, you could use the Hold All command and then Unhold only the thread you want to execute. Note: The Hold command only applies to use of the Resume command. The Step commands implicitly hold all threads when it is executed. 1 In the Debug view, right-click and select any of the following. Option Hold Hold All Unhold Unhold All Description Holds the selected thread Holds all threads Releases the selected thread Releases all threads Teradata Debugger for C/C++ UDF User Guide, Release

22 Chapter 3 Working with the Debugger Locating the Current Thread You can easily locate the current thread if a configuration, process, or thread line was previously selected. This functionality does not work if a stack frame entry was previously selected. 1 In the Debug view toolbar, click. The current thread is highlighted. Secondary Breakpoints A UDF that accesses data on multiple AMPs may have several threads running concurrently (one thread per AMP). When execution is resumed, as soon as one thread hits a breakpoint, all threads in the debug session are stopped. Any other threads that would have hit a breakpoint had execution continued are highlighted with a light green background and marked Secondary Breakpoint. You can select any thread to view its contents and perform debug actions on it. In the Debug view shown below, all threads are suspended because Thread 3, marked as the Current Thread, has already encountered its breakpoint at line 22. When execution is resumed, Thread 1, marked as Secondary Breakpoint, will continue running, executing lines 22 and later. Teradata Watchpoint View A Teradata watchpoint is a special breakpoint that stops the execution of the UDF whenever the watched address is written to, read from, or executed. The Teradata Watchpoint view displays information about the current watchpoints for the selected thread. A thread can have up to four watched addresses. The watched locations directly reference the Intel debug x8664 registers. 22 Teradata Debugger for C/C++ UDF User Guide, Release 15.10

23 Chapter 3 Working with the Debugger Each watchpoint is bound to a certain thread. When the thread exits, the watchpoint expires and is automatically removed from the Teradata Watchpoint view. When the watchpoint is set on a local variable, the Debugger will stop the execution twice: first when the variable changes value, and again when the watchpoint goes out of scope. When the watchpoint goes out of scope, it is no longer in effect. You can set the watchpoint again as needed. You can add a watchpoint, remove a watchpoint, and remove all watchpoints from this view. Opening the Teradata Watchpoint View 1 From the Window menu, select Show View > Other. 2 Expand Teradata Debugger for C/C++ UDF and select Teradata Watchpoint. Adding a Watchpoint 1 Do one of the following to open the Add Teradata Watchpoint dialog box. Option In Variables view Description Right-click on the variable you want to watch and select Add Teradata Watchpoint. In Teradata Watchpoint view Click. In Editor view Select the variable or expression, right-click and select Add Teradata Watchpoint. 2 Under Expression to watch, enter or select the expression to be watched. 3 Select one of the following: Option Write Read Execute Description Halt execution when the specified address is written to. Halt execution when the specified address is read from. Halt execution when the specified address is executed. 4 Click OK. The watchpoints are displayed in the Teradata Watchpoint view. When execution is resumed and a watchpoint is hit, a popup message will appear at the bottom right corner of the screen to alert the user, and the Debug view will show the thread that just hit the watchpoint. Removing a Watchpoint 1 In the Teradata Watchpoint view, click the watchpoint you want to remove. Teradata Debugger for C/C++ UDF User Guide, Release

24 Chapter 3 Working with the Debugger 2 Click. The watchpoint information is removed from the list. Teradata Map View The Teradata Map view shows the memory usage map. For each segment in the address space of the process being debugged, it shows its base address, size, access permissions, and the name of the file if this memory is a mapped file. Opening the Teradata Map View 1 From the Window menu, select Show View > Other. 2 Expand Teradata Debugger for C/C++ UDF and select Teradata Map. Console View The Console view enables you to select from and display a number of different consoles. Most important for the Debugger, it enables you to view traces in order to monitor what is happening on the backend, in Teradata UDF Debugger (tdgdb). Monitoring the Backend You can view Teradata UDF Debugger (tdgdb) traces in order to monitor any detailed communication messages and the tdgdb backend status. 1 In the toolbar of the Console view, click. 2 Select the gdb traces console for your launch configuration. 24 Teradata Debugger for C/C++ UDF User Guide, Release 15.10