Volume 14 April 2010 IBM DEBUG TOOL NEWSLETTER Currently Available PTFs SERVICE INFORMATION Release Debug Tool for z/os V10.1 Debug Tool for z/os V9.1 Debug Tool for z/os V8.1 English Component Japanese Component Korean Component UK54741 UK54639 UK54640 UK55067 UK55068 UK55069 English DTUAF UK55903 UK55904 UK55905 UK55906 Japanese DTUAF To determine your current Debug Tool service level, issue the following command using the Mainframe Interface (MFI): CALL %VER; You should get the following output showing the release and PTF: Version 10.1 IBM Debug Tool Version 10 Release 1 Mod 0 02/26/2010 11:51:00 AM Level: V10R1 PM08594 5655-V50: Copyright IBM Corp. 1992, 2009 Version 9.1 IBM Debug Tool Version 9 Release 1 Mod 0 03/10/2010 04:29:00 PM Level: V9R1 PM05431 5655-U27: Copyright IBM Corp. 1992, 2008 Version 8.1 IBM Debug Tool Version 8 Release 1 Mod 0 04/07/2010 08:30:00 AM Level: V8R1 PK99776 5655-S17 and 5655-S16: Copyright IBM Corp. 1992, 2007 Tips and Hints How to Start Debug Tool by Specifying a CEEOPTS DD Statement How to Use a CEEOPTS DD to Start the Debugger for a Batch Job How to Use a CEEOPTS DD to Start the Debugger for an IMS Message Processing Program running under BTS in TSO The LE TEST Option and Sub-options 1
How to Start Debug Tool by Specifying a CEEOPTS DD Statement There are several methods that can be used to start Debug Tool when a program runs. Regardless of the method selected, the programmer takes an action that causes the debugger to start when the target program or application is executed. This action is called setting a debugging trigger. For programs that run in batch and for IMS MPP programs that are executed in BTS under TSO, the two most common methods used to set a debugging trigger are the following: Specify a debugging profile in the User exit data set panels in TSO Specify a CEEOPTS DD statement Technically, both of these methods trigger the debugger by passing a TEST run-time option to Language Environment, which causes the debugger to trigger. Of the two, the CEEOPTS method is generally the easiest. This document describes how to start Debug Tool by specifying a CEEOPTS DD statement. However, the User exit data set method continues to work and can still be used. Using one method or the other is a matter of personal preference. 2
How to Use a CEEOPTS DD to Start the Debugger for a Batch Job This method can be used to start Debug Tool with a batch application running in batch. It can generally be used for any LE application (for example programs written in COBOL). It works for IMS programs (either DLI or BMP), non-ims programs, and programs that access DB2 databases. Do not follow these instructions when debugging programs that run in other environments, such as in BTS, in TSO, or in an IMS Message Processing Region. Instructions for starting the debugger: 1. Start a Debug Tool TIM terminal session and log on to it. Open a dedicated TIM terminal session for Debug Tool Log on to Debug Tool with your User ID and password Enter click 2. Leave the TIM session ready and open TSO in another terminal session. 3. In the ISPF editor, open the JCL to be used to run the batch job. Insert a CEEOPTS DD statement into the step to be debugged (see the next screen shot). The JCL looks like this: //CEEOPTS DD * TEST(,,,VTAM%user-id:) Notes: 3
a. user-id is the user id that was used to log on to the TIM terminal. It is typically your user id. Debug Tool uses this id to identify the terminal. b. Be very careful about the syntax! The three commas, VTAM% and : are all required exactly as shown. 4. If you had previously added an hlq.dtxload data set in STEPLIB or JOBLIB, remove it. You may have done this to start Debug Tool using the User exit data set method. The DTXLOAD library can prevent the CEEOPTS DD from working. 5. Submit the job. Submit the job Enter 6. When the step that has the CEEOPTS DD runs, the debugger triggers and displays on the Debug Tool TIM terminal. The highest level LE application program is the one displayed. When the step runs, the TEST option is processed, and Debug Tool is displayed on the Debug Tool terminal Select the Debug Tool terminal click 4
When you no longer want the batch job to trigger the debugger, update the JCL: 1. Delete or comment the CEEOPTS DD and TEST option 2. Change the TEST option to NOTEST, for example: //CEEOPTS DD * NOTEST(,,,VTAM%user-id:) 5
How to Use a CEEOPTS DD to Start the Debugger for an IMS Message Processing Program Running under BTS in TSO This method can be used to start Debug Tool when running an IMS Message Processing Program (MPP) under BTS in TSO. It can generally be used for any LE program; for example, programs written in COBOL. It works when running in either DLI or BMP access mode. Do not follow these instructions when debugging programs that run in other environments such as batch programs, or MPPs running in an IMS Message Processing Region. Instructions for Starting the Debugger: Note: You will not need a Debug Tool TIM terminal when using this method. 1. Navigate to the Debug Tool Setup File utility in TSO and open the setup file that you use to run BTS. 2. Insert a new DD statement. A new DD can be inserted with an I line command. 3. A new DD line is added. (The line where ** Select Detail DD Information ** is displayed) 4. On the new DD line, specify CEEOPTS as the DD name and SYSIN in the DD information field. 6
5. Specify an E line command to edit the CEEOPTS input data. 6. An edit session is displayed. Type TEST starting in the first position of the first data line. The TEST option with no sub-options specifies all of the default sub-options. You can optionally code the full TEST option and explicitly code the sub-options; for example, TEST(,,,MFI%:) If you do this be very careful about the syntax! The three commas, MFI% and : are all required exactly as shown. 7. Then press PF3 to exit and save the TEST option. 8. If you previously added an hlq.dtxload data set in STEPLIB or JOBLIB, remove it. You may have done this to start Debug Tool using the User exit data set method. The DTXLOAD library can prevent the CEEOPTS DD from working. 7
9. Run the setup file. 10. BTS displays; you can enter BTS commands as needed to run the programs. 11. When the first application program runs, the debugger is displayed on your TSO terminal. CEEOOPTS causes the debugger to trigger when a main program starts while you are in BTS. When you no longer want to trigger the debugger, update the setup file: 1. Delete or comment the CEEOPTS DD 2. Edit (using an E line command) the CEEOPTS DD and change the TEST option to NOTEST. 8
The LE TEST Option and Sub-options The LE TEST option has five sub-options, separated by commas and a colon. Refer to the Debug Tool Reference and Messages Manual for a detailed description of all sub-options. TEST( test-level, command-file, prompt, connection : preferences-file ) Test-level is not typically coded. It is used to control when the debugger should automatically stop as a program runs. (default = all conditions and abends) Command-file can be used to specify the DDname or file name of a script file containing debugger commands that runs automatically. (default = no command file) Prompt is not typically coded. (default = display the debugger when triggered) Connection controls where the debugger displays: VTAM%user-id: - Connect to the TIM terminal where user-id logged on MFI%terminal-id: - Connect to the non-tim terminal named terminal-id. If terminal-id is not coded, then connect to the TSO terminal (if the program is running in TSO) TCP%workstation_tcpip_address%port_id: - Connect to GUI debugging software such as Rational Developer for system z Preferences-file can be used to specify the DDname or file name of a script file containing debugger commands that runs automatically. The preferences file runs before the command file, if specified. Code an asterisk (*) to indicate that no preferences file is to be used. (default = INSPPREF) 9
Contributing Authors: Doug Stout and Elizabeth Spangler Editor: Elizabeth Spangler Copyright IBM Corporation 2010 IBM Corporation Department DQZA Route 100 Box 100 Somers, NY USA, 06877 Printed in the (United States of America) 05-04 All Rights Reserved References in this publication to IBM products or services do not imply that IBM intends to make them available in all countries in which IBM operates. All Statements regarding IBM s future direction and intent are subject to change or withdrawal without notice, and represent goals and objectives only. IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not grant you any license to these patents. You can send license inquiries, in writing, to: IBM Director of Licensing IBM Corporation North Castle Drive Armonk, NY 10504-1785 U.S.A. The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you. This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice. Any performance data contained in this document were determined in various controlled laboratory environments and are for reference purposes only. Customers should not adapt these performance numbers to their own environments as system performance standards. The results that may be obtained in other operating environments may vary significantly. Users of this document should verify the applicable data for their specific environment. 10