Runtime tracing in Visual LANSA

Date:11 July 2005
Product/Release:Visual LANSA
Abstract:How to enable tracing on a runtime application when requested by LANSA support
Submitted By:LANSA Technical Support
Updated:29 March 2017

LANSA provides the ability to trace a running Visual LANSA application. Under normal circumstances, enabling tracing will not be required. Enabling tracing will only be required when requested by LANSA support. There is no expectation that LANSA users will understand the trace output. The trace output is intended exclusively for use by the LANSA development team.

Trace Considerations:

  • Enabling tracing is a LANSA troubleshooting tool. It should not be enabled unless requested by a LANSA representative.
  • For versions of LANSA prior to V13, the trace output files will be named x_trace.nnn (where nnn is a number, for example, x_trace.001) and the output files will be located in the <root>:\x_win95\x_lansa folder, where <root> is where LANSA is installed. This is typically C:\Program Files (x86)\LANSA\X_WIN95\X_LANSA
  • For versions of LANSA post V13, the trace output files will be named x_tracennn.txt (where nnn is a number, for example, x_trace001.txt) and the output files will be located in the users TEMP folder. You can navigate to this location in Windows Explorer by typing %TEMP%
  • Enabling tracing will degrade application performance significantly
  • Tracing can be enabled on the x_run command, in a LANSA start file, as an environmental variable
  • In a client/server application (for example, a SuperServer application to a windows backend server), setting tracing on the client side will cause BOTH the client trace files and the server trace files to be generated.
  • Setting tracing on the server side will cause trace files to be generated on the server ONLY.

Trace Options:

ITRO=
This parameter specifies whether the application is to produce a trace file. Specify Y to produce a trace file or N to not produce a trace file.
Pre V13: Trace files are named X_TRACE.nnn. The highest nnn suffix indicates the newest trace file. The production of trace files severely impacts application performance.
Post V13: Trace files are named X_TRACEnnn.txt. The highest nnn suffix indicates the newest trace file. The production of trace files severely impacts application performance.

ITRL=
This parameter specifies the level of trace. Valid values are 0 to 9, where 0 provides the lowest level of detail and 9 the highest level of detail. This parameter does not need to be set unless requested by your Product Vendor.

ITRM=
This parameter specifies the maximum number of lines in the trace file. The maximum number is 999,999,999.

ITRC=
This parameter specifies the trace categories. It allows you to restrict the areas of LANSA that will generate trace messages. This should not be changed unless requested by your Product Vendor.

ITHP=
This parameter specifies the heap validation level. This should not be changed unless requested by your Product Vendor.

Turn tracing on and off by commands embedded within your application:

Sometimes tracing from the start of your application is problematic because so much trace data may be generated by your application before you get to the problem area.

From LANSA V11 it is possible to selectively turn tracing on and off by commands embedded within your application. This allows you to turn tracing on immediately before entering the problem area, thus drastically reducing the amount of trace data produced.

Here's some examples of how to dynamically manipulate tracing from within your application:

Checking if tracing is ON or OFF 

USE GET_SESSION_VALUE (ITRO) (#Trace #RetCode)
If (#Trace = Y)
<< tracing is currently on >>
Else
<< tracing is currently off >>
Endif

Turning Tracing ON or OFF

USE SET_SESSION_VALUE (ITRO N) << turns tracing off  >>
USE SET_SESSION_VALUE (ITRO Y) << turns tracing on  >>

Other Tracing Values can be also altered

For example:

USE SET_SESSION_VALUE (ITRL '2') 
USE SET_SESSION_VALUE (ITRC 'FUN')
USE SET_SESSION_VALUE (ITRM '999999999')