Problem:
This document details what is needed to configure and use the Micro Focus External File Handler, File Tracing.
When problems occur while using Micro Focus indexed files, such as data and/or index corruption, you may be asked to enable File Tracing in your application, in order to assist Micro Focus SupportLine personnel in resolving the file issues.
After enabling File Tracing, you would run your application in the normal manner with the goal of reproducing the reported error within the indexed files. File Tracing will cause each file handling I-O operation, including data, to be written to the trace file. Micro Focus personnel can then use a special debugging tool to replay the trace file step-by-step using a "before" image of the files being traced. This allows us to locate the particular I-O operation which may have caused the files to become corrupt.
For more general information on how to configure the External File Handler and a description of the File Handler configuration parameters, look in the Net Express File Handling Programmer's Guide, chapter 6, "File Handler Configuration".
Resolution:
This document contains the following sections:
o
How to configure the External File Handler
o
How to configure the External File Handler configuration options for File Tracing
o
Runtime system requirement for the External File Handler File Tracing
o
Material necessary when sending File Tracing information to Micro Focus SupportLine
How to configure the External File Handler
To enable File Tracing, the "Trace" option of the External File Handler must be set. External File Handler options are specified in a configuration file with the default name of EXTFH.CFG.
The EXTFH environment variable can be set to specify the exact location and name of the configuration file to be used. Although the configuration file can be given any allowable filename, in this document we will use the default name of EXTFH.CFG.
1.
From a command prompt use:
SET EXTFH=drive:\\directory\\EXTFH.CFG
drive
= Drive containing the EXTFH.CFG file.
Directory
= Full path containing the EXTFH.CFG file.
2.
Create or update a file called EXTFH.CFG.
Or under Windows Control Panel> System> Advanced> Environment Variables, create a system wide environment variable named EXTFH and set it as described above.
How to configure the External File Handler configuration options for File Tracing
The following configuration options are needed to enable File Tracing:
TRACE
TRACEFILENAME
TRACEFILEEXTEND
LOG
LOGFILENAME
To change the default behavior for all files used in an application, a section named XFH-DEFAULT must be included in the configuration file. This is where the parameters that apply to all files used by the application are defined.
For example:
[XFH-DEFAULT]
BASENAME=ON
TRACE=OFF
TRACEFILENAME=drive:\\directory\\tracefilename
TRACEFILEEXTEND=ON
LOG=ON
LOGFILENAME=drive:\\directory\\logfilename
When using this example configuration file, the following behavior is set for all files used in your application:
1)
BASENAME=ON
To customize the behavior of a particular file the base name of the file will be used, for example; filename.dat rather than a fully qualified name such as drive:\\directory\\filename.dat
2)
TRACE=OFF
Tracing for all files will be turned off by default
3)
TRACEFILENAME=drive:\\directory\\tracefilename
The name of the trace filename is set.
4)
TRACEFILEEXTEND=ON
The TRACEFILEEXTEND parameter affects the functioning of File Handler Tracing (see also the TRACE parameter). By default, when tracing is switched on, the File Handler will attempt to create a new trace file when it is first invoked, which will overwrite any existing trace file. By setting TRACEFILEEXTEND=ON, the trace file will be extended.
5)
LOG=ON
When LOG is set to ON, any unusual file-related situations, such as corrupted files, or automatic file recovery, are noted in a log file for later examination.
6)
LOGFILENAME=drive:\\directory\\logfilename
The name of the log filename is set.
You'll need to decide File Tracing is required for all files or only specific files. If File Tracing is required for all files, change the TRACE parameter under the XFH-DEFAULT heading from OFF to ON.
To restrict File Tracing to specific files, add TRACE=ON, after the square bracketed heading consisting of the file name and extension, for each file needed to be traced.
[filename.extension]
TRACE=ON
IMPORTANT NOTE: If the generation of the specified trace file results in a file which might exceed a size of 4GB, you will also need to specify the relevant File Handler configuration options for FILEMAXSIZE and IDXFORMAT, if your Operating System permits it.
Typical example of a File Handler configuration file that enables File Tracing;
[XFH-DEFAULT]
BASENAME=ON
TRACE=OFF
TRACEFILENAME=c:\\trace\\mftracefile.xfh
TRACEFILEEXTEND=ON
LOG=ON
LOGFILENAME=c::\\temp\\mflogfile.log
FILEMAXSIZE=8
IDXFORMAT=8
[datafile.dat]
TRACE=ON
This example configuration file will enable the File Handler logging and File Tracing for the data file named datafile.dat.
Runtime System Requirement for the External File Handler File Tracing
In order to use File Tracing, the appropriate system modules must be present in your deployment environment. The system module XFHTRACE must be available at execution time. This module is provided as "xfhtrace.obj" located in your Net Express\\Base\\Lib directory.
The easiest way to deploy this module is to create a dynamic link library named "xfhtrace.dll" using the object file provided. To create "xfhtrace.dll", from a Net Express command prompt use the following command:
cbllink -D xfhtrace
Copy "xfhtrace.dll" to the same location as the rest of the Net Express runtime files.
IMPORTANT NOTE: If the data files that you will be tracing are using Data and/or Key Compression, then the appropriate compression system object files (.obj) will also need to be linked with your "xfhtrace.dll". For example;
cbllink -D xfhtrace cbldcxxx -oxfhtrace
Where xxx is the appropriate compression routine value used.
Material necessary when sending File Tracing information to Micro Focus SupportLine
1)
Backup copy/image of the data file(s) and corresponding .idx file(s), if required, before File Tracing is enabled
2)
Trace and/or log file generated
3)
Copy/image of the data file(s) and corresponding .idx file(s), if required, after File Tracing is turned off.
Published in the June 2004 issue of the SupportLine Newsletter.
