Performing a Trace in EXTRA! X-treme
Technical Note 2249
Last Reviewed 01-Mar-2012
Applies To
EXTRA! X-treme version 9.0 or higher
Summary

When troubleshooting a problem in EXTRA! X-treme, you may need to obtain one or more traces. This technical note describes how to generate an API trace, communications trace, secure connection socket trace, or AOMDemon trace.

This technical note contains the following sections:

API Trace

If you have an application that makes API calls to EXTRA!, such as using HLLAPI, and your application is not working properly, you can capture the API calls and return codes for debugging purposes. (For API code examples and test code, see Technical Note 2164.)

  1. Close your API application(s).
  2. Launch the Status application from the Start menu (click Attachmate EXTRA! X-treme > Status App).
  3. Click the API Trace tab.
  4. Click Options > Settings. In the API Trace Options dialog, enable the API(s) your application uses, such as IBM EHLLAPI, and click OK.

Note: API Trace does not support COM (OLE Automation) calls.

  1. Click the Record (triangle) toolbar button.
  2. Run your application that makes the API calls.

Note: For HLLAPI, you must already have HLLAPI short name(s) assigned to .edp session(s) in EXTRA! X-treme (Options > Global Preferences > Advanced).

The Status application displays the API activity (date, time, API type, and function name) with separate rows for the call and return. When a row is double-clicked, the Details pane displays parameter names, data types, and values.

  1. After the problem has been reproduced, go back to the Status application. Click the Stop (square) toolbar button.
  2. Save the trace file (with .log extension). You can later re-open the trace file in the Status application to view it again, or provide the trace file to Technical Support if necessary.

Note: The trace file is stored in binary format, so cannot be viewed in a text editor.

To provide the file to Technical Support, either attach the file to your service request (see Technical Note 2327) or use http://upload.attachmate.com/.

Communications Trace

Note: EXTRA! 9.0 Service Pack 1 – 9.2 VT Telnet and VT SSH sessions cannot use this communications trace because the trace does not capture the appropriate data. To trace VT Telnet and VT SSH sessions, use a third-party utility, or for SSH sessions, follow the instructions in one of the following sections: Secure Connection Socket Trace – SSH Connection Issues Only or Secure Connection Socket Trace – All SSH Issues.

To capture a communications trace, follow these steps:

  1. Close EXTRA! X-treme if it is running.
  2. Launch the Status application from the Start menu (click Attachmate EXTRA! X-treme > Status App).
  3. Click the Communications Trace tab.
  4. Click File > Open and open the session .edp file that you want to trace.
  5. To start the trace, click the Record (triangle) toolbar button. The red circle should turn green and begin to rotate.
  6. Start EXTRA! X-treme and open the same session .edp file from step 4 above. Note that, in the Status application, the value in the Events column should increment as the connection progresses.
  7. When the problem has been reproduced, go back to the Status application. Stop and save the communications trace file (with .trc extension).
  8. Provide the saved trace file to Technical Support. You can either attach the file to your service request (see Technical Note 2327) or use http://upload.attachmate.com/.

Secure Connection Socket Trace – SSL

Beginning with version 9.0 SP1, detailed tracing is available to diagnose secure connection problems at the socket level for SSL connections. To enable this level of tracing, you must edit the session .edp file.

  1. Open the session .edp file in a text editor.
  2. In the [Connection] section of the session file, add the RSCTraceLevel setting. For example:
[Connection]
RSCTraceLevel=3

The following RSCTraceLevel values are supported:

0 – Tracing is off. This may be used to optimize performance.
1 – Trace errors only. This is the default setting.
2 – Trace errors and warnings.
3 – Trace everything. Use for diagnosing failing secure connections.
  1. Start an AOMDemon trace to capture the connection trace events. (See AOMDemon Trace for information about how to perform an AOMDemon trace).
  2. limited number of connection trace events are also written to the AomAudit.slg (Audit Log) file in your EXTRA! session folder and to the Windows system event log. (You can prevent this data from being written to the Windows system event log by checking “Disable event logging” in EXTRA! X-treme: click Options > Global Preferences.)
  3. After the connection issue or SSL application error has been reproduced, restore normal performance by removing the RSCTraceLevel line from the session .edp file.
  4. The AuditLog events can be viewed in the Status application (Audit Log Tab). Provide the saved AOMDemon trace or AomAudit.slg file to Technical Support. You can either attach the file to your service request (see Technical Note 2327) or use http://upload.attachmate.com/.

Secure Connection Socket Trace – SSH Connection Issues Only

Beginning with version 9.2, detailed tracing is available to diagnose secure connection problems at the socket level for SSH connections. (You can trace SSH connection issues by following the steps in this section, or by following the steps in the Secure Connection Socket Trace – All SSH Issues section.)

To enable this level of tracing, you must make changes to the session settings.

  1. Open the EXTRA! session.
  2. Go to Options > Settings > Connection.
  3. Click the “Advanced…” button.
  4. On the General tab change the Logging Level: to Debug3.

The following Logging Levels values are supported (the least information to the most):

Quiet
Fatal
Error
Info – This is the default setting
Verbose
Debug
Debug2
Debug3 – Trace everything. Use for diagnosing failing secure connections.
  1. Start an AOMDemon trace to capture the connection trace events. (See AOMDemon Trace for information about how to perform an AOMDemon trace).
  2. After the connection issue has been reproduced and the AOMDemon trace has been captured, restore normal performance by setting the Logging Level to Info.
  3. Provide the saved AOMDemon trace file to Technical Support. You can either attach the file to your service request (see Technical Note 2327) or use http://upload.attachmate.com/.

Secure Connection Socket Trace – All SSH Issues

Beginning with version 9.2 SP1, additional detailed tracing is available to diagnose secure connection issues, as well as SSH host system application communication problems.

To enable this enhanced level of tracing, you must edit the session .edp file.

  1. Open the session .edp file in a text editor.
  2. In the [Connection] section of the session file, add the RSCTraceLevel setting. For example:
[Connection]
RSCTraceLevel=3

The following RSCTraceLevel values are supported:

0 – Tracing is off. This may be used to optimize performance.
1 – Trace errors only. This is the default setting.
2 – Trace errors and warnings.
3 – Trace everything. Use for diagnosing failing secure connections.
  1. Start an AOMDemon trace to capture all the connection trace events and complete SSH traffic. (See AOMDemon Trace for information about how to perform an AOMDemon trace).

A limited number of connection trace events are also written to the AomAudit.slg (Audit Log) file in your EXTRA! session folder and to the Windows system event log. (You can prevent this data from being written to the Windows system event log by checking “Disable event logging” in EXTRA! X-treme: click Options > Global Preferences.)

  1. After the connection issue or SSH application communication issue has been reproduced, restore normal performance by removing the RSCTraceLevel line from the session .edp file.
  2. The Audit Log events can be viewed in the Status application (Audit Log Tab). Provide the saved AOMDemon trace or AomAudit.slg file to Technical Support. You can either attach the file to your service request (see Technical Note 2327) or use http://upload.attachmate.com/.

AOMDemon Trace

Note the following:

  • Run the AOMDemon trace utility only as directed by Attachmate Technical Support. The trace utility requires a special filter file that you must first obtain from support, http://support.attachmate.com/contact/.
  • It is important to run the AOMDemon trace under the same Microsoft Windows user account (or context) as the Extra.exe process, or else no trace data will be captured.

The AOMDemon trace is a detailed internal EXTRA! trace that captures low-level information that is happening within the Attachmate software including the interaction between the various code modules, API calls made and returned, thread operation, and the actions of the internal processes that make up a running EXTRA! X-treme session.

The AOMDemon.exe module is installed automatically with the EXTRA! X-treme setup program, so all users have it installed. The AOMDemon trace utility requires a special filter file for each tracing instance and must be obtained from Technical Support. The utility has limited user interface and is intended to be run from a Windows Command Prompt.

  1. Copy the filter file, typically called default.flt, to the C:\Program Files\Attachmate\EXTRA! folder where the AOMDemon.exe program is located.

On a 64-bit operating system, the Attachmate Program Files folder is located at C:\Program Files (x86)\Attachmate\EXTRA!

  1. Open a Command Prompt and make the EXTRA! Program Files folder the current directory. If you are running Microsoft Windows 7, be sure to run the Windows Command Prompt as an Administrator.
  2. To start the AOMDemon trace, type the following command in lower case:
aomdemon log default.flt outfile.trc

This starts the AOMDemon trace using the filter file called default.flt. Data will be written to a file called outfile.trc.

  1. Reproduce the problem.
  2. Return to the Command Prompt and press the ENTER key to stop and save the trace.
  3. Provide the saved trace file to Technical Support. You can either attach the file to your service request (see Technical Note 2327) or use http://upload.attachmate.com/.

Note: Beginning with EXTRA! 9.2 SP1, the default location for the filter file and output trace file is now the session storage location, which is typically <My Documents>\Attachmate\EXTRA!\Sessions\. This location is used when the path is not included with either of the file names. A fully qualified filename for either the filter or the trace file can be used if you want to redirect the input or output locations.

Default extensions are defined as .flt for filter files and .trc for trace files, if they are not included on the command line. If you want to purposefully omit the file extension, use the DOS 8.3 notation and include the period separator without qualification.

Related Technical Notes
1109 Performing a Trace in Reflection for IBM
2164 EXTRA! Developer Tools: API Code Samples and Manuals
2228 Performing a Trace in Reflection for IBM 2014 or 2011
2327 How to Attach a File to a Service Request in My Support
2481 Troubleshooting "See Status App" in EXTRA!
9970 Technical Notes for EXTRA!

Did this technical note answer your question?

           



Need further help? For technical support, please contact Support.