WebSphere® Application
Server for z/OS® provides support
for setting optimized local adapter trace levels to assist in application,
connection, or server diagnosis. You can set the trace level to three
levels to capture detailed, coarse, or no trace data. These are designated
as trace levels 2, 1, and 0.
Before you begin
Dynamic trace support in optimized local adapters provides
several ways to set or change existing trace levels without restarting
the server, including:
- Predefine server-wide tracing in properties files. This enables
you to have a set of tracing defined when the server is started so
that the optimized local adapter processing is immediately ready with
tracing enabled. You can use the WebSphere Application
Server for z/OS administrative
console and system modify SETOLATRACEPROPS command to designate the
properties file and make it active.
- Define the trace level. You can use the trace properties file
to specify both server-wide default trace levels and individual
trace levels for connections that are yet to be registered to the
optimized local adapter. The trace level can be set to 0, 1 or 2
for each entry in the properties file.
- Use the z/OS operator modify
SETOLATRACE command to set a specific trace level for existing registrations.
The command can also set the trace level for a registration name,
job name, or a specific Registration Entry control block (RGE) in
server controlled storage.
- Use an asterisk (*) symbol as a wildcard character in both the
trace properties file and the SETOLATRACE modify command to indicate
a setting for multiple groups of connections. The wildcard feature
can specify multiple registration names in the properties file or
the system default, and can set multiple registration names and job
names in the modify SETOLATRCE command.
- The developer of an application that uses optimized local adapters
can also set tracing for the life of the program connection when registration
is done by setting trace flags in the call to BBOA1REG.
Procedure
- Predefine trace levels. Predefining trace levels
readies you to capture registration and connection trace data as early
as optimized local adapter initialization. You are also prepared to
follow activity for connections that are not yet registered; when
the indicated registrations are made, tracing automatically occurs.
Predefine the trace levels as follows:
- Create a trace properties file in HFS. This
file should be in EBCDIC and accessible by the WebSphere Application Server for z/OS daemon.
The trace properties
file syntax follows the WebSphere Application
Server properties file syntax of <
keyword>=<
parameter>.
In this case, the property has a syntax as follows:
<registration_name>=<trace_level>
where:
<registration_name>
is an alphanumeric string
<trace_level> is 0, 1 or
2
For clarity, you can use single or double quotation style
syntax when indicating the registration name, for example:
MYREGNAME=1 "CICSREG"=2 'SHORTREG'=0
You
can also group like-named registrations into one line by using asterisks
as wildcard characters, for example:
REGNAME*=1 *NAME=2 "REG*NAME"=0
A
leading # character indicates the start of a comment, unless it is
within a quoted string.
Important: - Any non-valid trace level is treated as 0. For example, REGNAME=ALL
is treated as trace level 0.
- A registration name of "*" is treated as the default trace
level, for example, if *=1 is specified, the default for any new registrations
is a coarse level of tracing.
- The properties file can have a maximum of 1,024 trace specifications.
The SETOLATRACEPROPS command issues a response message
that displays how many trace definitions were processed for registrations
other than system default.
- Create an environment variable WAS_DAEMON_ONLY_ola_trace_settings_file
in the administrative console.
- Set the variable as a string to the fully qualified
path and file name of the trace properties file in HFS and activate
the variable.
If this environment variable is set and
saved in the WebSphere Application
Server configuration, the properties file is processed at server initialization.
You can update the trace properties file and activate the new definitions
by issuing the modify SETOLATRACEPROPS command and the new trace properties
affect new registrations. The syntax is:
F daemonname,SETOLATRACEPROPS
Attention: Activating a trace settings properties file deactivates
any currently active trace properties.
- Modify trace settings for existing connections. For
current connections that use optimized local adapters, you can turn
on or off tracing with the modify SETOLATRACE command. The command
has these forms:
F servername,SETOLATRACE=tracelevel,REGNAME=namestring
F servername,SETOLATRACE=tracelevel,JOBNAME=namestring
F servername,SETOLATRACE=tracelevel,RGE=hexaddress
The trace
level can be 0, 1, or 2 for, in order: no tracing, coarse level of
tracing, and detailed tracing.Namestring specifies the registration
name or job name for the existing registration to be modified. You
can delimit the namestring with matching single or double quotation
marks. Likewise, you can use an asterisk as a wildcard character to
modify more than one similarly named job or registration. A lone asterisk
affects every existing registration. You can turn off all tracing
of current registrations by using either of these commands:
F servername,SETOLATRACE=0,REGNAME=*
F servername,SETOLATRACE=0,JOBNAME=*
In cases where you
want to target a specific registration by the address of the RGE in
server controlled storage, you can use the RGE=hexaddress form of
the command. The hex address is an unquoted string of hexidecimal
numerals. This approach is probably one that the IBM® support team would direct you to use.
The
SETOLATRACE command displays a response message that indicates how
many registrations were affected.
- Specify trace settings at registration. You
can request tracing in code that calls the BBOA1REG API to create
the registration to the optimized local adapter. The interface to
BBOA1REG contains a parameter called registerflags.
The trace level settings for a registration can be modified by setting
one or more of the following values into the registerflags parameter:
reg_flag_trcmod EQU X'80000000' modify trace level
reg_flag_trcmore EQU X'40000000' trace level=2
reg_flag_trcsome EQU X'20000000' trace level=1
Set reg_flag_trcmod
if you want to modify the trace settings for the registration. If
you do not set this flag, no change to the trace setting is made,
and the system defaults or predefined trace settings that apply to
the registration name or job name are used.
Set either reg_flag_trcmore
or reg_flag_trcsome if you want detailed tracing or coarse level tracing.
Leaving both of them set to "off" forces no tracing no matter
what pre-definitions or defaults are set.