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
- Planning considerations
- Configuring a data source
- Performance issues
- Controlling trace log files
- Enabling the MAS Trace Facility
- Controlling 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.
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
Before using the MAS Trace Facility, there are some important factors to
consider. These include:
- Configuring a data source
- Performance issues
- Controlling trace log files
Make sure you have configured a dynamic data source. (See "Configuring the ODBC driver").
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.
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.
- Open the ODBC Data Source Administrator.
- Select the Tracing Tab.
- Click Start Tracing Now.
- Click OK.
- Follow steps 1 through 3 for "Enabling the MAS ODBC driver trace for Windows".
- 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.
- Click OK.
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.
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:
- Selecting the options using the Debug Information dialog
box.
- Setting the appropriate NEONTRACE
environment variable in DOS.
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.
- 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).
- 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.
- From the User Data Sources list, select the appropriate data
source.
- Click Configure. The system displays a configuration
dialog box, as shown in Figure 14.
Figure 14. Debug configuration

- Click Advanced. The system displays the Advanced
Information dialog box (Figure 15).
Figure 15. Advanced information

- Click Debug. The system displays the Debug
Information dialog box (Figure 16).
Figure 16. Client debug information

- Note:
- If you had selected IMS as your client type from the configuration dialog box
shown in Figure 14, the Debug button would have appeared on the Advanced
Information dialog box, shown in Figure 15
- 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:
- NONE: With this option, no messages are traced or
recorded. No trace file is created or opened. This option
effectively turns off the MAS Trace Facility.
-
FATAL: This option, the highest severity level, causes only
program termination messages to be traced and recorded.
-
SEVERE: (Default selection) This option causes only events of a
severe or higher level to be traced and recorded.
-
ERROR: This option causes all error messages to be traced and
recorded. These messages usually include a description of what went
wrong, a record of where the error was detected, any relevant return code, and
a detailed error text message.
-
WARNING: This option allows any warning messages issued by the MAS
ODBC Driver to be traced and recorded.
-
INFO: This option allows all informational events to be
traced. Note that values passed to and returned from the MAS ODBC
Driver are included here. This option will cause a large quantity of
information to be traced and recorded and is not recommended for general
use. However, this option can be useful for application
debugging.
-
DETAIL: This option, the lowest severity level, causes all events,
including function call events, to be traced. This value will cause
huge amounts of information to be traced and recorded, and it is not
recommended for general use.
- Select additional options by clicking the appropriate boxes. The
additional options include the following:
-
STAY: This option keeps the trace file open. This can
improve performance if you are using a disk file to store trace
messages.
-
FLUSH: Use this option with STAY. It helps to ensure that
messages are not lost if your machine fails.
-
STORAGE: This option causes all storage
GET and
FREE operations to be traced. The trace record shows the name of the
file requesting or freeing the storage area and the line number within the
file. The record also indicates the size of the data area being
obtained or freed, the address of the data area, and other important
information. The final storage report is generated in the Windows
environment when the DLL containing the storage manager functions is
unloaded.
-
DATA: This option causes all conversion operations to and from
DB2, ODBC C, and ODBC SQL data types to be traced. In each case, the
input and output data is displayed in hexadecimal and character format.
In addition, information is provided that designates which row and column of
the table is currently being processed.
-
SQL: This option causes all SQL statements passed to the host to
be traced, even if the trace severity level is higher than INFO. It
also causes the column information for SELECT statements to be displayed,
including the column number, name, and data type. For
SQL_NUMERIC and
SQL_DECIMAL data types, the precision and scale values are also
displayed.
- Click Select. The system displays the Select Trace
File dialog box (Figure 17).
Figure 17. Select Trace File

- Select a name and directory for the trace file.
- Click OK to return to the Debug Information dialog
box (shown in Figure 16).
- 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.
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:
- Manually enter the SET NEONTRACE=[string] command from the DOS
command line.
- Add the SET NEONTRACE=[string] command to the
AUTOEXEC.BAT and
CONFIG.SYS files. Reboot your computer for the
command to take effect.
- 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.
