Use tracing on optimized local adapters

(zos)
Use tracing on optimized local adapters

WebSphere Application Server for z/OS provides support for setting optimized local adapter trace levels to assist in application, connection, or server diagnosis. We 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.

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. We can use the WAS for z/OS console and system modify SETOLATRACEPROPS command to designate the properties file and make it active.

Define the trace level. We 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.
Predefine trace levels. Predefining trace levels readies you to capture registration and connection trace data as early as optimized local adapter initialization. We 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 WAS for z/OS daemon.
The trace properties file syntax follows the WAS 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, we can use single or double quotation style syntax when indicating the registration name, for example:
MYREGNAME=1 "CICSREG"=2 'SHORTREG'=0
We 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 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 WAS configuration, the properties file is processed at server initialization. We 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

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, we 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. We can delimit the namestring with matching single or double quotation marks. Likewise, we 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. We 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 to target a specific registration by the address of the RGE in server controlled storage, we 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. We 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 to modify the trace settings for the registration. If we 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 we 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.