Diagnostics

Download Docs

e-docs > WebLogic Java Adapter for Mainframe > Programming Guide > Diagnostics

Programming Guide

Diagnostics

This section discusses the following topics:

Gateway Statistics

You can display the statistics for a Gateway definition using the WebLogic Administration Console. For instructions on accessing Gateway statistics, refer to the BEA WebLogic Java Adapter for Mainframe Configuration and Administration Guide. The statistics information displayed for the Gateway is listed in Table 7-1.

Table 7-1 Statistics Categories

Total Requests	The number of requests that have reached the gateway. This may be larger than the sum of successes and failures if some requests are still being processed.
Total Successes	The number of requests that have successfully been processed to completion by the gateway. Application level failures may be reported as gateway successes.
Average Response Time	The average response time for all successful requests and some failures. Failures that fail before they are transmitted over the network do not affect this statistic. Timeouts do not affect this statistic until a late reply is received.
Total Failures	The total number of failures of any kind.
No Response	The number of requests that have timed out and have never received a response of any kind.
Late Response	The number of requests that timed out and then received a response.
Other	The number of request that failed other than by timeout.

Gateway Tracing

WebLogic JAM runtime traces are sent to the WebLogic log as "Debug" messages. Debug messages are written to each WebLogic Server's log file but are not sent to the administration server. In addition, these messages are only sent to the server's stdout if the server's configuration has both the Log to Stdout and Debug to Stdout options selected on the server's Logging/General page.

For instructions on accessing Gateway tracing options, refer to the BEA WebLogic Java Adapter for Mainframe Configuration and Administration Guide. The user trace categories displayed for the Gateway are listed in Table 7-2.

Table 7-2 User Trace Categories

User level trace	Produces trace records for the beginning and completion of all user requests, both to and from the mainframe. The completion message will indicate the success or failure of the request.
User dump trace	Produces trace records with a hexadecimal dump of the user data associated with all user requests and replies. This trace level will also cause the trace records for User level trace to be produced.

Here is an example of a trace for two user requests:

<Nov 15, 2001 3:53:06 PM GMT-06:00> <Debug> <JAM1> <[5560199] Beginning of request:134217866 service:sampleCreate>

<Nov 15, 2001 3:53:06 PM GMT-06:00> <Debug> <JAM1> <[5560199] ---- request data dump ----

0000: 00 00 00 00 0f d3 81 a2 a3 61 f0 40 40 40 40 40   .....Last/0     
0010: 40 40 40 40 c6 89 99 a2 a3 61 f1 40 40 40 40 40       First/1     
0020: 40 40 40 d4 f3 f2 f0 f0 40 c1 95 a8 a2 a3 99 85      M3200 Anystre
0030: 85 a3 40 c3 96 a4 99 a3 40 40 40 40 40 40 40 40   et Court        
0040: 40 40 e3 e7 f7 f7 f5 f5 f5 f0 f0 f0 f0              TX775550000
------------------------------
>

<Nov 15, 2001 3:53:07 PM GMT-06:00> <Debug> <JAM1> <[5560199] End of request:134217866>

<Nov 15, 2001 3:53:07 PM GMT-06:00> <Debug> <JAM1> <[5560199] ---- response data dump ----

0000: 00 00 00 00 0f d3 81 a2 a3 61 f0 40 40 40 40 40   .....Last/0     
0010: 40 40 40 40 c6 89 99 a2 a3 61 f1 40 40 40 40 40       First/1     
0020: 40 40 40 d4 f3 f2 f0 f0 40 c1 95 a8 a2 a3 99 85      M3200 Anystre
0030: 85 a3 40 c3 96 a4 99 a3 40 40 40 40 40 40 40 40   et Court        
0040: 40 40 e3 e7 f7 f7 f5 f5 f5 f0 f0 f0 f0              TX775550000
------------------------------
>

<Nov 15, 2001 3:53:07 PM GMT-06:00> <Debug> <JAM1> <[5560199] Starting one phase commit>

<Nov 15, 2001 3:53:07 PM GMT-06:00> <Debug> <JAM1> <[5560199] Beginning of request:1207959692 service:sampleRead>

<Nov 15, 2001 3:53:07 PM GMT-06:00> <Debug> <JAM1> <[5560199] ---- request data dump ----

0000: 00 00 00 00 0f d3 81 a2 a3 61 f0 40 40 40 40 40   .....Last/0     
0010: 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40                   
0020: 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40                   
0030: 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40                   
0040: 40 40 40 40 40 40 40 40 40 40 40 40 40                         
------------------------------
>

<Nov 15, 2001 3:53:07 PM GMT-06:00> <Debug> <JAM1> <[5560199] End of request:1207959692>

<Nov 15, 2001 3:53:07 PM GMT-06:00> <Debug> <JAM1> <[5560199] ---- response data dump ----

0000: 00 00 00 00 0f d3 81 a2 a3 61 f0 40 40 40 40 40   .....Last/0     
0010: 40 40 40 40 c6 89 99 a2 a3 61 f1 40 40 40 40 40       First/1     
0020: 40 40 40 d4 f3 f2 f0 f0 40 c1 95 a8 a2 a3 99 85      M3200 Anystre
0030: 85 a3 40 c3 96 a4 99 a3 40 40 40 40 40 40 40 40   et Court        
0040: 40 40 e3 e7 f7 f7 f5 f5 f5 f0 f0 f0 f0              TX775550000
------------------------------
>

<Nov 15, 2001 3:53:07 PM GMT-06:00> <Debug> <JAM1> <[5560199] Starting one phase commit>

The trace categories listed in Table 7-3 are for use if you find it necessary to contact BEA Technical Support. They may be used to collect data about your system necessary to resolve problems.

Table 7-3 System Trace Categories

CRMAPI trace	Produces trace records showing the messages exchanged between the Gateway and the CRM.
JAM socket trace	Produces trace records showing a hexadecimal dump of the data exchanged between the Gateway and the CRM.
Configuration trace	Produces trace records showing operations within the WebLogic Administration Console and interactions between it and the Gateway.
Thread level trace	Produces trace records showing operations within the Gateway related to its internal threads and subtasks.

Low-Level Client Diagnostics

WebLogic JAM includes two low-level features to support diagnosing problems with eGen-based client programs. While these facilities are not designed for use in a production environment, they should be useful during development. These features are enabled by adding the settings listed in Table 7-4 to the java statement at the end of your startWebLogic.cmd file for the BEA WebLogic Server domain that you are currently running.

Table 7-4 Client Diagnostic Settings

bea.jam.client.loopback	Set to "true" to bypass the gateway & simply loop the request bytes back to the client.
bea.jam.client.stub	Set to the full name of a class to be used as a gateway stub.

Listing 7-1 provides an example in bold of the changes that need to be made to the java statement in the startWebLogic.cmd file necessary to enable the client diagnostic loopback feature. This file can be found in the <WLS_HOME>\config\<domain> directory. The java statement can be found near the end of the file.

Listing 7-1 startWebLogic.cmd Loopback Example

				...
"%JAVA_HOME%\bin\java" -hotspot -ms64m -mx64m -classpath %CLASSPATH% -Dweblogic.Domain=mydomain -Dbea.jam.client.loopback=true -Dweblogic.Name=myserver "-Dbea.home=g:\bea" "-Djava.security.policy==%WL_HOME/server/lib/weblogic.policy" -Dweblogic.management.password=%WLS_PW% weblogic.Server
				...

Client Loopback

If the client loopback feature is enabled, all requests receive a response that is exactly equal to the request data. Note that this loopback response is accomplished while the data is in mainframe format. If a service accepts one DataView subclass and returns a different one, a conversion failure in trying to construct the resulting DataView subclass may occur.

Note: When the client loopback feature is enabled, a Gateway need not be deployed.

Client Stub Operation

The client stub operation enables you to replace the gateway with your own class, in effect providing a replacement for the entire target mainframe. This feature is valuable for testing or proof-of-concept situations where the mainframe connection is not available.

Your stub class must:

Provide a constructor that takes no arguments.
Be available on your CLASSPATH.
Contain a method for each service that is to be supported. This method must take some DataView subclass as its only argument and return a DataView subclass.

CRM Tracing

The CRM has tracing options that can be enabled for advanced debugging of WebLogic JAM applications. Refer to the BEA WebLogic Java Adapter for Mainframe Configuration and Administration Guide for information about setting trace levels.

On Windows NT and Unix systems, traces are written to a file in the directory in which the CRM was started. If the environment variable APPDIR is set, the trace will be written to the directory it specifies. The file name will be specified as:

CRM.<pid>.trace.<seq>

Where <pid> is the process ID of the CRM process, and <seq> is the sequence number of the trace file, which is always 0.

On MVS systems, traces are written to SYSOUT, which is identified by TRACE DD NAME.

Viewing Trace Output

With a few exceptions, each line in the trace output is preceded by a time tag, identifying the date and time the line was written.

Note: The time tag information in the CRM trace should reflect the current system time. In order to make use of the correct time zone information on Unix and MVS systems, it is important that the TZ environment variable be set correctly. If this variable is not set correctly on your system, refer to your system documentation for further information.

After the time tag, a four-digit number appears, identifying the number of the task that wrote the line to the trace. This number can be useful when multiple processes are connected to the CRM.

If the trace level of the CRM is greater than one, a plus sign (+) following the task number indicates that a line in the trace is level 1 output. For example, in the sequence:

Tue Oct 09 10:45:10.291 0001 +CRM initialization complete -- Normal dispatching begins

Tue Oct 09 10:45:10.291 0001  CRM state transition from InitializationInProgress to Reset

The line CRM initialization complete is level 1 output, and the line CRM state transition is not (it is level 3 output).

When the trace level is set to 3, hex dump information will appear in the trace. These entries will appear interspersed with other trace statements. An example follows:

OFFS  ----------------- HEXADECIMAL------------------  *------ASCII-----*
0000: 00 00 00 B2 63 00 00 56 BE AC 05 00 00 04 00 02  (....c..V........)
0010: 00 00 00 00 00 00 00 1C 7E 71 00 00 00 00 00 96  (.........q......)
0020: 7E 76 00 00 41 30 36 52 65 67 69 6F 6E 00 00 00  (.v..A06Region...)
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  (................)
0040: 00 00 00 00 01 57 45 42 4C 00 43 49 43 53 00 53  (.....WEBL.CICS.S)
0050: 4E 41 43 52 4D 00 00 00 00 00 00 00 00 00 00 00  (NACRM...........)
0060: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 41 30  (..............A0)
0070: 36 43 49 43 53 00 00 00 00 00 00 00 00 00 00 00  (6CICS...........)
0080: 00 00 00 00 00 00 00 00 00 00 00 00 00 41 30 36  (.............A06)
0090: 43 49 43 53 00 00 53 4D 53 4E 41 31 30 30 00 4C  (CICS..SMSNA100.L)
00A0: 4F 43 41 4C 00 00 00 00 00 00 02 00 00 04 00 02  (OCAL............)
00B0: EA 60                                            (..)

These entries consist of offset information in the left column, followed by columns with the data in hexadecimal format, followed by an ASCII or EBCDIC representation of the data. The data is read from left to right, top to bottom.

Hex dump information for application data appears in a slightly different format, with two different representations of the user data. An example follows:

00000 |12345678 9fe29489 a3884040 40404040| |.....Smith      |
00010 |40404040 d1968895 40404040 40404040| |    John        |
00020 |404040d8 f1f2f3f4 40c59394 40e2a34b| |   Q1234 Elm St.|
00030 |40404040 40404040 40404040 40404040| |                |
00040 |4040e3d5 f1f2f3f4 f5404040 40000000| |  TN12345    ...|

The two columns following the hex data contain the user data in "actual" and "native" representations. In the "actual" representation, the binary data is represented directly as character data, with unprintable characters appearing as a period (.). In the "native" representation, the binary data is converted to the native character format (EBCDIC or ASCII), allowing text fields to be viewed directly.

Note: The above example was taken from a CRM trace from an EBCDIC machine, so the "actual" and "native" columns both contain readable text.

APPC API Tracing

The BEA support team might request an APPC API trace for diagnosis of a customer problem. The mapping of the APPC API trace is BEA internal.

The VTAM APPC API may be captured by enabling the APPC API tracing. The API trace shows the parameters and values passed and returned to the VTAM APPC stack. The API trace is captured to the GTF tracing facility. The GTF tracing facility must be active in the mainframe region to capture the API traces.

After capturing the traces, you must format the print using GTF formatting procedures such as IPCS. The APPC API trace is written to GTF as user id '2EA'. You may use this ID to filter the GTF print to include only the APPC API traces.

Refer to the BEA WebLogic Java Adapter for Mainframe Configuration and Administration Guide for information about setting APPC tracing.

Viewing APPC Trace Output

The APPC API trace captures the parameters and values used by the CRM to make a VTAM APPC request. The trace will show the APPC verb control block before and after the request is made. The response to the request will show return codes and returned values.

The following example of a request and a response was formatted by using the IBM provided program IKJEFT01.