Using the NLM Application Debugging Tool

September 12, 1995

Disclaimer

Novell, Inc. Makes no representations or warranties with respect to any software or to the contents or use of this document, and specifically disclaims any express or implied warranties of merchantability, title or fitness for any particular purpose. Further, Novell, Inc. Reserves the right to modify or replace any and all parts of the software, this document, or the contents of this document at any time, without any obligation of any person or entity of such changes.

Copyright

© Copyright 1993, Novell, Inc. All rights reserved. No part of this package (NLMDEBUG) may be redistributed without the express prior written consent of the publisher.

Overview

The NLM Application Debugging Tool provides the ability to debug your NLM applications and ready them for certification. This NLM gives you the capability to check your NLM's resources, semaphores, memory overwrites, and debug NCPs. You can set the debugger to break or delay after each packet, at a specific function code or sub-function code, or just on errors. The NLM Application Debugger gives you the information needed to quickly debug your NLM applications and where the NLM needs to relinquish the CPU so that it can certify easily.

Setting Up and Using NLM Debugger

To use the NLM Debugger, simply copy nlmdebug.nlm to the server where the NLM you want to debug is loaded. At the prompt type LOAD NLMDEBUG. The NLM Debugging Tool main screen opens.

NOTE: Make sure that CLIB.NLM v.4.11 is loaded.

The main screen displays the Debug Options Menu. Select the debug option you want by using the up and down arrow keys to highlight the option and press Enter.

Setting CLib Debug Options

From the CLib Debug Options menu you can set the debugger to check for resources not freed, memory overwrites, semaphores not freed, and have the debugger report if a CLib call is used when you don't have CLib Context. You can even set the debugger to ring a bell when information is written to the console.

To set CLib Debug options:

1.	From the NLM Debugger main menu select CLib Debug Options and press Enter.

The CLib Debug Options menu displays.

2.	Select the options you want the debugger to check and press Y.

3.	Press Enter.

4.	When you are done, press Esc.

Once the options are set, they stay set until you change them, even if NLMDEBUG is unloaded and reloaded.

Clib Resource Checking

When the CLib Resource Checking option is set to Yes, the NLM Debugger checks for various resources allocated by your NLM that are not subsequently freed. A Stack Walk to the location of the allocated resources not freed displays on the console screen.

Clib Memory Checking

When the CLib Memory Checking option is set to Yes, the NLM Debugger checks for memory overwrites on all memory API calls. A Stack Walk to the location of the memory overwrites displays on the console screen. If you want to force the checking at a certain point in your code call free (NULL).

Clib Semaphore Checking

When the CLib Semaphore Checking option is set to Yes, the NLM Debugger checks for any semaphores allocated by your NLM and not subsequently freed. A Stack Walk to the location of the allocated semaphores not freed displays on the console screen. (Unfreed semaphore allocated through CLib no longer ABEND the server.)

Report No CLib Context

When the Report No CLib Context option is set to Yes, if a CLib call that requires CLib Context is used when you don't have it, the error is reported to you on the console.

Ring the Bell on Error

When Ring the Bell on Error is set to Yes, whenever an error is detected as per the conditions set in CLib Debug Options and an error message is printed to the console screen, a bell rings.

Using NCP Debugger

Use the NCP Debugger to watch request and reply packet activity for your NLMs. Set the NCP Debugger so that you can watch activity for every packet, only when there are errors, or for specific functions and/or sub-functions.

To use NCP Debugger:

1.	From the NLM Debugger main menu select NCP Debugger Menu and press Enter.

The NCP Debugger Setup Menu displays.

2.	Enter the server your NLM is communicating with. If left blank all servers are monitored.

3.	Set the conditions you want for monitoring packets and press Enter.

4.	Press Esc.

The NCP Debugger Setup Menu closes and the Waiting for Beginning Request Packet and Waiting for Beginning Reply Packet windows display. Run your NLM and from this screen watch the packet activity based on the set conditions. To view the buffer information for either the Request Packet Activity or the Reply Packet Activity, highlight the screen you are interested in with the Pg Up and Pg Dn keys. Then scroll through the information in the buffer of the highlighted screen using the up and down arrow keys.

Press F4 from the NCP Debugger window to display the NCP Debugger Setup Menu again. You can make any changes to the NCP Debugger Setup at any time, even while your NLM is being monitored.

Break On Connection Number

To have the debugger break on a specific connection number:

1.	From the NCP Debugger Setup Menu, highlight the Break on Connection Number edit box using the up and down arrow keys.

2.	Enter the connection number you want the NLM debugger to break on and press Enter.

The debugger will break on the connection number entered.

If you do not want the debugger to break on a connection number, enter 0 in the edit box.

Break on Function Code

To have the debugger break on a specific function code:

1.	From the NCP Debugger Setup Menu, highlight the Break on Function Code edit box using the up and down arrow keys.

2.	Enter the function code as a hex number and press Enter.

If you do not want to break on a function code, enter a 0 in the edit box.

Break on Sub-Function Code

To have the debugger break on a specific sub-function code:

1.	From the NCP Debugger Setup Menu, highlight the Break on Sub-Function Code edit box using the up and down arrow keys.

2.	Enter the sub-function code as a hex number and press Enter

If you do not want the debugger to break on a function code, enter a 0 in the edit box.

Break on Error

To have the debugger break on errors:

1.	From the NCP Debugger Setup Menu, highlight the Break on Error edit box. using the up and down arrow keys.

2.	Press Y and press Enter.

The debugger will break wherever an error is encountered sending an NCP packet.

If you do not want the debugger to break on errors, enter a No in the edit box.

Break on Every Packet

To have the debugger break on every packet:

1.	From the NCP Debugger Setup Menu, highlight the Break on Every Packet edit box using the up and down arrow keys.

2.	Press Y and press Enter.

The debugger will break after each packet and only continue after you press the Space bar.

If you do not want the debugger to break on every packet, enter a No in the edit box.

Delay between Packets

To have the debugger break after each packet for a specified amount of time:

1.	From the NCP Debugger Setup Menu, highlight the Delay Between Packets edit box using the up and down arrow keys.

2.	Enter the delay time in seconds and press Enter.

The debugger will break after each packet for the specified time before continuing.

If you do not want the debugger to delay between packets, enter 0 in the edit box.

Packet Header Information

To view the Packet Header Information:

1.	From the NCP Debugger main screen, press F3 .

The Packet Header Information screen displays.

Checksum

This field displays the packet's checksum.

Packet Length

This field displays the entire length of the packet, including the length of the header and the length of the data.

Transport Control

This field displays the packet transport control. IPX always sets this field to zero before sending the packet.

Destination Socket

This field displays the destination socket address. The following sockets are reserved for use by NetWare:

451	File Service Packet

452	Service Advertising Packet

453	Routing Information Packet

455	NetBIOS Packet

456	Diagnostic Packet

Therefore, NetWare file servers accept requests addressed to socket 0x0451 .

From

This field displays the physical address of the packet's source node.

Source Socket

This field displays the socket address of the packet's source node.

NCP Type

This field displays the packet NCP type.

Sequence Number

This field displays the packet sequence number.

Low Slot

This field displays the low slot connection number.

Task

This field displays which client task is making the service request.

High Slot

This field displays the high slot connection number.

Return Code

This field displays the packet return code as a hex value.

Connection Status

This field displays the packet connection status.

Stack Walk Information

To view the Stack Walk information:

1.	From the NCP Debugger main screen, press F2 .

The Stack Walk Information screen opens and displays the Stack Walk information to the call generating the received packet.

Error Status

To view the NCP Error Status for a specific error:

1.	From the NCP Debugger main screen, press F5.

The Error Status screen opens displaying information about the detected error.

The Return Code field displays the error string associated with the error.

The Connect Status information field tells you whether the connection is OK or Bad.

The Reply ECB Status field tells you if there are buffer overflows or if it was successful.

Using NLM Process Timer

Use the NLM Process Timer to determine where your NLM needs to relinquish the CPU.

To use NLM Process Timer:

1.	From the NCP Debugger Tool main menu select NLM Process Timer and press Enter.

The NLM Process Time screen displays.

2.	Enter the maximum time slice in milliseconds and press Enter.

3.	Press Enter.

4.	The NLM Process Stack Trace screen displays. Whenever your NLM takes longer than the entered number of ms to relinquish CPUs, a Stack Walk to the problem displays in this screen.

5.	To quit the NLM Process Stack Trace, press Esc.