The chapter describes how you use the Generalized Trace Facility to obtain an execution trace of an Assembler program.
The Assembler Generalized Trace Facility (GTF) is a debugging tool designed to help speed up the process of isolating the location and cause of a problem in an Assembler program. You use the GTF tool to create a trace file showing the operations performed by the program. You do not have to compile the program for debugging. You can request different levels of detail. For example, you might run a trace requesting program level information and then run a further trace on a specific section by specifying the level of detail and the start and end points for the trace.
To turn on the Generalized Trace Facility, set the environment variable GTFFILE to the absolute path and file name of the trace file. You set this environment variable in the mfuser\config\MF370ctl.cfg configuration file.
You can specify the following GTF options after the GTFFILE environment variable:
| GTFIMIN | The instruction count at which to start the trace (default 00000000) | ||||||||||||||||||
| GTFIMAX | The instruction count at which to end the trace (default FFFFFFFF) | ||||||||||||||||||
| GTFAMIN | The instruction address at which to start the trace (default 00000000) | ||||||||||||||||||
| GTFAMAX | The instruction address at which to end the trace (default FFFFFFFF) | ||||||||||||||||||
| GTFOPT | The level of detail. You can set this
environment variable to one or more of the following three-character
codes separated by commas to indicate the level of detail you want:
The default value is BAL, PGM, FOC |
The size of a trace file depends on the options that you specify. It can be very large. For this reason we recommend that you always begin by running a trace with the default options to find out the optimum starting point for a detailed trace. When you run a detailed trace, using options such as FIO, INS or ALL, specify the start and end points using the GTFIMIN and GTFIMAX or the GTFAMIN and GTFAMAX options.
You can also specify the REG option with any other option if you want the contents of the 16 general-purpose registers at each trace point. This increases the size of the trace file by a factor of 3 and makes it a little more difficult to read, so only use this option if you really need it. The contents of the registers are shown as they were just before the trace operation; hence the REG option is most useful with the following options:
Regardless of the trace options you have specified, whenever a program interruption occurs, the trace file contains extra lines for the instruction causing the interruption. These lines show the program status word (PSW), which contains the interruption code in the low-order byte of the first word, and the registers.
You can view or print the GTF trace file using any ASCII-compatible editor or word processor. The file begins with the GTF options used to generate the file and the date and time the trace started. The last line of the file shows the date and time the trace ended. If this line is not present, the trace is probably incomplete because it was not closed properly. This can happen if you are running an interactive debugging session using the Assembler debugger with the Generalized Trace Facility turned on, and an unrecoverable error occurs. To ensure that the GTF trace file is complete, you must allow the debugging session to end without being forced: press S(tep) or G(o) to record the program exception on the trace file and then stop the debugging session.
In between the information at the beginning of the file and the last line are individual trace records. Each of these includes the following items of information:
| INS | The hexadecimal machine instruction, which can be 2, 4, or 6 bytes in length |
| PGM | The program name and entry for LOAD, DELETE, or LINK |
| FOC and FIO | The DCB, ACB, or DTF control block address |
| MEM | Length and address of memory allocated or deallocated |
This section describes various types of trace you can obtain.
Use the default trace option GTFOPT=PGM,BAL,FOC, which traces LOAD, DELETE, LINK, BALR, BASR, OPEN, and CLOSE operations, to get an overview of what an application is doing and to identify possible starting and ending points for more detailed traces if required.
Here is the trace file for a default trace of an IMS COBOL and Assembler application:
GTF option GTFFILE =D:\MFUSER\CONFIG\GTF.LOG GTF option GTFOPT =BAL,FOC,PGM GTF option GTFIMIN =00000000 GTF option GTFIMAX =FFFFFFFF GTF option GTFAMIN =00000000 GTF option GTFAMAX =FFFFFFFF GTF trace file DATE=000114 TIME=08495898 INS-CTR INS-ADDR INS-OP 00000043 81000188 BALR 05EF 00000044 81005998 BALR 05F0 00000047 810059A2 LINK NAME=AIBTDLI ENTRY=(COBOL) 00000051 810001E6 LOAD NAME=LDDECTBL ENTRY=810059D8 000006DA 8100033A BALR 05EF 00000704 81005998 BALR 05F0 00000707 810059A2 LINK NAME=AIBTDLI ENTRY=(COBOL) 00000762 81000E10 LOAD NAME=CG#CTL ENTRY=80012CF0 00000988 810059B0 BALR 05F0 0000098B 810059BA LINK NAME=ASMTDLI ENTRY=(COBOL) 00001051 8100033A BALR 05EF 0000107B 81005998 BALR 05F0 0000107E 810059A2 LINK NAME=AIBTDLI ENTRY=(COBOL) 000012F7 810059B0 BALR 05F0 000012FA 810059BA LINK NAME=ASMTDLI ENTRY=(COBOL) 00001360 8100033A BALR 05EF 0000139C 81005998 BALR 05F0 0000139F 810059A2 LINK NAME=AIBTDLI ENTRY=(COBOL) 00001618 810059B0 BALR 05F0 0000161B 810059BA LINK NAME=ASMTDLI ENTRY=(COBOL) 00001CDC 8100033A BALR 05EF 00001D06 81005998 BALR 05F0 00001D09 810059A2 LINK NAME=AIBTDLI ENTRY=(COBOL) 00001F82 810059B0 BALR 05F0 00001F85 810059BA LINK NAME=ASMTDLI ENTRY=(COBOL) 00001F92 810003EA DELETE NAME=LDDECTBL ENTRY=00000000 00001FED 81007628 BALR 05EF 00001FEE 8100CE38 BALR 05F0 00001FF1 8100CE42 LINK NAME=AIBTDLI ENTRY=(COBOL) 00001FFB 81007686 LOAD NAME=LDDECTBL ENTRY=80011228 00002684 810077DA BALR 05EF 000026AE 8100CE38 BALR 05F0 000026B1 8100CE42 LINK NAME=AIBTDLI ENTRY=(COBOL) 0000270C 810082B0 LOAD NAME=CG#CTL ENTRY=8100CE78 00002932 8100CE50 BALR 05F0 00002935 8100CE5A LINK NAME=ASMTDLI ENTRY=(COBOL) 00002FFB 810077DA BALR 05EF ......................................... ......................................... 0000B04A 81022160 BALR 05F0 0000B04D 8102216A LINK NAME=ASMTDLI ENTRY=(COBOL) 0000B0AA 8101CAEA BALR 05EF 0000B0EF 81022148 BALR 05F0 0000B0F2 81022152 LINK NAME=AIBTDLI ENTRY=(COBOL) 0000B114 81022160 BALR 05F0 0000B117 8102216A LINK NAME=ASMTDLI ENTRY=(COBOL) 0000B174 8101CAEA BALR 05EF 0000B1B0 81022148 BALR 05F0 0000B1B3 81022152 LINK NAME=AIBTDLI ENTRY=(COBOL) 0000B4A4 81022160 BALR 05F0 0000B4A7 8102216A LINK NAME=ASMTDLI ENTRY=(COBOL) 0000B501 8101CAEA BALR 05EF 0000B519 81022160 BALR 05F0 0000B51C 8102216A LINK NAME=ASMTDLI ENTRY=(COBOL) 0000BBE2 8101CAEA BALR 05EF 0000BC0C 81022148 BALR 05F0 0000BC0F 81022152 LINK NAME=AIBTDLI ENTRY=(COBOL) 0000BE8D 81022160 BALR 05F0 0000BE90 8102216A LINK NAME=ASMTDLI ENTRY=(COBOL) 0000BEED 8101CAEA BALR 05EF 0000BF32 81022148 BALR 05F0 0000BF35 81022152 LINK NAME=AIBTDLI ENTRY=(COBOL) 0000BF51 81022160 BALR 05F0 0000BF54 8102216A LINK NAME=ASMTDLI ENTRY=(COBOL) 0000BFB1 8101CAEA BALR 05EF 0000BFED 81022148 BALR 05F0 0000BFF0 81022152 LINK NAME=AIBTDLI ENTRY=(COBOL) 0000C2E1 81022160 BALR 05F0 0000C2E4 8102216A LINK NAME=ASMTDLI ENTRY=(COBOL) 0000C33E 8101CAEA BALR 05EF 0000C356 81022160 BALR 05F0 0000C359 8102216A LINK NAME=ASMTDLI ENTRY=(COBOL) 0000C3BF 8101CAEA BALR 05EF 0000C3FB 81022148 BALR 05F0 0000C3FE 81022152 LINK NAME=AIBTDLI ENTRY=(COBOL) 0000C67C 81022160 BALR 05F0 0000C67F 8102216A LINK NAME=ASMTDLI ENTRY=(COBOL) 0000CD40 8101CAEA BALR 05EF 0000CD6A 81022148 BALR 05F0 0000CD6D 81022152 LINK NAME=AIBTDLI ENTRY=(COBOL) 0000CFEB 81022160 BALR 05F0 0000CFEE 8102216A LINK NAME=ASMTDLI ENTRY=(COBOL) 0000CFFB 8101CB9A DELETE NAME=LDDECTBL ENTRY=00000000 GTF trace file DATE=000114 TIME=08514748
Use the GTFOPT=ALL option to obtain a detailed trace.
Here is a detailed trace of the last section of code starting with BALR at instruction count CFEB in the default trace example in section program level trace. Options GTFOPT=ALL and GTFIMIN=0000CFEB were used to obtain this trace:
GTF option GTFFILE =D:\MFUSER\CONFIG\GTF.LOG GTF option GTFOPT =ALL GTF option GTFIMIN =0000CFEB GTF option GTFIMAX =FFFFFFFF GTF option GTFAMIN =00000000 GTF option GTFAMAX =FFFFFFFF GTF trace file DATE=000114 TIME=09370586 INS-CTR INS-ADDR INS-OP 0000CFEB 81022160 BALR 05F0 0000CFEC 81022162 ICM BF08F00D 0000CFED 81022166 LA 41F0F00E 0000CFEE 8102216A SVC 0A27 0000CFEE 8102216A LINK NAME=ASMTDLI ENTRY=(COBOL) 0000CFEF 8102216C BCR 07FE 0000CFF0 8101DBFA L 58D0D004 0000CFF1 8101DBFE L 58E0D00C 0000CFF2 8101DC02 BCR 07FE 0000CFF3 8101CAEC L 58E0B092 0000CFF4 8101CAF0 BCR 07FE 0000CFF5 8101C864 BAS 4DE0B3B4 0000CFF6 8101CB7A ST 50E0B092 0000CFF7 8101CB7E CLC D501300AB484 0000CFF8 8101CB84 BC 4770B40C 0000CFF9 8101CB88 L 5860B446 0000CFFA 8101CB8C BAL 4500B3D2 0000CFFB 8101CB98 SVC 0A09 0000CFFB 8101CB9A DELETE NAME=LDDECTBL ENTRY=00000000 0000CFFC 8101CB9A LTR 12FF 0000CFFD 8101CB9C BC 4770B412 0000CFFE 8101CBA0 L 5810B4B6 0000CFFF 8101CBA4 L 5890B4BE 0000D000 8101CBA8 L 5860B442 0000D001 8101CBAC LR 1809 0000D002 8101CBAE LH 48F0B3EE 0000D003 8101CBB2 BC 47000003 0000D004 8101CBB6 SVC 0A78 0000D004 8101CBB8 FREEMAIN LOC= 00010EC8 LEN= 00000359 0000D005 8101CBB8 LTR 12FF 0000D006 8101CBBA BC 4770B412 0000D007 8101CBBE L 5810B4D6 0000D008 8101CBC2 LH 48F0B4D2 0000D009 8101CBC6 LA 4120B49A 0000D00A 8101CBCA LH 4830B482 0000D00B 8101CBCE SR 1B55 0000D00C 8101CBD0 MVCL 0E24 0000D00D 8101CBD2 L 58E0B092 0000D00E 8101CBD6 BCR 07FE 0000D00F 8101C868 L 58D0B04E 0000D010 8101C86C ST 50FD0010 0000D011 8101C870 LM 98ECD00C 0000D012 8101C874 BCR 07FE 0000D013 80000860 SVC 0A00 GTF trace file DATE=000114 TIME=09375776
Use the option GTFOPT=FIO to trace all file input and output operations including OPEN, CLOSE, GET, PUT, POINT, READ, WRITE etc. Alternatively, use the option GTFOPT=FOC, which traces file open and close operations only, to identify the location within an application where an OPEN or CLOSE is failing.
Here is the GTF trace file for a file input/output trace of the Assembler demo program pgasm04.mlc:
GTF option GTFFILE =D:\MFUSER\CONFIG\GTF.LOG GTF option GTFOPT =FIO GTF option GTFIMIN =00000000 GTF option GTFIMAX =FFFFFFFF GTF option GTFAMIN =00000000 GTF option GTFAMAX =FFFFFFFF GTF trace file DATE=000114 TIME=09504509 INS-CTR INS-ADDR INS-OP 0000002B 80017572 OPENL CB=000172C0 00000070 80017572 OPENL CB=00017320 000000A1 80017AD0 GET CB=000172C0 000000C6 80017AD0 PUT CB=00017320 000000F3 80017AD0 GET CB=000172C0 00000118 80017AD0 PUT CB=00017320 00000145 80017AD0 GET CB=000172C0 0000016A 80017AD0 PUT CB=00017320 00000197 80017AD0 GET CB=000172C0 000001BC 80017AD0 PUT CB=00017320 000001E9 80017AD0 GET CB=000172C0 0000020E 80017AD0 PUT CB=00017320 0000023B 80017AD0 GET CB=000172C0 00000260 80017AD0 PUT CB=00017320 0000028D 80017AD0 GET CB=000172C0 000002B2 80017AD0 PUT CB=00017320 000002DF 80017AD0 GET CB=000172C0 00000304 80017AD0 PUT CB=00017320 00000331 80017AD0 GET CB=000172C0 00000356 80017AD0 PUT CB=00017320 00000383 80017AD0 GET CB=000172C0 000003A8 80017AD0 PUT CB=00017320 000003D5 80017AD0 GET CB=000172C0 000003FA 80017AD0 PUT CB=00017320 00000427 80017AD0 GET CB=000172C0 0000044C 80017AD0 PUT CB=00017320 00000479 80017AD0 GET CB=000172C0 0000049E 80017AD0 PUT CB=00017320 000004CB 80017AD0 GET CB=000172C0 000004F0 80017AD0 PUT CB=00017320 0000051D 80017AD0 GET CB=000172C0 00000542 80017AD0 PUT CB=00017320 0000056F 80017AD0 GET CB=000172C0 000005A2 80017E8A CLOSEL CB=000172C0 000005DE 80017E8A CLOSEL CB=00017320 GTF trace file DATE=000114 TIME=09504618
Use the option GTFOPT=MEM to focus on the allocation and deallocation of memory in an Assembler application. The information shown includes the address and length of memory allocated above and below the 16 megabyte line.
Here is the GTF trace file for a memory allocation trace of the Assembler demo program testvml.mlc:
GTF option GTFFILE =D:\MFUSER\CONFIG\GTF.LOG GTF option GTFOPT =INS,MEM GTF option GTFIMIN =00000000 GTF option GTFIMAX =FFFFFFFF GTF option GTFAMIN =00000000 GTF option GTFAMAX =FFFFFFFF GTF trace file DATE=000114 TIME=10044120 INS-CTR INS-ADDR INS-OP 00000001 81007E78 BALR 05C0 00000002 81007E7A LR 18BE 00000003 81007E7C BAL 4510C03A 00000004 81007EB4 SVC 0A23 00000005 81007EB6 PACK F232C158C173 00000006 81007EBC PACK F232C15CC176 00000007 81007EC2 PACK F272C166C179 00000008 81007EC8 CVB 4F20C166 00000009 81007ECC MH 4C20C17E 0000000A 81007ED0 MH 4C20C17E 0000000B 81007ED4 CP F930C158C181 0000000C 81007EDA BC 4780C0CA 0000000D 81007EDE BAL 4510C08C 0000000E 81007F06 SVC 0A23 0000000F 81007F08 LR 1802 00000010 81007F0A ICM BF08C097 00000011 81007F0E BC 47000000 00000012 81007F12 SR 1B11 00000013 81007F14 BCTR 0610 00000014 81007F16 SVC 0A0A 00000014 81007F18 GETMAIN LOC= 00010010 LEN= 00100000 00000015 81007F18 BAL 4510C0BE 00000016 81007F38 SVC 0A23 00000017 81007F3A SP FB30C158C180 00000018 81007F40 BC 4720C08E 00000019 81007F08 LR 1802 0000001A 81007F0A ICM BF08C097 0000001B 81007F0E BC 47000000 0000001C 81007F12 SR 1B11 0000001D 81007F14 BCTR 0610 0000001E 81007F16 SVC 0A0A 0000001E 81007F18 GETMAIN LOC= 00110020 LEN= 00100000 0000001F 81007F18 BAL 4510C0BE 00000020 81007F38 SVC 0A23 00000021 81007F3A SP FB30C158C180 00000022 81007F40 BC 4720C08E 00000023 81007F44 CP F930C15CC181 00000024 81007F4A BC 4780C136 00000025 81007F4E BAL 4510C0FC 00000026 81007F76 SVC 0A23 00000027 81007F78 LR 1802 00000028 81007F7A LH 48F0C106 00000029 81007F7E BC 47000022 0000002A 81007F82 SVC 0A78 0000002A 81007F84 GETMAIN LOC= 01008010 LEN= 00100000 0000002B 81007F84 BAL 4510C12A 0000002C 81007FA4 SVC 0A23 0000002D 81007FA6 SP FB30C15CC180 0000002E 81007FAC BC 4720C0FE 0000002F 81007F78 LR 1802 00000030 81007F7A LH 48F0C106 00000031 81007F7E BC 47000022 00000032 81007F82 SVC 0A78 00000032 81007F84 GETMAIN LOC= 01108020 LEN= 00100000 00000033 81007F84 BAL 4510C12A 00000034 81007FA4 SVC 0A23 00000035 81007FA6 SP FB30C15CC180 00000036 81007FAC BC 4720C0FE 00000037 81007FB0 BAL 4510C154 00000038 81007FCE SVC 0A23 00000039 81007FD0 BCR 07FB 0000003A 80000860 SVC 0A00 GTF trace file DATE=000114 TIME=10044864
Here is the trace file for a program that attempts to add 1 to a packed decimal field containing spaces. The PSW contains interrupt code 7 corresponding to the MVS abend 0C7 that would occur on the mainframe.
GTF option GTFFILE =GTF.LOG GTF option GTFOPT =ALL GTF option GTFIMIN =00000000 GTF option GTFIMAX =FFFFFFFF GTF option GTFAMIN =00000000 GTF option GTFAMAX =FFFFFFFF GTF trace file DATE=000114 TIME=10565281 INS-CTR INS-ADDR INS-OP 00000001 81007FE8 BALR 05C0 00000002 81007FEA LA 41100002 00000003 81007FEE AP FA10C00CC00E R0-R7 00000000 00000002 00000000 00000000 00000000 00000000 00000000 00000000 R9-RF 00000000 00000000 00000000 00000000 81007FEA 00002870 00000860 01007FE8 00000003 81007FF4 PGMCHK PSW=0000000781007FF4 GTF trace file DATE=000114 TIME=10565286
Copyright © 2001 Micro Focus International Limited. All rights reserved.
This document and the proprietary marks and names
used herein are protected by international law.