JANUS TRACE: Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (link repair)
 
(8 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{DISPLAYTITLE:JANUS TRACE}}
<span class="pageSubtitle">Set Janus TRACE level</span>
<span class="pageSubtitle"><section begin="desc" />Set Janus TRACE level<section end="desc" /></span>


This command sets or overrides the trace settings for the named Janus port(s), determining which, and how much, information is written to the Model 204 journal.  
This command sets or overrides the trace settings for the named Janus port(s), determining which, and how much, information is written to the Model 204 journal.  


You specify a bit mask integer setting that sums the values of the tracing options you want to invoke. The trace setting for a port is initially set to the value specified for the TRACE parameter on the JANUS DEFINE command for the port. The JANUS TRACE command will override this.
You specify a bit mask integer setting that sums the values of the tracing options you want to invoke. The trace setting for a port is initially set to the value specified for the <var>TRACE</var> parameter on the <var>JANUS DEFINE</var> command for the port. The <var>JANUS TRACE</var> command will override this.


==Syntax==
==Syntax==
<p class="syntax"><section begin="syntax" /> JANUS TRACE portname [ ipaddr | ipsubnet ] value | OFF
<p class="syntax">JANUS TRACE <span class="term">portname</span> [ <span class="term">ipaddr</span> | <span class="term">ipsubnet</span> ] <span class="term">value</span> | OFF
<section end="syntax" /></p>
</p>


===Syntax terms===
===Syntax terms===
 
<table>
<table class="syntaxTable">
<tr><th><i>portname</i></th>
<tr><th><i>portname</i></th>
<td>The name of the port(s) to modify.</td></tr>
<td>The name of the port(s) to modify.</td></tr>
<tr><th><i>ipaddr</i></th>
<tr><th><i>ipaddr</i></th>
<td>The remote IP address for which to set trace options. The IP address should be specified in standard ''dotted'' form: for example, 198.242.244.97. A host name cannot be specified on the JANUS TRACE command. If neither <var class="term">ipaddr</var> nor <var class="term">ipsubnet</var> is specified, the JANUS TRACE command is assumed to apply to all connections on the port.</td></tr>
<td>The remote IP address for which to set trace options. The IP address should be specified in either:
<ul>
<li>IPV4 standard 32-bit "dotted-decimal" form: for example, <code>198.242.244.97</code>. </li>
 
<li>IPV6 standard ([https://tools.ietf.org/html/rfc5952 RFC 5952]) 128-bit form: for example, <code>2011:0ab4:15a1::4a0e:0280:5274</code>
<p>
The IPV6 form is supported as of version 7.7 of Model&nbsp;204.</p></li>
</ul>
<p>
A host name cannot be specified on the <var>JANUS TRACE</var> command. </p>
<p>
If neither <var class="term">ipaddr</var> nor <var class="term">ipsubnet</var> is specified, the <var>JANUS TRACE</var> command is assumed to apply to all connections on the port.</p></td></tr>
 
<tr><th><i>ipsubnet</i></th>
<tr><th><i>ipsubnet</i></th>
<td>The IP subnet for which to set trace options. The IP subnet can be specified either in the standard ''dotted'' subnet and mask form, for example, 198.242.244.0/255.255.255.0, or a ''dotted'' IP address followed by the number of subnet bits, as in 198.242.244.0-24. All bits that are not part of the subnet '''must''' be 0. If neither <var class="term">ipaddr</var> nor <var class="term">ipsubnet</var> is specified, the JANUS TRACE command is assumed to apply to all connections on the port.</td></tr>
<td>The IP subnet for which to set trace options. The IP subnet can be specified either in the standard ''dotted'' subnet and mask form, for example, 198.242.244.0/255.255.255.0, or a ''dotted'' IP address followed by the number of subnet bits, as in 198.242.244.0-24. All bits that are not part of the subnet '''must''' be 0. If neither <var class="term">ipaddr</var> nor <var class="term">ipsubnet</var> is specified, the <var>JANUS TRACE</var> command is assumed to apply to all connections on the port.</td></tr>
 
<tr><th><i>value</i></th>
<tr><th><i>value</i></th>
<td>The bit-mask integer value to use for tracing the indicated connections.
<td>The bit-mask integer value to use for tracing the indicated connections. This controls the quantity of trace information logged to the audit trail. You specify an integer that sums the values of the options you want to have logged:
The TRACE setting controls the quantity of trace information logged to the audit trail. You specify an integer that sums the values of the options you want to have logged:


<table class="syntaxNested">
<table class="thJustBold">
<tr><th>1</th>
<tr><th>1</th>
<td>Log the SQL request on SDS or URL rules processing on WEBSERV ports. This bit is useful on WEBSERV ports if there is confusion about which JANUS WEB rules apply to a particular URL.</td></tr>
<td>Log the SQL request on SDS or URL rules processing on <var>WEBSERV</var> ports. This bit is useful on <var>WEBSERV</var> ports if there is confusion about which <var>JANUS WEB</var> rules apply to a particular URL.</td></tr>
 
<tr><th>2</th>
<tr><th>2</th>
<td>Log RPC requests on OPENSERV ports. Show request headers on WEBSERV ports.</td></tr>
<td>Log RPC requests on <var>OPENSERV</var> ports. Show request headers on <var>WEBSERV</var> ports.</td></tr>
 
<tr><th>4</th>
<tr><th>4</th>
<td>Log generated User Language (SDS ports only). Show form data on WEBSERV ports. This bit has no effect on OPENSERV ports. Using this bit on SDS ports can generate huge quantities of data so use it sparingly.</td></tr>
<td>Log generated <var class="product">User Language</var> (<var>SDS</var> ports only). Show form data on <var>WEBSERV</var> ports. This bit has no effect on <var>OPENSERV</var> ports. Using this bit on <var>SDS</var> ports can generate huge quantities of data so use it sparingly.</td></tr>
 
<tr><th>8</th>
<tr><th>8</th>
<td>Log in hex and char all activity on port (this allows TCP/IP level tracing).</td></tr>
<td>Log in hex and char all activity on port (this allows TCP/IP level tracing).</td></tr>
<tr><th>16</th>
<tr><th>16</th>
<td>Log Persistent Client State (cookies) on WEBSERV ports.</td></tr>
<td>Log Persistent Client State (cookies) on WEBSERV ports.</td></tr>
<tr><th>32</th>
<tr><th>32</th>
<td>Trace web response headers.</td></tr>
<td>Trace web response headers.</td></tr>
<tr><th>64</th>
<tr><th>64</th>
<td>Trace web response text.</td></tr>
<td>Trace web response text.</td></tr>
<tr><th>128</th>
<tr><th>128</th>
<td>Trace data between TCP and SSL.
<td>Trace data between TCP and SSL.
Line 43: Line 61:
</table>
</table>


The default for TRACE is 3 for SDS and OPENSERV ports, and it is 0 for WEBSERV ports and all others.  
The default for <var>TRACE</var> is 3 for <var>SDS</var> and <var>OPENSERV</var> ports, and it is 0 for <var>WEBSERV</var> ports and all others.  
</td></tr>
</td></tr>
<tr><th>OFF</th>
 
<td>Indicates that no TRACE override is to be used for the specified IP address or addresses.
<tr><th><var>OFF</var></th>
<td>Indicates that no <var>TRACE</var> override is to be used for the specified IP address or addresses.
</td></tr></table>
</td></tr></table>


==Usage notes==
==Usage notes==
<ul>
<li><var>JANUS TRACE</var> does not affect the <var>TRACE</var> setting on the port definition, although it may override it. If a <var>JANUS TRACE</var> override is subsequently turned off, any <var>JANUS DEFINE</var> <var>TRACE</var> setting for the port becomes in effect again. </li>


<ul>
<li><var>JANUS TRACE</var> may be issued while an online is running, and the order in which <var>JANUS TRACE</var> commands are specified is irrelevant. The <var>JANUS TRACE</var> command to be associated with a particular connection is the one that matches the IP address and has the most subnet bits.  
<li>JANUS TRACE does not affect the TRACE setting on the port definition, although it may override it. If a JANUS TRACE override is subsequently turned off, any JANUS DEFINE TRACE setting for the port becomes in effect again.
<li>JANUS TRACE may be issued while an online is running, and the order in which JANUS TRACE commands are specified is irrelevant. The JANUS TRACE command to be associated with a particular connection is the one that matches the IP address and has the most subnet bits.  


If a JANUS TRACE command exactly matches the IP address, it will always be used. If no IP address-specific rule is found, the subnet command with the most matching bits will be used. For example, a JANUS TRACE command for 198.242.244.96-27 will be used ahead of 198.242.244.0-24 for address 198.242.244.99, because the former subnet has 27 bits versus 24 for the second.  
If a <var>JANUS TRACE</var> command exactly matches the IP address, it will always be used. If no IP address-specific rule is found, the subnet command with the most matching bits will be used. For example, a <var>JANUS TRACE</var> command for 198.242.244.96-27 will be used ahead of 198.242.244.0-24 for address 198.242.244.99, because the former subnet has 27 bits versus 24 for the second.  


If two subnet-based JANUS TRACE commands with exactly the same number of subnet bits match an IP address, it is unpredictable which command will apply. Fortunately, this can only happen if at least one of the subnet masks has ''holes'' (interspersed 0 and 1 bits) in it. This type of subnet is non-standard and highly unusual.  
If two subnet-based <var>JANUS TRACE</var> commands with exactly the same number of subnet bits match an IP address, it is unpredictable which command will apply. Fortunately, this can only happen if at least one of the subnet masks has ''holes'' (interspersed 0 and 1 bits) in it. This type of subnet is non-standard and highly unusual.  


If no JANUS TRACE commands match the IP address for a connection, the trace setting for the port will be the setting of the TRACE parameter on the port definition.  
If no <var>JANUS TRACE</var> commands match the IP address for a connection, the trace setting for the port will be the setting of the <var>TRACE</var> parameter on the port definition.  
<li>In the following example, all connections for all ports starting with the character string <code>WEB</code> have tracing turned off, unless they match an IP address or subnet-specific JANUS TRACE command for the port to which they are connected:
<li>In the following example, all connections for all ports starting with the character string <code>WEB</code> have tracing turned off, unless they match an IP address or subnet-specific <var>JANUS TRACE</var> command for the port to which they are connected:


<p class="code"> JANUS TRACE WEB* 0
<p class="code">JANUS TRACE WEB* 0
</p>
</p>


In the following example, connections from IP address 193.147.133.167 to port WEB204 will use a trace value of 7:
In the following example, connections from IP address 193.147.133.167 to port <code>WEB204</code> will use a trace value of 7:


<p class="code"> JANUS TRACE WEB204 193.147.133.167 7
<p class="code">JANUS TRACE WEB204 193.147.133.167 7
</p>
</p>


In the following example, the special TRACE value for IP address 193.147.133.167 on port WEB204 is eliminated. Subsequent connections from this IP address will use the trace settings on the next most exactly matching JANUS TRACE command or, if there are none, the trace setting on the port definition.
In the following example, the special <var>TRACE</var> value for IP address 193.147.133.167 on port <code>WEB204</code> is eliminated. Subsequent connections from this IP address will use the trace settings on the next most exactly matching <var>JANUS TRACE</var> command or, if there are none, the trace setting on the port definition.


<p class="code"> JANUS TRACE WEB204 193.147.133.167 OFF
<p class="code">JANUS TRACE WEB204 193.147.133.167 OFF
</p>
</p>


In the following example, the general override of the trace setting for port <code>WEB204</code> is eliminated. The trace settings used for a connection that doesn't match any IP address or subnet-specific <var>JANUS TRACE</var> command will be the settings from the port definition.


 
<p class="code">JANUS TRACE WEB204 OFF
In the following example, the general override of the trace setting for port WEB204 is eliminated. The trace settings used for a connection that doesn't match any IP address or subnet-specific JANUS TRACE command will be the settings from the port definition.
 
<p class="code"> JANUS TRACE WEB204 OFF
</p>
</p>
</li>
</li>


<li>The TRACE setting controls the quantity of trace information logged to the audit trail. You specify an integer that sums the values of the options you want to have logged:
<li>Setting the 8 bit may result in huge quantities of data going to the audit trail; this trace option logs RK lines of the form:
 
<table class="syntaxTable">
<tr><th>1</th>
<td>Log the SQL request on SDS or URL rules processing on WEBSERV ports. This bit is useful on WEBSERV ports if there is confusion about which JANUS WEB rules apply to a particular URL.</td></tr>
<tr><th>2</th>
<td>Log RPC requests on OPENSERV ports. Show request headers on WEBSERV ports.</td></tr>
<tr><th>4</th>
<td>Log generated User Language (SDS ports only). Show form data on WEBSERV ports. This bit has no effect on OPENSERV ports. Using this bit on SDS ports can generate huge quantities of data so use it sparingly.</td></tr>
<tr><th>8</th>
<td>Log in hex and char all activity on port (this allows TCP/IP level tracing).</td></tr>
<tr><th>16</th>
<td>Log Persistent Client State (cookies) on WEBSERV ports.</td></tr>
<tr><th>32</th>
<td>Trace web response headers.</td></tr>
<tr><th>64</th>
<td>Trace web response text.</td></tr>
<tr><th>128</th>
<td>Trace data between TCP and SSL.
</td></tr>
</table>
 
The default for TRACE is 3 for SDS and OPENSERV ports, and it is 0 for WEBSERV ports and all others.


Setting the 8 bit may result in huge quantities of data going to the audit trail; this trace option logs RK lines of the form:
<p class="code">AP?: offxxx : xdxdxdxd ... | ccc...ccc |
 
<p class="code"> AP?: offxxx : xdxdxdxd ... | ccc...ccc |
</p>
</p>


where:
where:


<table class="syntaxTable">
<table>
<tr><th>?</th>
<tr><th><var>?</var></th>
<td>is <code>I</code> for input trace data, <code>O</code> for output, and <code>U</code> for urgent input data. For tracing <var class="product">[[Janus Sockets]]</var> or <var class="product">[[Debugger|Sirius Debugger]]</var> client connections (CLSOCK or DEBUGGERCLIENT ports), after the I/O/U indicator will be the user's socket number in parentheses. For example, if an application has used the $SOCK_CONN function once and that port is being traced, it is socket number two, so the trace of $SOCK_SEND values will start with ''APO(2)''.</td></tr>
<td><code>I</code> for input trace data, <code>O</code> for output, and <code>U</code> for urgent input data. For tracing <var class="product">[[Janus Sockets]]</var> or <var class="product">[[Debugger|TN3270 Debugger]]</var> client connections (<var>CLSOCK</var> or <var>DEBUGGERCLIENT</var> ports), after the <code>I</code>, <code>O</code>, or <code>U</code> indicator will be the user's socket number in parentheses. For example, if an application has used the <var>$Sock_Conn</var> function once and that port is being traced, it is socket number two, so the trace of <var>$Sock_Send</var> values will start with <code>APO(2)</code>.</td></tr>
 
<tr><th>offxxx</th>
<tr><th>offxxx</th>
<td>is the hex offset in the current stream.</td></tr>
<td>The hex offset in the current stream.</td></tr>
 
<tr><th>xdxdxdxd</th>
<tr><th>xdxdxdxd</th>
<td>is the hex representation of the data separated into 4 byte (8 digit) pieces.</td></tr>
<td>The hex representation of the data separated into 4 byte (8 digit) pieces.</td></tr>
 
<tr><th>cccc</th>
<tr><th>cccc</th>
<td>is the character representation of the data with non-printable characters changed to periods.
<td>The character representation of the data with non-printable characters changed to periods.
</td></tr></table>
</td></tr></table>
Both input and output are traced when the JANUS DEFINE for the port has <code>TRACE 8</code> specified.  
 
<li>The current JANUS TRACE command settings for any or all ports can be determined with the [[JANUS DISPLAYTRACE]] command.
Both input and output are traced when the <var>JANUS DEFINE</var> for the port has <code>TRACE 8</code> specified. </li>
 
<li>The current <var>JANUS TRACE</var> command settings for any or all ports can be determined with the <var>[[JANUS DISPLAYTRACE]]</var> command.</li>
</ul>
</ul>
<blockquote> The TRACE keyword was introduced in Version 6.0 of the ''[[Sirius Mods]]''. Before that, trace operations were controlled by the DEBUG keyword, which is no longer supported as of Version 6.5.</blockquote>


==See also==
==See also==

Latest revision as of 22:08, 14 September 2016

Set Janus TRACE level

This command sets or overrides the trace settings for the named Janus port(s), determining which, and how much, information is written to the Model 204 journal.

You specify a bit mask integer setting that sums the values of the tracing options you want to invoke. The trace setting for a port is initially set to the value specified for the TRACE parameter on the JANUS DEFINE command for the port. The JANUS TRACE command will override this.

Syntax

JANUS TRACE portname [ ipaddr | ipsubnet ] value | OFF

Syntax terms

portname The name of the port(s) to modify.
ipaddr The remote IP address for which to set trace options. The IP address should be specified in either:
  • IPV4 standard 32-bit "dotted-decimal" form: for example, 198.242.244.97.
  • IPV6 standard (RFC 5952) 128-bit form: for example, 2011:0ab4:15a1::4a0e:0280:5274

    The IPV6 form is supported as of version 7.7 of Model 204.

A host name cannot be specified on the JANUS TRACE command.

If neither ipaddr nor ipsubnet is specified, the JANUS TRACE command is assumed to apply to all connections on the port.

ipsubnet The IP subnet for which to set trace options. The IP subnet can be specified either in the standard dotted subnet and mask form, for example, 198.242.244.0/255.255.255.0, or a dotted IP address followed by the number of subnet bits, as in 198.242.244.0-24. All bits that are not part of the subnet must be 0. If neither ipaddr nor ipsubnet is specified, the JANUS TRACE command is assumed to apply to all connections on the port.
value The bit-mask integer value to use for tracing the indicated connections. This controls the quantity of trace information logged to the audit trail. You specify an integer that sums the values of the options you want to have logged:
1 Log the SQL request on SDS or URL rules processing on WEBSERV ports. This bit is useful on WEBSERV ports if there is confusion about which JANUS WEB rules apply to a particular URL.
2 Log RPC requests on OPENSERV ports. Show request headers on WEBSERV ports.
4 Log generated User Language (SDS ports only). Show form data on WEBSERV ports. This bit has no effect on OPENSERV ports. Using this bit on SDS ports can generate huge quantities of data so use it sparingly.
8 Log in hex and char all activity on port (this allows TCP/IP level tracing).
16 Log Persistent Client State (cookies) on WEBSERV ports.
32 Trace web response headers.
64 Trace web response text.
128 Trace data between TCP and SSL.

The default for TRACE is 3 for SDS and OPENSERV ports, and it is 0 for WEBSERV ports and all others.

OFF Indicates that no TRACE override is to be used for the specified IP address or addresses.

Usage notes

  • JANUS TRACE does not affect the TRACE setting on the port definition, although it may override it. If a JANUS TRACE override is subsequently turned off, any JANUS DEFINE TRACE setting for the port becomes in effect again.
  • JANUS TRACE may be issued while an online is running, and the order in which JANUS TRACE commands are specified is irrelevant. The JANUS TRACE command to be associated with a particular connection is the one that matches the IP address and has the most subnet bits. If a JANUS TRACE command exactly matches the IP address, it will always be used. If no IP address-specific rule is found, the subnet command with the most matching bits will be used. For example, a JANUS TRACE command for 198.242.244.96-27 will be used ahead of 198.242.244.0-24 for address 198.242.244.99, because the former subnet has 27 bits versus 24 for the second. If two subnet-based JANUS TRACE commands with exactly the same number of subnet bits match an IP address, it is unpredictable which command will apply. Fortunately, this can only happen if at least one of the subnet masks has holes (interspersed 0 and 1 bits) in it. This type of subnet is non-standard and highly unusual. If no JANUS TRACE commands match the IP address for a connection, the trace setting for the port will be the setting of the TRACE parameter on the port definition.
  • In the following example, all connections for all ports starting with the character string WEB have tracing turned off, unless they match an IP address or subnet-specific JANUS TRACE command for the port to which they are connected:

    JANUS TRACE WEB* 0

    In the following example, connections from IP address 193.147.133.167 to port WEB204 will use a trace value of 7:

    JANUS TRACE WEB204 193.147.133.167 7

    In the following example, the special TRACE value for IP address 193.147.133.167 on port WEB204 is eliminated. Subsequent connections from this IP address will use the trace settings on the next most exactly matching JANUS TRACE command or, if there are none, the trace setting on the port definition.

    JANUS TRACE WEB204 193.147.133.167 OFF

    In the following example, the general override of the trace setting for port WEB204 is eliminated. The trace settings used for a connection that doesn't match any IP address or subnet-specific JANUS TRACE command will be the settings from the port definition.

    JANUS TRACE WEB204 OFF

  • Setting the 8 bit may result in huge quantities of data going to the audit trail; this trace option logs RK lines of the form:

    AP?: offxxx : xdxdxdxd ... | ccc...ccc |

    where:

    ? I for input trace data, O for output, and U for urgent input data. For tracing Janus Sockets or TN3270 Debugger client connections (CLSOCK or DEBUGGERCLIENT ports), after the I, O, or U indicator will be the user's socket number in parentheses. For example, if an application has used the $Sock_Conn function once and that port is being traced, it is socket number two, so the trace of $Sock_Send values will start with APO(2).
    offxxx The hex offset in the current stream.
    xdxdxdxd The hex representation of the data separated into 4 byte (8 digit) pieces.
    cccc The character representation of the data with non-printable characters changed to periods.
    Both input and output are traced when the JANUS DEFINE for the port has TRACE 8 specified.
  • The current JANUS TRACE command settings for any or all ports can be determined with the JANUS DISPLAYTRACE command.

See also

Retrieved from "https://m204wiki.rocketsoftware.com/index.php?title=JANUS_TRACE&oldid=94083"