Tracing

The MAS Trace Facility can be very useful in solving problems that can occur during installation and use. You can enable the client side trace for both the MAS ODBC Driver and the MAS JDBC Driver. The sections below cover the following topics:

An overview of the MAS trace facility

The MAS Trace Facility traces selected events. It creates a file named NEONLOG.TXT in a selected directory and records the traced events in that file. If a file by that name is already present, the trace facility adds any newly recorded events to it.

The format of the trace output data always includes a date, time, and pertinent information about each event.

Example of trace output data

Fri Oct 01 22:19:30 1993   pcbColName       = 0x0a5f:759a
 Fri Oct 01 22:19:30 1993   pfSqlType        = 0x0a5f:759e
 Fri Oct 01 22:19:30 1993   pcbColDef        = 0x0a5f:75a0
 Fri Oct 01 22:19:30 1993   pibScale         = 0x0a5f:7594
 Fri Oct 01 22:19:30 1993   pfNullable       = 0x0a5f:759c
 Fri Oct 01 22:19:30 1993 SQLDescribeCol exiting - return = SQL_SUCCESS(0)
 Fri Oct 01 22:19:30 1993   szColName        = 'REMARKS'
 Fri Oct 01 22:19:30 1993   *pcbColName      = 7
 Fri Oct 01 22:19:30 1993   *pfSqlType       = SQL_CHAR(1)
 Fri Oct 01 22:19:30 1993   *pcbColDef       = 64
 Fri Oct 01 22:19:30 1993   *pibScale        = 9999
 Fri Oct 01 22:19:30 1993   *pfNullable      = SQL_NULLABLE_UNKNOWN(2)
 Fri Oct 01 22:19:30 1993 SQLFetch entered
 Fri Oct 01 22:19:30 1993   lpstmt           = 0x095f:0000
 Fri Oct 01 22:19:30 1993 internal error detected: file scodbcre.c line 1228 rc =
  0 from scclxlat
 Fri Oct 01 22:19:30 1993 SQLFetch exiting - return = SQL_SUCCESS(0)
 Fri Oct 01 22:19:30 1993 SQLGetData entered
 Fri Oct 01 22:19:30 1993   lpstmt           = 0x095f:0000
 

Planning considerations

Before using the MAS Trace Facility, there are some important factors to consider. These include:

Configuring data sources

Make sure you have configured a dynamic data source. (See "Configuring the ODBC driver").

Performance issues

The MAS Trace Facility is a debugging tool that can slow the execution of your ODBC application. Because of this, you may want to turn it off once you have the driver and your applications operating perfectly. This can be done by setting up the DOS environment variable SET NEONTRACE=NONE.

Controlling trace logfiles

If a fully qualified pathname (including a directory) for the NEONLOG.TXT file has not been specified, the MAS Mainframe Agent creates the NEONLOG.TXT file in the current directory. Over time, this could result in several NEONLOG.TXT files in several different directories. These files can become very large, especially if you are using a low severity level trigger to trace events. These files should be deleted as necessary.

Enabling the MAS ODBC driver trace for Windows

  1. Open the ODBC Data Source Administrator.
  2. Select the Tracing Tab.
  3. Click Start Tracing Now.
  4. Click OK.

Enabling the MAS JDBC driver trace for Windows

  1. Follow steps 1 through 3 for "Enabling the MAS ODBC driver trace for Windows".
  2. Add the following item to the NEONTRACE environment variable in DOS:
    JDBCLOG=xyz
     
    

    where xyz is the full pathname of a log file. For example, on Windows NT, you may have:

    THREADID INFO BUFFER JDBCLOG=C:\temp\neonjdbc.txt LOG=C:\temp\neonlog.txt
     
    
    Note:
    The JDBCLOG keyword must precede the LOG keyword.

    Two separate files will be generated: one for the ODBC driver and one for the JDBC driver.

  3. Click OK.

Using the JDBC trace on Windows NT

To perform the trace in the Windows NT environment if you are running in TYPE1 mode (default), ensure that the trace file specified in the data source has the same file name as the one specified in the LOG keyword. If you omit the LOG keyword from the NEONTRACE parameter, the trace will be written to the trace file specified in the data source.

Controlling the MAS Trace Facility

The MAS Trace Facility's default values provide adequate tracing in most cases. However, you might need to change the MAS Trace Facility's severity level trigger or tracing options. You can do this in one of the following ways:

Using the debug dialog box

The most commonly used method for controlling the MAS Trace Facility is to use the Debug Information dialog box. This lists all of the options available to you and ensures that the correct keyword is changed in the ODBC.INI file.

  1. Open the Start menu and select Settings/Control Panel (if you are using Windows 95 or higher) or Settings/Control Panel/Administrative Tools (if you are using Windows NT 3.0 or higher).
  2. Double-click the ODBC Data Sources icon (or item, if viewing by List or Details).

    The system displays the ODBC Data Source Administrator dialog box.

  3. From the User Data Sources list, select the appropriate data source.
  4. Click Configure. The system displays a configuration dialog box, as shown in Figure 13.

    Figure 13. Debug configuration

  5. Click Advanced. The system displays the Advanced Information dialog box (Figure 14).

    Figure 14. Advanced information

  6. Click Debug. The system displays the Debug Information dialog box (Figure 15).

    Figure 15. Client debug information

    Note:
    If you had selected IMS as your client type from the configuration dialog box shown in Figure 13, the Debug button would have appeared on the Advanced Information dialog box, shown in Figure 14
  7. Select the appropriate severity level trigger of the events to be traced. When a severity level is selected, all events at and above that severity level will be traced and recorded. The severity options are listed below from the highest to the lowest level:
  8. Select additional options by clicking the appropriate boxes. The additional options include the following:
  9. Click Select. The system displays the Select Trace File dialog box (Figure 16).

    Figure 16. Select Trace File

  10. Select a name and directory for the trace file.
  11. Click OK to return to the Debug Information dialog box (shown in Figure 15).
  12. Click OK.

    This writes a NEONTRACE keyword in the appropriate section of the ODBC.INI file. The NEONTRACE keyword will reflect the options you selected with the data source that you selected from the ODBC Data Source Administrator. The contents of the ODBC.INI file augment and override any DOS environment variable values set earlier using the SET NEONTRACE=[string] command.

Setting the trace environment variable in DOS

The other approach for controlling the MAS Trace Facility is to set a trace environment variable in DOS. To set this variable, use the following form:

SET NEONTRACE=[string]
 

where [string] consists of the options you select, delimited with spaces.

Set this variable in one of the following ways:

Note:
If you prefer to enter the command manually, be sure to do so within DOS itself and not through a DOS window while Windows is still running. Setting the trace environment variable from a DOS window (which uses a second-level command processor) will have no effect at all on the MAS Trace Facility.

Copyright IBM Corp. 1997, 2003