[z/OS]

Using 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. 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.

About this task

Procedure

  1. 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:
    1. 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.
    2. Create an environment variable WAS_DAEMON_ONLY_ola_trace_settings_file in the administrative console.
    3. 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.
  2. 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.

  3. 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 word of registration flags. Three have been defined for trace level setting; they are bits 0 - 2 as follows:
    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.




In this information ...


IBM Redbooks, demos, education, and more

(Index)

Use IBM Suggests to retrieve related content from ibm.com and beyond, identified for your convenience.

This feature requires Internet access.

Task topic Task topic    

Terms and conditions for information centers | Feedback

Last updatedLast updated: Feb 6, 2014 8:11:25 PM CST
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=matt&product=was-nd-mp&topic=tdat_usetraceinfoola.dita
File name: tdat_usetraceinfoola.html