Tracing in Java client programs

You can control tracing in Java™ client programs by issuing various calls and by setting properties. Ideally applications should implement an option that activates trace.

Calling the com.ibm.ctg.client.T trace class

Here is an example of how to call this class from within a user application:

if (getParameter("trace") != null)  
 {
   T.setOn(true);  
 }
where trace is a startup parameter that can be set on the user program.

Setting the gateway.T trace system property

Here is an example of how to set this property:

java -Dgateway.T=on com.usr.smp.test.testprog1

This example specifies full debug trace for testprog1.

For more information on the use of system properties see your Java documentation.

Standard trace

This is the standard option for application tracing. By default, it displays only the first 128 bytes of any data blocks (for example the commarea, or network flows). This trace level is equivalent to the Gateway trace set by the ctgstart –trace option.

com.ibm.ctg.client.T call: T.setOn (true/false)

System property: gateway.T.trace=on

Full debug trace

This is the debugging option for application tracing. By default, it traces out the whole of any data blocks. The trace contains more information about the CICS® Transaction Gateway than the standard trace level. This trace level is equivalent to the Gateway debug trace set by the ctgstart –x option.

com.ibm.ctg.client.T call: T.setDebugOn (true/false)

System property: gateway.T=on

Exception stack trace

This is the exception stack option for application tracing. It traces most Java exceptions, including exceptions which are expected during typical operation of the CICS Transaction Gateway. No other tracing is written. This trace level is equivalent to the Gateway stack trace set by the ctgstart –stack option.

com.ibm.ctg.client.T call: T.setStackOn (true/false)

System property: gateway.T.stack=on

Additional options for configuring trace

You can also configure additional options for trace, including: output destination, data block size, dump offset, and whether or not to include timestamps. Use these options, in addition to one of the directives, to activate trace. For example, the following command activates standard trace, and also sets the maximum size of any data blocks to be dumped to 20 000 bytes: 
java -Dgateway.T.trace=on -Dgateway.T.setTruncationSize=20000

Output destination

  • com.ibm.ctg.client.T call: T.setTFile(true,filename)
  • System property: gateway.T.setTFile=filename
  • Usage: The value filename specifies a file location for writing of trace output. This is as an alternative to the default output on stderr. Long file names must be nested within quotation marks, for example: "trace output file.log".
  • Example: java -Dgateway.T.trace=on -Dgateway.T.setTFile="trace output file.log"

Data block size

  • com.ibm.ctg.client.T call: T.setTruncationSize(number)
  • System property: gateway.T.setTruncationSize=number
  • Usage: The value number specifies the maximum size of any data blocks that will be written in the trace. Any positive integer is valid. If you specify a value of 0, then no data blocks will be written in the trace. If a negative value is assigned to this option the exception java.lang.IllegalArgumentException will be raised.
  • Example: java -Dgateway.T.trace=on -Dgateway.T.setTruncationSize=20000

Dump offset

  • com.ibm.ctg.client.T call: T.setDumpOffset(number)
  • System property: gateway.T.setDumpOffset=number
  • Usage: The value number specifies the offset from which displays of any data blocks will start. If the offset is greater than the total length of data to be displayed, an offset of 0 will be used. If a negative value is assigned to this option the exception java.lang.IllegalArgumentException will be raised.
  • Example: java -Dgateway.T.trace=on -Dgateway.T.setDumpOffset=100

Display timestamps

  • com.ibm.ctg.client.T call: T.setTimingOn (true/false)
  • System property: gateway.T.timing=on
  • Specifies whether or not to display timestamps in the trace.
  • Example: java -Dgateway.T.trace=on -Dgateway.T.setTimingOn="true"