WebSphere Message Service Client for C/C++, Version 2.0.2 Operating Systems: AIX, Linux, Solaris, Windows

FFDC and trace configuration for C/C++ applications

First Failure Data Capture (FFDC) records are stored in human readable text files with names that start with the prefix xmsffdc. Trace files are binary and can be formatted. Trace file names start with the prefix xms.

XMS creates FFDC records and trace files in the current working directory, unless you specify an alternative location by configuring an XMS environment variable as described below.

Trace configuration using XMS environment variables

To configure trace for an XMS C or C++ application, set the following XMS environment variables before running the application:

Table 1. Environment variable settings for C/C++ trace
Environment variables Default Settings Meaning
XMS_TRACE_ON Not applicable normal Selected components are traced.
    full All components are traced.
    partial A comma separated list of component identifiers to trace. For example, "partial,osa,cal" only traces XMS components gxiosa and gxical. Use full trace to show the components that can be traced.
XMS_TRACE_FILE_PATH Current working directory /dirpath/ The directory path that trace and FFDC records are written to.

XMS creates FFDC and trace files in the current working directory, unless you specify an alternative location by setting the environment variable XMS_TRACE_FILE_PATH to the fully qualified path name of the directory where you want XMS to create the FFDC and trace files. You must set this environment variable before you start the application that you want to trace, and you must make sure that the user identifier under which the application runs has the authority to write to the directory where XMS creates the FFDC and trace files.

XMS_TRACE_FILE_SIZE 200000 integer The maximum size that XMS product trace can grow to (in kilobytes), that is, 10 represents 10,000 bytes.
XMS_TRACE_FILE_NUMBER 4 integer The number of files that can be used to store trace records. (200000 / 4 = 50000 bytes per file.)

Dynamic trace configuration

To configure trace dynamically, use the executable gxisc. You can use gxisc to enable and disable trace in a running XMS C or C++ application, and to modify the trace size. You must run gxisc on the same machine as the XMS application.

To invoke gxisc, use the process id of the XMS application for which you want to alter the trace configuration, as shown in the example below.

gxisc 1234                              <enter>
display all                             <enter>
alter trace(enabled) tracesize(100)     <enter>
help                                    <enter>
alter trace(disabled)                   <enter>
alter                                   <enter>
end

gxisc                                   <enter>
alter pid(1234) trace(enabled)          <enter>
end

cat a.file                              <enter>

        alter pid(1234) trace(enabled)
        end

cat a.file | gxisc                      <enter>


cat b.file                              <enter>

        alter trace(disabled) tracesize(1000)
        end

cat b.file | gxisc 1234                 <enter>

Note: Trace settings are not retained after the XMS C or C++ application terminates.

Trace file formatting

To minimize processing and disk overheads at runtime, XMS outputs trace in a binary format into one or more trace files with the extension .trc. You can format trace files by using the executable gxitrcfmt, as shown in the following example:

gxitrcfmt xms01234.trc

A formatted file has the suffix txt, for example:

cat xms01234.trc.txt

Concept topic

Terms of Use | Rate this page

Last updated: 24 May 2011

(C) Copyright IBM Corporation 2005, 2011. All Rights Reserved.