Using the Generalized Trace Facility

The Assembler Generalized Trace Facility (GTF) is a debugging tool that helps 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 can 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.

Note: Under the Enterprise Server environment any trace file will be locked for exclusive access by the server, so in order to examine the file you must first stop the server.

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 %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin\MF370CTL.CFG file.

Configuring GTF

You can specify the following GTF options after the GTFFILE environment variable:

Option	Description
GTFIMIN	The instruction count at which to start the trace. The default is 00000000.
GTFIMAX	The instruction count at which to end the trace. The default is FFFFFFFF.
GTFAMIN	The instruction address at which to start the trace. The default is 00000000.
GTFAMAX	The instruction address at which to end the trace. The default is 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: INS Trace each instruction BAL Trace each BALR, BASR, and BASSM instruction SVC Trace each SVC instruction PGM Trace each LOAD, DELETE, and LINK FOC Trace each file OPEN and CLOSE operation FIO Trace each file input and output operation, as well as each OPEN and CLOSE MEM Trace GETMAIN, FREEMAIN, and STORAGE ALL All of the above trace options REG Trace the 16 general-purpose registers at each trace event The default value is BAL, PGM, FOC.

The size of a trace file depends on the options that you specify and can be very large. Therefore 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. Note that this increases the size of the trace file by a factor of three. 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:

INS, because this traces every instruction
MEM and PGM, because with these options the trace is performed at the end of the instructions affected such as LOAD and GETMAIN

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.

The Trace File

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:

Instruction count. This is a hexadecimal counter showing the total number of instructions executed up to the trace point. This count is very useful when you want to work out where to start a detailed trace at a point deep into a complex application where the same code may be executed many times before the point of failure. You use the option GTFIMIN to set the starting instruction count for a trace.
Instruction address. This is the linear address of the next instruction at the current trace point. This address provides an alternative way of specifying where you want a detailed trace to start. You use the option GTFAMIN to set the starting instruction address for a trace.

Instruction operation. This field indicates the machine instruction or run-time operation being performed at the trace point. Additional information may follow depending on the type of trace line:

Trace Line Type	Description
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

Default Trace Option

Use the default trace option GTFOPT=PGM,BAL,FOC to trace LOAD, DELETE, LINK, BALR, BASR, OPEN, and CLOSE operations. This enables you to get an overview of what an application is doing and to identify possible starting and ending points for more detailed traces if required.

Below is an example 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

Detailed Trace Option

Use the GTFOPT=ALL option to obtain a detailed trace.

Below is an example of a detailed trace of the last section of code starting with BALR (instruction count CFEB) in the default trace example above. 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

Program Interruption Information

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