15.3.1 Extended Trace Commands

Description

This command opens a trace file and performs initial processing for collecting traces. To invoke the collecting of script execution traces, this command must be called first.

Synopsis

sw_TcOpenTrace [-size fsize] [-level tlevel]
[-mode group|other] filename

Options

-size fsize

Specify the maximum size of one trace file in fsize. The value can be any number from 1 to 100,000 (KB). It defaults to 50 (KB).

In the trace collection, two files are created to cyclically collect traces and, thus, the estimated maximum file size will be twice as much as the size specified here.

-level tlevel

Specify the trace level in tlevel in the range from 0 to 2. It defaults to 1. The following table lists what is collected and recommended examples for each trace level.

Disables the subsequent sw_TcWriteTrace commands and no trace is collected.

Only level-1 traces are collected in the subsequent sw_TcWriteTrace.

Example: Using to output the information collected when Systemwalker Scripts are actually running.

Output of information that is kept as operation logs such as results of startup or processing
Output of information that is kept as error logs such as details for errors detected

Both level 1 and 2 traces are collected in the subsequent sw_TcWriteTrace.

Example: Using to output the information collected when performing operation verification test and debugging

Output of information that is kept as script root check, such as breakpoints and the points before and after external programs are invoked
Output of information that is kept as information within scripts, such as the contents of read files and values of variables used in handling loops

-mode group|other

Specify the write mode for the trace file to create. If omitted, the write permission attribute is set for the owner. This option is ignored on Windows.

group: Specify the write permission attribute for the owner and group.

other: Specify the write permission attribute for the owner, group, and others.

filename

Specify the name of a trace file. If the filename is specified without its path, the trace is collected into the default trace storage directory. If it is specified with its path, the trace is collected in accordance with the path.

For Windows, the file names on Windows can be also separated by a slash (/) in addition to the backslash sign (\). When using a backslash sign, the entire file name must be enclosed in braces ({}) so as not to be treated as an escape character.

By default, the traces are stored in the following directory:

[Windows]

Systemwalker Operation Manager installation directory \MpWalker.JM\mpfwtco\trc

[UNIX]

/var/opt/FJSVfwtco/trc

Note

The directory where a trace file is created should be the directory for which the Systemwalker Script execution user has update rights.

Information

Two files are created to cyclically collect traces. Thus "#1.txt" or "#2.txt" is appended to the end of the filename you specified.

For example, if you specify {c:\tmp\trc}, trc#1.txt and trc#2.txt will be created under c:\tmp. [Windows]

If you specify "/var/tmp/trc", trc#1.txt and trc#2.txt will be created under /var/tmp. [UNIX]

Return Values

Positive value:	Normal termination. A handle used in a trace command
-9:	Insufficient memory
-15:	Code conversion error
-17:	File open error

Reference

sw_TcCloseTrace

Examples

[Windows]

The following example opens traces with c:\var\tmp\usrtrc given as the trace file and stores the handle in the variable hwnd.

set hwnd [sw_TcOpenTrace {c:\var\tmp\usrtrc}]

[UNIX]

The following example opens traces with /var/tmp/usrtrc given as the trace file and stores the handle in the variable hwnd.

set hwnd [sw_TcOpenTrace /var/tmp/usrtrc]

15.3.1.2 sw_TcWriteTrace (Output Trace Information Command)

Description

This command outputs trace information to a trace file.

Synopsis

sw_TcWriteTrace [-level tlevel] thandle text

Options

-level tlevel: Specify trace level 1 or 2 in tlevel. It defaults to 1.

thandle: Specify the handle obtained by sw_TcOpenTrace. If a null string ("") is specified, traces will not be collected.

text: Specify a string to be output to the trace file. It should be specified within 900 bytes. Part of a string exceeding 900 bytes will be truncated to 900 bytes.

Return Values

TCOK:	Normal termination
TCERR_WRITE:	File write error
TCERR_CODECONV:	Code conversion error

Reference

sw_TcOpenTrace

Example

The following example writes the string "File open error"to the trace file given by hwnd if the return value of sw_TcOpenTrace has been stored in the variable hwnd.

sw_TcWriteTrace $hwnd "File open error"

Execution Results/Output Format

Description of Output Items

The following explains items that are output in the above example:

(1) Time:: The time that the trace information was output in the form of "Day of the week Month Day Hour:Min:Sec Year".

(2) Process ID:: Process ID of Systemwalker Script

(3) String:: String specified by sw_TcWriteTrace

15.3.1.3 sw_TcCloseTrace (Close Trace File Command)

Description

This command closes a trace file and terminates the collection of traces.

Synopsis

sw_TcCloseTrace thandle

Option

thandle: Specify the handle obtained by sw_TcOpenTrace.

Return Values

TCOK:	Normal termination
TCERR:	Abnormal termination

Reference

sw_TcOpenTrace

Example

The following example closes the trace file given by hwnd if the return value of sw_TcOpenTrace has been stored in the variable hwnd.

sw_TcCloseTrace $hwnd