This chapter describes how to use the facilities provided for tracing file operations, which are provided to help in investigations into problems with file handling.
The File Handler facilities for tracing file operations enable you to:
You use the File Handler configuration parameters TRACE, TRACEFILEEXTEND, TRACEFILENAME, LOG and LOGFILENAME to control tracing and logging activities:
You can set TRACE and LOG either globally or for individual files, but you can only set TRACEFILEEXTEND, TRACEFILENAME and LOGFILENAME globally.
For more information about setting configuration options globally or for individual files, see the section Configuration File in the chapter File Handler Configuration.
Here is an example configuration file:
[XFH-DEFAULT] TRACE=OFF TRACEFILENAME=/trace/mftracefile.xfh TRACEFILEEXTEND=ON LOG=ON LOGFILENAME=/temp/mflogfile.log [datafile1.dat] TRACE=ON [datafile2.dat] LOG=OFF
In this example file tracing is set off globally and set on for the data file named datafile1.dat; new trace records are appended to the trace file, c:\trace\mftracefile.xfh, if it already exists. Logging is set on globally and set off for the data file named datafile2.dat.
Note: If the trace file might exceed a size of 4GB, you will also need to specify the configuration options FILEMAXSIZE=8 and IDXFORMAT=8.
You can turn tracing on and off from within a COBOL program either by setting the appropriate flags in the FCD or by using library routines. You might want to do this to focus on file handling problems in a subset of an application's operations. When you set FCD flags you do it for a particular file. When you use the library routines, the trace settings affect all the file operations executed by the program from that point on.
When you do dynamic tracing, you use two flags together. This is because file operations such as READs and WRITEs can be traced only if the OPEN operation was traced. If you execute a program with tracing turned off, open a file, then switch dynamic tracing on, the tracing mechanism won't be able to trace any subsequent operations. The best way to proceed is to switch dynamic tracing on for OPENs and CLOSEs at the beginning of the program, then switch tracing for all operations on and off as required. However, the tracing of OPEN and CLOSE operations on its own can also be useful.
To use the FCD flags you must have access to the FCD; see the section Accessing the FCD in the chapter File Handler and Sort APIs.
File tracing is controlled by two flag bit settings within the FCD:
Change these bit settings as required to control tracing for individual files.
If you want to use dynamic tracing in a program you must first issue a call to the mFFH library routine or perform an I/O operation using a standard COBOL statement. This initializes the File Handler.
The library routines provide a means of obtaining the same tracing behavior as setting the FCD flags without the need to have the FCD available. All changes to tracing behavior made using the library routines affect all files subsequently accessed.
To control tracing, issue calls to the MFFH_MODIFY_TRACE library routine. You can:
To disable all the modifications that you have set, issue a call to the library routine MFFH_MODIFY_DISABLE.
For further information see the topics mFFH, MFFH_MODIFY_TRACE and MFFH_MODIFY_DISABLE.
You can use the Trace Player, xfhrepro, to read and optionally replay the tracing information created when you have file operation tracing configured on. Tracing information is stored for one or more processes, with each process identified as a separate session. An operation trace consists of the I/O number (a number starting from 1 giving the position of the operation in the sequence of operations), the session ID, the opcode, file status resulting from the call and the name of the file. Additional information can optionally be displayed.
There are various ways to use the Trace Player:
The format of the command line is:
xfhrepro [options]
The options specified on the command line define the operation to be carried out by the Trace Player. The following options are available:
num | Replays all the operations in one session, where num is the session ID. If num = 0, all the operations in all the sessions are replayed. |
/a | Displays arguments; use in conjunction with /d |
/d | Displays the trace information for each operation in I/O number order |
/eop-num | Ends the replay at the I/O number op-num |
/f | Displays the files needed for a replay |
/nfilename | Trace a specific file |
/pop-num | Pauses the replay at the I/O number op-num; press Enter to continue |
/t | Displays only operations that fail and final status |
If you run xfhrepro with no options, it creates the script that plays back each session in session order and informs you of the script's name. You must do this before every invocation of the script.
Here are some examples of typical output.
Example /d output
I/O Sess Op Opcode Act Exp Filename O Number Id Code Desc Stat Stat K -------- ---- ---- -------- ----- ----- ------------------------------ - 00000001 0001 FA02 Open \ 0\0 .\CATALOG.DAT 00000002 0001 FAF6 Read Ran \ 0\0 .\CATALOG.DAT 00000003 0001 FA02 Open \ 0\0 .\CATALOG.DAT
Example /d /a output
I/O Sess Op Opcode Act Exp Filename O Number Id Code Desc Stat Stat K -------- ---- ---- -------- ----- ----- ------------------------------ - 00000001 0001 FA02 Open \ 0\0 .\CATALOG.DAT fcd-version. 00 organisation 02 access-mode. 88 open.mode... 80 opt2........ 20 shr2........ 08 shr......... 84 opt......... 20 osp......... 80 file-format. 08 flags1...... 03 misc........ 10 RBA =000000000000 Rec Len = 010476 Session-id = 000000000000 FS-file-id = 000000000000 00000002 0001 FAF6 Read Ran \ 0\0 .\CATALOG.DAT fcd-version. 00 organisation 02 access-mode. 88 open.mode... 02 opt2........ 20 shr2........ 08 shr......... 84 opt......... 20 osp......... 80 file-format. 08 flags1...... 03 misc........ 10 RBA =000000000000 Rec Len = 010476 Session-id = 000000000000 FS-file-id = 000000000000 00000003 0001 FA02 Open \ 0\0 D:\Catalogs\TempOLFiles\Catalo fcd-version. 00 organisation 02 access-mode. 88 open.mode... 80 opt2........ 20 shr2........ 08 shr......... 84 opt......... 20 osp......... 80 file-format. 08 flags1...... 03 misc........ 10 RBA =000000000000 Rec Len = 010476 Session-id = 000000000000 FS-file-id = 000000000000
Example replay output
I/O Sess Op Opcode Act Exp Filename O Number Id Code Desc Stat Stat K -------- ---- ---- -------- ----- ----- ------------------------------ - 00000001 0001 FA02 Open 0\0 0\0 .\CATALOG.DAT - 00000002 0001 FAF6 Read Ran 0\0 0\0 .\CATALOG.DAT - 00000003 0001 FA02 Open 0\0 0\0 .\CATALOG.DAT -
Act Stat is the actual status returned when xfhrepro is run. Exp Stat is the status returned when the trace was recorded. In theory these two should be the same but in practice, they can be different. Act Stat is blank when you do a display because there is no actual status.