The {{Trace}} Tag

Enables or disables trace logging for the current session.

Trace ( options )

The options in the table below control the internal accumulation of trace information on UNIX. Windows always accumulates trace information and these options are ignored.

START START causes BIS to begin accumulating trace output. If tracing has been started, START has no effect.
STOP STOP causes BIS to stop accumulating trace output. If tracing has not been started, STOP has no effect.
OFF Turns tracing off. Equivalent to STOP,NOPAGE,NOFILE,NOTAG,NOEXCHFILES,NOQUERYPARAM,NOIP.

The options in the table below determine where the TRACE output is emitted. They are independent of each other. The underlined options are the defaults.

PAGE Indicates that the trace is emitted at the end of the page.
NOPAGE Disables end of page trace output.
FILE Indicates that the trace is written to a file in directory indicated by the DIR option.
NOFILE Disables trace output to the file.
TAG Enables the TraceDump tag and allows it to write trace output is written when it is rendered.
NOTAG Causes TraceDump tags to be ignored.
EXCHFILES Enable saving a copy of the XML Exchange request/response files for each session in the trace directory.
NOEXCHFILES Disables the tracing of XML Exchange request/response files.

If the FILE option is in effect, these options determine how the TRACE output is written to a file.

DIR=dir dir specifies the directory that will receive trace output if FILE is in effect. If no dir is specified, this option has the same effect as NODIR. If a relative directory is specified for dir , output is written into a directory relative (on BIS/IIS) to the Windows temporary directory or (on BIS/Apache) to the /tmp directory. If an absolute path is specified for dir , output is written into that directory. On BIS/IIS, this directory must exist or the trace file will not be written. On BIS/Apache, the specified directory will be created if it does not exist.
NODIR Disables the trace directory specified by DIR. If file output is enabled with either FILE or EXCHFILES then all trace output is written (on BIS/IIS) into the Windows temporary directory, or (on BIS/Apache) into /tmp.

The options below allow tracing to be controlled using a query parameter or a cookie:

QUERYPARAM=value

QP=value

QUERYPARAM and QP are synonymous and designate a URL query parameter whose value can be used to dynamically specify the options above. See the section The Trace Query Parameter for more information. Since the ability to dynamically configure the trace system is a potential security issue, the QUERYPARAM option allows you to specify your own query parameter name, rather than BIS supplying a standard one. This will make it harder for an unscrupulous person to obtain control of the tracing, but not impossible, so it is strongly suggested that the QUERYPARAM option not be left in the Trace tag of stencils files in production systems.
NOQUERYPARAM

NOQP

Disable the query parameter set by QUERYPARAM or QP.
IP=xx.xx.xx.xx [-x.xx.xx.xx]

IP=ipv6addr [- ipv6addr ]

BISFE005-low.gif

IP allows trace output to be restricted to requests originating at one or more IP addresses. If an IP restriction is in effect, trace output is restricted exclusively to requests from those particular IP addresses. A comma-separated list of IP addresses or ranges may be specified. The list of IP restrictors is processed from left to right.

Note that specifying 127.0.0.1 will allow access from a web browser running on the host's console. In this case, access the pages using localhost as the name of the host.

On BIS/IIS, IPv6 addresses may be specified instead of IPv4. For example, ::1 specifies the IPv6 loopback address, and on Windows Vista and Windows 2008 server, localhost resolves to this IPv6 address, while on older versions of Windows, localhost resolves to 127.0.0.1. IPv6 and IPv4 addresses may be mixed in a single IP statement, but not in a single range.

For portability between Apache and IIS, if either an IPv4 or IPv6 loopback address is specified (that is, 127.*.*.* or ::1), the setting applies to both IPv4 and IPv6 loopback addresses.

NOIP Disables the restriction of IP addresses.