Application Messages and Return Codes

Messages and Logging

The NTRACE.EXE program and the utility programs which use the services of the NTRACE.OS2 device driver, will display their messages to STDOUT (the "console" of the command session in which they are running).

When the -l option is used with NTRACE.EXE, all console output is also written to NTRACE.LOG or to a filename of the user's specification.

Message Types

There are 2 types of messages that can be generated by the tracing control application and utility programs.

The first type is a failure in the NTRACE.EXE module itself.  These are messages related to the command line parameters, memory allocation or file system operations.

The second type of message can be generated by NTRACE.EXE or by the other utilities which utilize the services of the NTRACE.OS2 device driver.  These can be called "Device Request" messages.  These messages are specific to either:

When this second type of error occurs, it is ALWAYS fatal and usually indicates a severe problem with the installation.

NTRACE.EXE Specific Messages and Return Codes

Message
NTRACE.EXE
Return Code
Error Level
Description
Action
Unknown option %1 ignored n/a Warning Unrecognized option or parameter "1%" was entered on the command line. The program ignores the entry and continues processing.
DosCloseMutexSem error=%1 n/a Warning An error %1 has occurred when closing the mutex semaphore.  No action required, this error does not prevent the application from completing.
DosCloseEventSem error=%1 n/a Warning An error %1 has occurred when closing the event semaphore. No action required, this error does not prevent the application from completing.
DosFreeMem error=%1 n/a Warning An error %1 has occurred when freeing the trace buffer memory. No action required, this error does not prevent the application from completing.
DosClose error = %d n/a Warning An error %1 has occurred when closing the device driver. No action required, this error does not prevent the application from completing.
Can't create log file %1. Logging suppressed. n/a Warning The fopen() for the log file failed. Check the specified path for validity.  Ensure that the path specifies a writable disk location with free space available.
Network hardware errors detected during this session: n/a Warning The application detected hardware errors as reported by MAC. No action required, this error does not prevent the application from completing.
Another trace or playback session is active. 2 Fatal The user made a second attempt to start tracing for the same driver instance. This is not possible.  Only one trace at any given time may be taken per instance.
Invalid adapter index specified with -a option. Valid indexes are from 0 to %1.

OR
 

Invalid adapter index specified with -a option. The only valid index is 0

 3 Fatal The -a option was specified which is invalid. Utilize the NTRACE -q  to display a report of the possible indexes.  Restart the trace with the correct -a index.
Memory allocation failed for MAC SCT control block 6 Fatal The application can't get temporary memory.  OS/2 is reporting that no additional virtual memory is available. Make more memory available to application programs.  Close unnecessary applications.
Memory allocation failed for Trace Buffer 6 Fatal The OS/2 system can't allocate the requested amount of virtual memory for the Trace Buffer. Check the trace buffer size parameter on the command line for possible error.  Try to restart the application with a smaller trace buffer or stop other applications to free up memory resources.
  7 Fatal DosCreateEventSem error. The system cannot allocate semaphore resources.  Close running applications or reboot.
  8 Fatal DosCreateMutexSem error. The system cannot allocate semaphore resources.  Close running applications or reboot.
  9 Fatal DosCreateMutexSem error. The system cannot allocate semaphore resources.  Close running applications or reboot.
  10 Fatal DosCreateEventSem error. The system cannot allocate semaphore resources.  Close running applications or reboot.
  99 Fatal User aborted the trace using CTRL-C or CTRL-BREAK. No action necessary.
"The 32-bit OS/2 system does not support %dMb memory buffers" 100 Fatal The system cannot allocate a memory buffer which is larger than can be represented by a 32-bit integer. Run application again with a smaller buffer value (<= 4095).
  100 Informational This is returned when the syntax display has been shown. No action necessary.
The product license has expired; please contact vendor for renewal. 996 Fatal The license file (LICENSE.NTO) is no longer valid. Obtain and properly deploy a valid license file.
The product license file is inaccessible. 997 Fatal The license file (LICENSE.NTO) cannot be opened. Obtain and properly deploy a valid license file.
The product license file %s is not available for reading. 998 Fatal The license file (LICENSE.NTO) cannot be found. Obtain and properly deploy a valid license file.
The product license file %s is corrupt; please reinstall original license file. 998 Fatal The license file (LICENSE.NTO) has been modified since creation.  This file is digitally signed and any changes will invalidate its use. Obtain and properly deploy a valid license file.
The product license file LICENSE.NTO is missing; please reinstall your original license file. 999 Fatal The license file (LICENSE.NTO) cannot be found. Place a valid LICENSE.NTO in the right search path.

Device Request Messages and Return Codes

Message
NTRACE.EXE 
Return Code
Description
Action
Can't contact the Network Trace driver instance %1, OS/2 error = %2
Check the instance name		 1 DosOpen() failed for this instance of the device driver. Ensure that an instance of NTRACE exists with the specified name.
The Network Trace driver instance %1 returned an error.
... see below		 4 CAPTURE_GETTABSIZE operation failed The corrective action is dependent upon the contents of the message text.  In some cases, the state of the machine is unreliable and corrective action may not be possible.
The Network Trace driver instance %1 returned an error.
... see below		 5 CAPTURE_GETSCTABLE operation failed The corrective action is dependent upon the contents of the message text.  In some cases, the state of the machine is unreliable and corrective action may not be possible.
The Network Trace driver instance %1 returned an error.
... see below		 11 CAPTURE_STARTREC operation failed The corrective action is dependent upon the contents of the message text.  In some cases, the state of the machine is unreliable and corrective action may not be possible.

For return codes 4, 5, and 11, there is a variety of message text which can be displayed.  These error conditions can occur ONLY when communication has been established with the device driver (DosOpen is successful).

In all cases the first message line will include:

The Network Trace driver instance %1 returned an error.

The second line will indicate 3 additional pieces of information:

This second line will be formatted in one of the following:
  1. Operation attempted was ILLEGAL (%1), error code was %2
  2. Operation attempted was %1, error code was %2


If the request was ILLEGAL, then there is most likely a version mismatch between the driver and the application or utility.  In this case, no other information will be displayed.

If the request was accepted as legal, then this indicates a generic error.  Additional message text will be displayed as follows:
 
If the 3rd Line is:
Then the 4th Line is:
One of the following:
  • ClearStatistics call returned an error.
  • UpdateStatistics call returned an error.
  • SetPacketFilter call returned an error when turning tracing on.
  • SetPacketFilter call returned an error when turning tracing off.
 One of the following:
  • No NDIS error detected.
  • NDIS call returned unexpected REQUEST_QUEUED code.
  • NDIS call returned OUT_OF_RESOURCE error code.
  • NDIS call returned INVALID_PARAMETER error code.
  • NDIS call returned INVALID_FUNCTION error code.
  • NDIS call returned NOT_SUPPORTED error code. 
  • NDIS call returned GENERAL_FAILURE error code.
  • NDIS call returned an unknown error code.
One of the following:
  • DevHelp service VirtToLin returned an error for the trace buffer header.
  • DevHelp service VMLock returned an error for the trace buffer header.
  • DevHelp service LinToGDTSelector returned an error for the trace buffer header.
  • DevHelp service VMLock returned an error for the trace buffer.
  • DevHelp service OpenEventSem returned an error for the trace data event semaphore.
  • DevHelp service VMAllock returned an error for the intermediate buffers.
  • DevHelp service LinToGDTSelector returned an error for the intermediate buffers.
  • DevHelp service VMFree returned an error for the intermediate buffers.
 DevHelp returned %1
Parameter passed to the driver has invalid size. The most probable reason is the mismatch between NTRACE.EXE and NTRACE.OS2
The driver's state is inconsistent with the operation requested. The most probable reasons are incomplete bindings or bad MAC index.
The requested operation is valid for VECTOR binding only. n/a
The error code cannot be interpreted. n/a

© 2000 Golden Code Development Corporation.  ALL RIGHTS RESERVED