Set the BINFILE emitter properties to control the behavior and appearance of the binary trace file when viewed using the CTF Viewer.
The format of the trace files is platform independent, so you can use CTF Viewer to view binary trace files that were created on UNIX, for example.
To enable the BINFILE emitter, specify the following statement in the Consolidated Tracing Facility configuration file:
mftrace.dest = BINFILE
The following list shows the properties you can set to control the behavior of the BINFILE emitter:
| Property
|
Description
|
Default
|
| FILE
|
The name of the trace file to be written. You can use the following pseudo-variables for the construction of the trace file name:
- $(APPNAME)
- The basename of the executable invoked to start the current process. For example, if
run.exeis invoked, $(APPNAME) has the value
"cobrun".
- $(EMITTER)
- Always "BINFILE" for this emitter.
- $(GEN)
- The generation of the file, starting from 1.
- $(PID)
- The operating system identifier for the current process.
- $(PLATFORM)
- A platform specific constant, useful when two run-time systems are in the same process, and you require separate trace files. Can be one of:
- native
- For all native processes
- dotnet
- For Microsoft .NET processes
- jvm
- For JVM processes
- $(RUNUNIT)
- A unique number that represents the managed RunUnit ID (applies to .NET and JVM COBOL only).
- $(RUNUNIT_SESSIONNAME)
- The session name passed to the managed RunUnit (applies to .NET and JVM COBOL only).
- $(RUNUNIT_GUID)
- The globally unique identifier associated with the managed RunUnit (applies to .NET and JVM COBOL only).
|
$(APPNAME).$(EMITTER).$(PID).ctb, or
$(APPNAME).$(EMITTER).$(PID).ctb_$(GEN) if the MAXGENERATION property has been specified. For example:
- If the BINFILE emitter is being used to output trace events for
cobrun
executing as process-id 3456 and the MAXGENERATION property has not been specified, the trace file created will be called
cobrun.binfile.3456.ctb
.
- If the binfile emitter is being used to output trace events for
myapp
executing as process-id 1975 and the MAXGENERATION property has been set to 3, the trace files created will be called
myapp.binfile.1975.ctb_1,
myapp.binfile.1975.ctb_2, and
myapp.binfile.1975.ctb_3.
|
| FLUSHEVERY
|
The number of trace records that will be output before the file is flushed. 0 indicates that the file will never be explicitly flushed.
|
1
|
| FORMAT
|
- $(RUNUNIT)
- A unique number that identifies the RunUnit that relates to the trace event.
|
|
| LOCATION
|
The folder where the trace files are to be written.
|
The folder specified by the MFTRACE_LOGS environment variable. If MFTRACE_LOGS is not set, the current folder is used.
If the folder specified by the LOCATION property does not exist, the Consolidated Tracing Facility tries to create it. If this fails, the Consolidated Tracing Facility uses the default location (as specified by the MFTRACE_LOGS environment variable). If this fails, the current folder is used.
|
| MAXFILESIZE
|
The maximum amount of data (in Kb) that will be written to the trace file before the file is closed and the next trace file in the generation sequence is opened. The first trace file in a generation sequence results in the $(GEN) pseudo-variable (see the description of the FILE property, above) being set to 1, the second in the sequence results in it being set to 2, and so on until MAXGENERATION is exceeded. Once the MAXGENERATION number of files has been reached, the generation number reverts to 1 and the first trace file in the generation is overwritten. This is only used if MAXGENERATION > 1.
|
0x00002800, indicating a maximum file size of 10 Mb.
|
| MAXGENERATION
|
The maximum number of trace files that will be written to while tracing is enabled. Use this property in conjunction with the MAXFILESIZE property.
|
1, indicating that only a single trace file will be created.
|
| MultiProc
|
Controls whether trace events are written to the trace file by a single process or by multiple processes. If enabled for multiple processes, the
File property must also be specified without the
$(PID) pseudo-variable embedded in its name.
if $(RUNUNIT), $(RUNUNIT_SESSIONNAME), or $(RUNUNIT_GUID)" is used, the file name will be unique, therfore MultiProc is not required (applies to .NET and JVM COBOL only)
|
FALSE, indicating that the configured trace file includes only events from the current process
|
| Rununitid
|
Controls whether the RunUnit information is included in the trace.
|
TRUE
|
Performance considerations:
When using the MultiProc property, and two or more COBOL run-time systems (native, .NET or JVM) are executing in the same process, sharing the same trace file is not a performant configuration. Using the
$(PLATFORM) variable in the filename allows you to use different filenames for different run-time systems. If tracing includes the
$(PID) variable, you can safely set the MultiProc property to false. For example:
$(APPNAME). $(EMITTER).$(PID).$(PLATFORM).ctb
When a JVM or .NET COBOL application executes in a multi-user environment, the user of managed RunUnits should be used. The default filename for both the TEXTFILE and BINFILE emitter collects all the trace events into one or more files. However, if the configuration property #file uses $(RUNUNIT), $(RUNUNIT_SESSIONNAME) or $(RUNUNIT_GUID), separate files can be created for each RunUnit. For example:
$(APPNAME).$(PLATFORM).$(EMITTER).$(RUNUNIT_GUID).log
or
$(APPNAME).$(PLATFORM).$(EMITTER).$(RUNUNIT).log
or
$(APPNAME).$(PLATFORM).$(EMITTER).$(RUNUNIT_SESSIONNAME).log
JVM COBOL restrictions:
If a JVM COBOL application is executing in a permissions-restricted environment, use of the MultiProc property on the BINFILE emitter is not available.
