Appendix A. Runtime properties files

Runtime settings, such as log, trace, and license settings are stored in one of two different files:

The runtime.properties file is used by HATS in the runtime environment and in the local test environment running in Run on Server mode (for Web applications) or Run mode (for rich client applications).
The runtime-debug.properties file is used by HATS in the local test environment in Debug on Server mode (for Web applications) or Debug mode (for rich client applications).

For more information about how to administer runtime settings for Web applications, see Administering problem determination components. For more information about how to administer runtime settings for rich client applications, see Administering HATS rich client applications.

The runtime.properties and runtime-debug.properties files contain the following properties.

adminPortNum

The adminPortNum is the default value used by the HATS administrative console when the management scope is to be changed. The port value must be an active WebSphere® BOOTSTRAP_ADDRESS port. The default is 2809, which is the default BOOTSTRAP_ADDRESS port of server1 for a WebSphere base installation, or of the nodeagent server when you federate an application server node into a deployment manager cell.

ioPatternKey Web-only

One or more patterns specifying the Integration Objects to be traced. See the description of trace.INTEGRATIONOBJECT below.

Each pattern can contain one or more wildcard (*) character. For example, IntegrationObject.Callup* specifies that tracing is enabled for all Integration Objects that start with the letters Callup. To trace all Integration Objects, specify IntegrationObject.*

If multiple patterns are specified, they should be delimited with commas.

numLicenses

Specifies the number of licenses you purchased. HATS tracks the number of HATS connections to host resources and logs a message when the value exceeds the number of licenses purchased.

The value is an integer. There is no default. Valid values for Authorized User licenses are 1 - 50000. For Value Unit licenses, the value must be -1.

licenseHardLimit

An encrypted field containing HATS licensing entitlement. Do not manually alter this field.

licenseTracking

Specifies whether HATS records license usage or not. The value is binary. The default is 0.

0

HATS does not record license usage.

1

HATS records license usage for all application servers in a node. HATS tracks the number of HATS connections to host or database resources and logs a message when the value exceeds the number of licenses purchased. The license usage information is written to a file named licensex.txt in the log directory of the HATS installation directory on the server, where the x is either 1 or 2.

The maximum size of the license usage files is 512 KB. When the file size of the license1.txt file reaches 512 KB or if the HATS server is restarted, the file is renamed to license2.txt, and a new license1.txt file is created. The new license1.txt file contains the most recent license usage information. When the new license1.txt reaches 512 KB and is renamed, the old license2.txt is deleted.

The license usage files contain the following information, arranged in rows, with each row representing one hour of operation. The values are separated by a space ( ).

Date
Time
The highest license count since the server was started
The highest license count in the last hour (the maximum of the last 60 entries)
The license count for each minute (1-60)

licenseFile

The name used as a template to generate names for the license files for license usage information. The default value for this property is license.txt.

logFile

The name used as a template to generate names for each set of application server files to which log messages are written. The default base name for a log file is messages.txt.

logMask

Certain macro errors cause an image of a host screen (screen dump) to be placed into the HATS log files.

Screen dumps are classified as INFO messages. To control which types of messages are placed in the HATS log, use this setting. For example, if you do not wish to have screens appear in the HATS log due to security concerns, set logMask=6 to prevent INFO messages (including screen dumps) from being placed in the log.

You cannot shut off ERROR messages with the logMask setting.

4: Log ERROR messages
5: Log ERROR and INFO messages
6: Log ERROR and WARNING messages
7: Log ERROR and WARNING and INFO messages

maxLogFiles

The maximum number of message files. The default is 2.

The base log file name in runtime.properties is used as a template to generate unique sets of message log files for each application server. The default base name for a log file can be changed in runtime.properties. The application server running HATS is the concatenation of: the underscore (_) character, followed by the name of the HATS instance, followed by another underscore (_) character.

The HATS instance ID (for example _SSS_) is then appended to the base file name to generate the template for the log files for an application server. For the log file, this becomes messages _SSS_.txt. Finally, an index (1, 2, 3, and so on) is added to this name to distinguish multiple files. So, for example, if the HATS instance ID is cell_node_server, the log file for the application server is named messages_cell_node_server_.txt. With multiple log files configured, the log file names for this application server are messages_cell_node_server_1.txt, messages_cell_node_server_2.txt, and so on.

When messages_cell_node_server_1.txt reaches maxLogFileSize, it is closed and renamed to messages_cell_node_server_2.txt. A new messages_cell_node_server_1.txt is opened.

When messages_cell_node_server_1.txt reaches maxLogFileSize again, previous log files are renamed--for example, messages_cell_node_server_2.txt is renamed to messages_cell_node_server_3.txt. Then messages_cell_node_server_1.txt is renamed to messages_cell_node_server_2.txt, and a new messages_cell_node_server_1.txt file is opened.

When the maxLogFiles number is exceeded, the oldest file is deleted.

Note:

When running on WebSphere Application Server for z/OS®, the server portion of the log file name also includes the Address Space ID of the Servant which is writing to the log (example: messages_asid_1.txt). See Log and trace file names for details.

maxLogFileSize

Specifies the maximum size, in kilobytes, that a message log file reaches before an additional log file is opened.

The value is an integer. The default is 512 KB.

traceFile

The name used as a template to generate file names to which HATS trace messages are written. The default base name for a trace file is trace.txt.

maxTraceFiles

The maximum number of trace information files. The default is 5.

The base trace file name in server.properties is used as a template to generate unique sets of trace files for each application server. The default base name for a trace file can be changed in runtime.properties. The application server running HATS is the concatenation of: the underscore (_) character, followed by the name of the HATS server instance, followed by another underscore (_) character.

The HATS server instance ID (for example _SSS_) is then appended to the base file name to generate the template for the trace files for an application server, which becomes trace _SSS_.txt. Finally, an index (1, 2, 3, and so on) is added to this name to distinguish multiple trace files. So, for example, if the HATS server instance ID is cell_node_server, the trace file for the application server is named trace_cell_node_server_.txt. With multiple trace files configured, the trace file names for this application server are trace_cell_node_server_1.txt, trace_cell_node_server_2.txt, and so on.

When trace_cell_node_server_1.txt reaches maxTraceFileSize, it is closed and renamed to trace_cell_node_server_2.txt. A new trace_cell_node_server_1.txt is opened.

When trace_cell_node_server_1.txt reaches maxTraceFileSize again, previous trace files are renamed--for example, trace_cell_node_server_2.txt is renamed to trace_cell_node_server_3.txt. Then trace_cell_node_server_1.txt is renamed to trace_cell_node_server_2.txt, and a new trace_cell_node_server_1.txt file is opened.

When the maxTraceFiles number is exceeded, the oldest file is deleted.

Note:

When running on WebSphere Application Server for z/OS, the server portion of the trace file name also includes the Address Space ID of the Servant which is writing to the log (example: trace_asid_1.txt). See Log and trace file names for details.

maxTraceFileSize

Specifies the maximum size, in kilobytes, that a trace file reaches before an additional trace file is opened.

The value is an integer. The default is 10240 KB.

traceLogDirectory

Sets the directory to be used for writing log and trace output when the application EAR is deployed. If this keyword is not specified, or the value specified is not valid, the directory used is logs, and it placed under the EAR's installed directory. This value is only used when the EAR is deployed to an application server. It has no effect within the Toolkit environment.

maxHODThreadManagerThreads

Specifies the maximum number of threads that can be created in the Host On-Demand ThreadManager thread pool. You can specify a value between 10 and 10000. If you specify a value outside of this range, the setting is ignored and the default Host On-Demand value of 10000 is used.

Tracing options

The tracelevel values used by the tracing options described in this section represent a hexadecimal digit string. Each bit of the digit string controls one type of tracing for the runtime. The defaults are:

tracelevel.1 : 0000000000020000
tracelevel.2 : 000000000000020f
tracelevel.3 : 000000000004023f  (minimum)
tracelevel.4 : 0000000000041a3f
tracelevel.5 : 00000000000c1bbf  (normal)
tracelevel.6 : 00000000000c1bbf
tracelevel.7 : 00000000001c1bbf  (maximum)
tracelevel.8 : 00000000001c1bbf
tracelevel.9 : 00000000001c1bbf

Following are the definitions of each bit in the trace mask:

x000001  - Informational messages
x000002  - Warning messages
x000004  - Error messages
x000008  - Critical error messages
x000010  - API traces
x000020  - Callback API traces
x000080  - Method entry
x000100  - Method exit
x000200  - Exceptions
x000400  - Miscellaneous traces
x000800  - Object creation
x001000  - Object disposal
x020000  - performance tracing - use this value alone
x040000  - Miscellaneous data - level 1
x080000  - Miscellaneous data - level 2
x100000  - Miscellaneous data - level 3

To customize the tracelevel values, add together the hexadecimal values in the trace mask. For example, if you specify tracelevel.9=180 and then use trace.RUNTIME=9 , only method entry and method exit runtime traces are performed.

trace.RUNTIME

Specifies the level of tracing for the main runtime and for all settings under RUNTIME.* that do not specify a trace level.

The value is an integer from 0-9. The default is 0, which means that no runtime tracing is performed.

trace.RUNTIME.ACTION

Specifies the level of tracing for the event actions. This setting overrides the trace.RUNTIME setting.

The value is an integer from 0-9. The default is 0, which means that no event action tracing is performed.

trace.TRANSFORM

Specifies the level of tracing for HATS transformations and for all settings under TRANSFORM.* that do not specify a trace level.

The value is an integer from 0-9. The default is 0, which means that no transformation tracing is performed.

trace.TRANSFORM.COMPONENT

Specifies the level of tracing for HATS components. This setting overrides the trace.TRANSFORM setting.

The value is an integer from 0-9. The default is 0, which means that no component tracing is performed.

trace.TRANSFORM.WIDGET

Specifies the level of tracing for HATS widgets. This setting overrides the trace.TRANSFORM setting.

The value is an integer from 0-9. The default is 0, which means that no widget tracing is performed.

trace.INTEGRATIONOBJECT Web-only

Specifies the level of tracing for Integration Objects.

The value is an integer from 0-9. The default is 0, which means that no Integration Object tracing is performed.

trace.UTIL

Specifies the level of tracing for HATS runtime utilities.

The value is an integer from 0-9. The default is 0, which means that no runtime utility tracing is performed.

trace.APPLET Web-only

Specifies the level of tracing for the applet.

The value is an integer, where

0: No tracing is performed.
3: Minimum level of tracing is performed.
5: Normal tracing is performed.

The default is 0.

Host On-Demand tracing

trace.HOD.COMMEVENT

Specifies the level of tracing for the Host On-Demand COMM events.

0: Host On-Demand COMM event tracing is not enabled.
1: Host On-Demand COMM event tracing is enabled.

The value is binary. The default is 0.

trace.HOD.DISPLAYTERMINAL

Specifies whether Host On-Demand displays a terminal window for each connection.

0: Host On-Demand does not display a terminal window for each connection.
1: Host On-Demand displays a terminal window for each connection.

The value is binary. The default is 0.

If trace.HOD.DISPLAYTERMINAL is 1, when HATS creates a host connection (for example, in response to a request from an application), it automatically creates a host terminal display. If this property is set to 0, this does not occur; however, regardless of whether the host terminal display is created automatically during host connection creation, a HATS administrator can use HATS administrative console to turn host terminal displays on or off for individual host connections.

trace.HOD.DS

Specifies the level of tracing for the Host On-Demand data stream tracing.

The value is an integer in the range 0 to 3, where

0: No tracing is performed.
1: Minimum level of tracing is performed.
2: Normal tracing is performed.
3: Maximum level of tracing is performed.

The default is 0.

trace.HOD.MACRO

Specifies the level of tracing for Host On-Demand macros.

The value is an integer in the range 0 to 2, where

0: Host On-Demand macro tracing is not enabled.
1: Host On-Demand event tracing is enabled.
2: Host On-Demand support tracing is enabled.

The default is 0.

trace.HOD.PS

Specifies the level of tracing for the Host On-Demand presentation space.

The value is an integer in the range 0 to 3, where:

0: No tracing is performed.
1: Minimum level of tracing is performed.
2: Normal tracing is performed.
3: Maximum level of tracing is performed.

The default is 0.

trace.HOD.PSEVENT

Specifies the level of tracing for the Host On-Demand PS events.

0: Host On-Demand PS event tracing is not enabled.
1: Host On-Demand PS event tracing is enabled.

The value is binary. The default is 0.

trace.HOD.OIAEVENT

Specifies the level of tracing for the Host On-Demand OIA events.

0: Host On-Demand OIA event tracing is not enabled.
1: Host On-Demand OIA event tracing is enabled.

The value is binary. The default is 0.

trace.HOD.SESSION

Specifies the level of tracing for Host On-Demand sessions.

The value is an integer in the range 0 to 3, where

0: No tracing is performed.
1: Minimum level of tracing is performed.
2: Normal tracing is performed.
3: Maximum level of tracing is performed.

The default is 0.

trace.HOD.TRANSPORT

Specifies the level of tracing for the Host On-Demand transport.

The value is an integer in the range 0 to 3, where

0: No tracing is performed.
1: Minimum level of tracing is performed.
2: Normal tracing is performed.
3: Maximum level of tracing is performed.

The default is 0.

trace.HOD.USERMACRO

Specifies the level of tracing for trace actions in Host On-Demand user macros.

The value is an integer in the range 0 to 3, where

0: No tracing is performed.
1: Minimum level of tracing is performed.
2: Normal tracing is performed.
3: Maximum level of tracing is performed.

The default is 0.

Host simulation tracing

recordSimulationTrace

Specifies whether host simulation trace recording is enabled at runtime.

0: Host simulation trace recording is not enabled.
1: Host simulation trace recording is enabled.

The value is binary. The default is 0.

startPort

Specifies the starting port of the range of ports to use during runtime to perform host simulation trace recording for multiple host sessions concurrently. The default is port 7021.

endPort

Specifies the ending port of the range of ports to use during runtime to perform host simulation trace recording for multiple host sessions concurrently. The default is port 7050.