Documentation
(C) IBM Corp. 1996, 1999

Text Extender: Administration and Programming

TXTRACE

This command writes processing information to a trace buffer in shared memory. This information can be used for tracing faults. It can be written in binary from the trace buffer to a file for later formatting when tracing has been switched off, or can be formatted and written to a file while tracing is still on.

Authorization

(UNIX only) SYSADM, DBADM.

Command syntax

>>-txtrace--| parameters |-------------------------------------><
 
parameters
 
|---+-on--+--------------+--------------------------------------------+->
    |     '-| options |--'                                            |
    +-dump--| dump-file |---------------------------------------------+
    +-off-------------------------------------------------------------+
    +-format--+--------------+---+->-------------+---| format-file |--+
    |         '-| options |--'   '-| dump-file |-'                    |
    +-change----------------------------------------------------------+
    +-clear-----------------------------------------------------------+
    +-flow------------------------------------------------------------+
    '-information-----------------------------------------------------'
 
>---------------------------------------------------------------|
 
options
 
    .-------------------------------------------------------------.
    V                                                             |
|-----+- -m--products--.--events--.--components--.--functions--+--+->
      +- -rc--return-code--------------------------------------+
      +- -e--max-system-errors---------------------------------+
      +- -r--max-record-size-----------------------------------+
      '- -i--initial-buffer-size--|-- -l--last-buffer-size-----'
 
>---------------------------------------------------------------|
 
dump-file
 
|---+-------+---dump-filename-----------------------------------|
    '-path--'
 
format-file
 
|---+-------+---format-filename---------------------------------|
    '-path--'
 

Command parameters
Note:

A -u option is also available with all of the TXTRACE parameters to display information about the parameter.

on
To start the trace facility.

dump | dmp
To write the trace information in binary to a file.

off
To stop the trace facility.

format | fmt
To format the binary trace information. You can format the dump file, when tracing is switched off, by specifying the name of the dump file and the name of the file to hold the formatted trace information. To format the trace information directly from the trace buffer while tracing is still switched on, enter: destrc format > filename.tmp.

change | chg
To change the trace mask, maxSysErrors, or maxRecordSize.

clear | clr
To clear the trace.

flow | flw
To show control flow of the trace.

information | info | inf
To get information about the trace.

options
To filter the trace information either when turning tracing on (this reduces the shared memory usage), or when formatting the trace information. Unless the trace is very large, it is usually easier to write the full trace information and then filter it during formatting.

-m
To add a "mask" to specify which events, components, and functions are to be included in the trace. The default is to trace everything. The mask is in four parts, separated by periods; for example: 2.2-6.1,3.* You can specify a range using "-" as a separator character, or a list using "," as a separator character. For example: 2-6 includes only the events whose IDs are in the range from 2 to 6. To include only components 2 and 6, specify 2,6

products
Product ID. The product ID for Text Extender is "2". The product ID for TextMiner is "3".

events
The set of event types to be included in the trace:
0
system_error
1
system_error
2
system_error
3
non-fatal_error
4
non-fatal_error
5
api_errcode
7
fnc_errcode
8
trap error
10
api_entry
11
api_exit
13
api_retcode
15
api_data
30
fnc_entry
31
fnc_exit
33
fnc_retcode
35
fnc_data

components
The components to trace.

The component IDs for Text Extender are:

1
COMMAND_LINE_INTERFACE
2
UDF
3
STORED_PROCEDURES
4
ADMINISTRATION
5
INDEX_CONTROL
6
LIBRARY_SERVICES
7
DES_PARSER
8
DES_DEMON
9
DES_API
10
SERVICES

The component IDs for TextMiner are:

1
automachine
2
bgproc (background processing)
3
cluster
4
common
5
commsrvc (common services)
6
communic (communication)
7
daemon
8
dsclient
9
environ (environment)
10
glue
11
idxcomm (index build, common part)
12
libsrv (library services)
13
search
14
trace
15
guru
16
indexbld (index build, tm only)
17
indexeng (index engine, tm only)
18
smsearch
19
search engine, tm only)
20
tmsearch
21
gtrcm (gtr, common part)
22
gtrsrch (search, gtr only)
23
gtridx (index build, gtr only)

functions
Asterisk (*). The set of functions to trace. Use an asterisk (*) to trace all functions unless directed to do otherwise by the IBM Support Center.

-rc return-code
Treat return-code as a system error.

-e max-system-errors
Integer. To stop the trace after this number of errors. The default is 1 which specifies that when the first system error occurs, all subsequent tracing of lower severity events is suppressed. This is acceptable if you are interested only in the first major error, but you should specify a higher number (such as -e 50) if you want to see the full trace after the initial system error. The trace destination is shared memory.

-r max-record-size
Integer. To stop the trace after this number of records have been written to the trace file. The default is 16 KB.

-i initial-buffer-size
Integer. To keep this number of records from the beginning of the trace. If -i is specified, the default is 16 KB. On a UNIX system, a recommended buffer size is 2 MB.

If neither -i nor -l are specified, -l is the default.

If you specify -i, no wrapping occurs; no further trace entries are written if the volume of records exceeds max-record-size, even if you clear all trace entries. To get new trace entries written, increase the buffer size, turn the trace off and then on again.

-l last-buffer-size
Integer. To keep this number of records from the end of the trace. The default is 16 KB. On a UNIX system, a recommended buffer size is 2 MB.

path
The directory where the corresponding file is stored.

dump-filename
The name of the file that contains the binary trace information.

formatted-filename
The name of the file that contains the formatted trace information.

Examples

See Tracing faults.


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]