Tracing Instructions for IBM i Access Connectivity Problems

---

Communications errors like connection timeouts, disconnects, and slow data transfer speeds require tracing both ends of a connection to see a complete picture of the problem. Even with both traces it sometimes just shows that the problem is somewhere between the two endpoints. These traces we use are the IBM i Access Client Solutions Windows Application Package data stream trace or cwbcotrc, the connection trace (TRCCNN), and a communications trace. This document explains how to use each trace in separate sections; however, keep in mind that all of these traces are to be taken at one time for these types of problems. Therefore, use the information to start each trace. Then, re-create the problem, stop the traces, format the communications trace, and send the documentation to IBM support.


The CWBCOTRC

The IBM i Access Client Solutions Windows Application Package product includes a service tool (cwbcotrc.exe) that can capture some communications data like socket information and Windows socket return codes. A Wireshark or other packet capture trace (www.wireshark.org) can be captured when a complete picture of the client-side communications is required.

Before you start a cwbcotrc or any trace in a Windows environment, stop the application or service that is creating the connection. Then, start the traces and start the application or service again. When you trace a desktop application, it is sufficient to trace the current user only (the default behavior for cwbcotrc). When the connection is being initiated by a Windows service program like IIS or WebSphere use the /ALLUSERS option with cwbcotrc commands so that information is captured for all Windows users including system accounts. You might find that your cwbcotrc is empty or nearly empty when you finish. In that case, it is likely that the program that made the connection was started before the trace was started or that program runs as a Windows service and the /ALLUSERS option was not specified.

It is important to run the cwbcotrc commands from a Windows command prompt rather than another method such as the run dialog on the Windows start menu because the command displays status information as output. Without the feedback provided by that information, you cannot be certain that your command worked as you intended. The Windows command prompt is usually found in the Accessories program folder on the Start menu or it can be started by running the CMD command. It is also important to note that the cwbcotrc wraps its data. The /WRAP option can be used to control the maximum trace file size. The following commands are used to start the cwbcotrc. Note, the /ALLUSERS option can be omitted when you trace the connections from a desktop application.

CWBCOTRC OFF /ALLUSERS (ends the trace if it was still running)
CWBCOTRC DEL /ALLUSERS (deletes any existing trace file)
CWBCOTRC ON /ALLUSERS* (starts the trace)

* Note you can also specify a WRAP size by using the /WRAP: option

Once the error occurs, stop the trace from the command line again by using the following command.

CWBCOTRC OFF /ALLUSERS

Again, omit the /ALLUSERS option when you trace desktop applications. The on-screen information directs you to the location of the trace file.


The connection trace: TRCCNN

The connection trace is an IBM i system trace of TCP/IP information and is started and stopped from the operating system command line. The TRCCNN command can be set up to wrap the data in a trace table whose size is defined on the TRCCNN command. The default behavior is for the trace to wrap so it is not specified in the example. Start the TRCCNN by using the following command.

TRCCNN SET(*ON) TRCTYPE(*IP) SIZE(200000) TCPDTA(*TCP () () *N '1.2.3.4')

Where 1.2.3.4 is the IP address for the PC.

After the problem is re-created and captured in the traces, stop the connection trace from the same emulation session by running the command

TRCCNN SET(*OFF)

If you cannot start and stop the trace from the same emulation session (job), a trace table name must be specified rather than using the default value of *GEN. When *GEN is used for the trace table name, the command creates a trace table based on the name of the job that you start the trace from.

This trace produces the following spooled files: QSYSPRT and QPCSMPRT. The user data on the QSYSPRT file is TRCCNN. The QSYSPRT file is unformatted LIC trace data, and the QPCSMPRT trace is formatted.


The Communications Trace

The communications trace is perhaps the most difficult one to get because it captures trace buffer data from the actual adapter. The data can move through this buffer before it is ever logged in the trace, and that causes gaps in the trace. Another difficulty with the communications trace is that it traces only activity on one communications line. If the system is sending on one line and receiving on the other, this trace captures only half of the connection. In that event, it is not likely to be worth the effort required to get a communications trace. The communications trace is desirable when there is some corruption of data or the packet headers. In those cases, the frames simply do not appear in a TRCCNN; however, their presence in the communications trace can positively identify a network data corruption problem.

To start the communications trace, determine the name of the line description for the interface that the windows server is connecting to. To get that, use the TCP/IP configuration tools. From the operating system command line, run the following command:

CFGTCP

Select Option 1 to view the interfaces, and find the interface that the client is connecting to. The name of the corresponding line description is listed in the fourth column. To start the communications trace, run the following command:

STRCMNTRC CFGOBJ(YOURLINE) CFGTYPE(*LIN) MAXSTG(16M) USRDTA(*MAX) CMNTRCOPTS(*RMTIPADR) RMTIPADR('1.2.3.4')

Where:
YOURLINE is the actual line name
1.2.3.4 is the IP address for the PC

Once the error occurs, stop the communications trace by using the following command.

ENDCMNTRC CFGOBJ(YOURLINE) CFGTYPE(*LIN)

Where:
YOURLINE is the actual line name

This trace must be formatted and printed after it is stopped. Print this trace two different ways so that the eye-catcher information is available in EBCDIC and ASCII by running the following commands.

PRTCMNTRC CFGOBJ(YOURLINE) CFGTYPE(*LIN) CODE(*CALC) FMTTCP(*YES)
PRTCMNTRC CFGOBJ(YOURLINE) CFGTYPE(*LIN) CODE(*ASCII) FMTTCP(*YES)

Where:
YOURLINE is the actual line name

This command produces two spooled files named QPCSMPRT owned by the user that printed the trace.

Eventually, you must delete the trace information. Only one can exist per line description. However, do not delete the traces until you have confirmation that the trace provided to IBM is formatted correctly. The command to delete the trace data for the communications trace is:

DLTCMNTRC CFGOBJ(YOURLINE) CFGTYPE(*LIN)


Getting the Traces to IBM

The IBM i system trace tools create spooled files that must be provided to IBM support in a text file format (not PDF). The easiest way to do that is to use IBM i Access Client Solutions to copy the spooled files to the PC. In the main IBM i Access Client Solutions window, select your system and click 'Printer Output'.  If you do not see the spool files, press Ctrl+F to modify the filter so that you are viewing the spool files for the same user profile used to collect the traces.  Click the 'Date created' column heading two times so that the newest spool files are at the top of the list.  Select the spool files, right-click on the selection and click 'Download...'.  Specify the location to download the data to and clear the box titled, 'Use PDF format if available'. If these traces are large, compress them.  Follow the instructions in this document to associate the traces with your IBM support case:  MustGather: Instructions for Sending Data to IBM i Support

Note: If the IP address of the client system is not known, determine it by using the IPCONFIG command from a Windows command prompt on the client machine.