Tool for analyzing and debugging EXEC applications Kent Fiala SAS Institute http://www.sas.com/ TRACEXEC is a tool for analyzing and debugging EXEC applications. It can be used to reveal the flow of logic in a multi-exec application, to tabulate CPU usage per exec or per line of REXX, and to set debugging breakpoints in REXX execs. See TRACEXEC HELPCMS or TRACEXEC HTML for more details. Authorship and distribution policy ================================== TRACEXEC was written by Kent Fiala of SAS Institute Inc., Cary NC 27513 USA. It is provided as-is without any warranty expressed or implied and it is not supported by SAS Technical Support. Permission is granted to use, copy, and distribute this program in any form as long as (1) this notice of authorship and distribution policy remain intact, (2) distribution is made without charge above and beyond any reasonable fee to cover costs in making and delivering the copy, and if accompanying another product does not contribute to the selling price of the product in any substantial way, and (3) no additional restrictions are imposed, either as to distribution or as to use. Files: (those marked "end user" should be installed where they are accessible to end users) TRACEXEC README This file TRACEXEC ASSEMBLE Source code TRACEXEC MODULE Functional code (end user) TRACEXEC HELPCMS Formatted help file (end user doc) TRACEXEC -HLPCMS Unformatted help file TRACEXEC HTML Help file in HTML form (end user doc) XDEBUG HELPTRAC Formatted help file (end user doc) XDEBUG -HLPTRAC Unformatted help file MAKETREX EXEC EXEC to assemble and build module TRACEXEC AUXVM AUX file TRACEXEC UPDT0205 Source update TRACEXEC UPDT0204 Source update TRACEXEC UPDT0203 Source update TRACEXEC UPDT0202 Source update TRACEXEC UPDT0201 Source update TREXPROF AUXVM AUX file TREXPROF XEDIT XDEBUG profile (end user) TREXPROF UPDT0001 Source update TREXPROF UPDT0002 Source update TREXPROF UPDT0003 Source update TREXPROF UPDT0004 Source update TREXPROF UPDT0005 Source update TREXPROF UPDT0006 Source update TREXPROF UPDT0007 Source update TREXPROF UPDT0008 Source update TREXPROF $XEDIT Base file ZSTATS XEDIT Profiling tool (end user) Assembling TRACEXEC requires CMS Release 6 or later. The module should run under CMS 5.5 or later. MAKETREX is the recommended procedure for building the TRACEXEC MODULE. This is TRACEXEC Version 2.05. Changes for TRACEXEC 2.01 ------------------------- New features: * XDEBUG mode provides a fullscreen debugging environment. You can view the source of the exec that you are debugging while you are debugging it, and can easily set, display, or clear breakpoints in a visual manner. For example, you can toggle a breakpoint just by moving the cursor to a line and pressing enter. * NODEBUG option Enhancements: * As long as there is no ambiguity, you can specify a fileid in the traditional "fn ft fm" format. The dot-delimited format ("fn.ft.fm") is required only if the ft could be confused with a TRACEXEC keyword. Bug fixes: * The display of exec arguments is properly formatted even if the exec is called without an EPLIST. * Breakpoints remain in effect after trace off is entered even if the exectrace flag is on. * FBLOCK initialized correctly even if extension block length was 0. Changes for TRACEXEC 2.02 ------------------------- * Fixes for bugs in 2.01. Mainly, I forgot about the need to preserve the console stack in XDEBUG mode. Changes for TRACEXEC 2.03 ------------------------- * New features/enhancements: 1 Option defaults can now be set via the DEFAULTS option. The command format is TRACEXEC DEFAULTS default-options The options set via DEFAULTS are processed in front of options specified on the command line for the initial TRACEXEC command only, not for subsequent commands. For example TRACEXEC DEFAULTS QUIET NOHT would make QUIET instead of VERBOSE, and NOHT intead of HT the new defaults. All remaining arguments following the keyword DEFAULTS are both processed as normal options and also set as defaults. Options specified before the keyword DEFAULTS are not set as defaults. Defaults are saved in LASTING GLOBALV. 2 New option HT | NOHT specifies whether TRACEXEC messages in verbose mode are affected by the CMSTYPE HT setting. The default HT means that TRACEXEC messages are suppressed by CMSTYPE HT (unless they are being routed to the TRACEXEC WINDOW, which isn't affected by CMSTYPE HT anyway). NOHT means that TRACEXEC messages will be displayed even if CMSTYPE HT is in effect. 3 New option PROFILE ZSTATS is nearly the same as PROFILE STATS, but reports on every line including those with an execution count of zero. This makes it easier to line up the report with the exec source. 4 PROFILE STATS and PROFILE ZSTATS now report CPU time for initialization and termination, so that the sum of all times reported matches the total CPU time for the exec. Initialization includes time from the invocation of the EXEC command until the first clause is interpreted. Termination time includes time from the execution of the REXX termination exit until the EXEC command terminates. 5 QUERY option displays all options currently in effect. QUERY VERsion Identical to the VERSION option. QUERY DEFaults Displays the options set by TRACEXEC DEFAULTS. QUERY OPTions Displays global TRACEXEC options, e.g. QUIET, HT, etc. QUERY TARget Displays the current debug target. QUERY FLAgged Displays the current debug target if any, and all execs that have been flagged for special processing by options such as EXPOSE, ?R, DEBUG, etc. For execs flagged by DEBUG or XDEBUG, breakpoints are also listed. QUERY ALL Displays output of all the above QUERY options, in the sequence listed above, except that the response from QUERY DEFAULTS or QUERY TARGET is not displayed if it is negative. This is the default if QUERY is the last option. QUERY DEBug Displays the debug target and a subset of the information that QUERY FLAGGED displays, including only the information on execs flagged for DEBUG or XDEBUG. 6 New option INDENT n causes TRACEXEC messages to be indented n spaces for each level of the traced exec's logical depth of nesting. This makes it easier to follow the structure of a nested application. The valid range for n is 0-254. The default is INDENT 0. * Bug fixes: 1 Else clauses are now correctly identified as executed or skipped when using debug mode or profiling. The paragraph describing special considerations for else clauses has been deleted from the help file. 2 Obtain correct filename and filetype when using debug mode or profiling an exec that was EXECLOAD'ed under a different name * Maintenance enhancements: 1 No longer necessary to specify the SYSTEM option when GENMOD'ing Changes for TRACEXEC 2.04 ------------------------- 1. ZSTATS XEDIT is a tool for use with profiling. After running an exec for which you have turned on TRACEXEC profiling, XEDIT the exec (either the original exec or a copy of it) and enter ZSTATS on the Xedit command line. ZSTATS takes a fileid as an argument but it defaults to that of the file you are editing, so you only need to specify it if you are editing a copy that has a different name. By default the statistics are written to a new file, but the OVERLAY option allows you to overlay the statistics in the same file. For example, try shift right 28 * zstats ( overlay 1 The purpose of ZSTATS XEDIT is to simplify the process of matching profiling statistics with the actual source lines. 2. Parsing enhancement: TRACEXEC supports a simplified syntax when you specify multiple instances of certain options on the command line. For example, without this simplification you can combine the two commands TRACEXEC XDEBUG MIRACLE EXEC TRACEXEC XDEBUG FOO EXEC as this single command: TRACEXEC XDEBUG MIRACLE EXEC XDEBUG FOO EXEC The simplification allows you to omit the second specification of the XDEBUG keyword: TRACEXEC XDEBUG MIRACLE EXEC FOO EXEC When TRACEXEC encounters an option keyword that takes a file specification as a parameter, specifically any of TRACE, ?R, NOTRACE, RESET, QAT, VAT, EXPOSE, CONCEAL, DEBUG, XDEBUG, NODEBUG, NOXDEBUG, or LISTBREAK all subsequent tokens are assumed to be parts of file specifications for the same option until another TRACEXEC keyword is found. In the example TRACEXEC XDEBUG BOGUS EXEC FOO EXEC JUSTIFY XEDIT QAT PROFILE XEDIT all the tokens following "XDEBUG" and preceding "QAT" are not TRACEXEC keywords, so this command is equivalent to TRACEXEC XDEBUG BOGUS EXEC TRACEXEC XDEBUG FOO EXEC TRACEXEC XDEBUG JUSTIFY XEDIT TRACEXEC QAT PROFILE XEDIT Note that you can not combine TRACEXEC XD BOGUS and TRACEXEC XD FOO as TRACEXEC XD BOGUS FOO because "BOGUS FOO" would be taken as filename and filetype of a single exec. You could combine them as TRACEXEC BOGUS EXEC FOO. A non-keyword token that follows a filename filetype sequence will be interpreted as a filemode if it is one or two characters (ANY one or two characters). If longer it will be interpreted as the next filename. If you have an exec whose name matches a TRACEXEC keyword, you can not exploit this simplification with it unless you use the "dotted" style of file specification. For example, if you have a QAT EXEC you could use TRACEXEC XDEBUG FOO EXEC XDEBUG QAT EXEC or TRACEXEC XDEBUG FOO EXEC QAT.EXEC but not TRACEXEC XDEBUG FOO EXEC QAT EXEC Changes for TRACEXEC 2.05 ------------------------- The only change is a fix for a bug that could lead to abends when breakpoints or profiling are enabled.