home *** CD-ROM | disk | FTP | other *** search
/ Network Support Encyclopedia 96-1 / novell-nsepro-1996-1-cd2.iso / download / netware / tdbg1b.exe / NLMDBG.TXT < prev    next >
Text File  |  1995-09-12  |  12KB  |  370 lines
  1.             Using the NLM Application Debugging Tool
  2.                        September 12, 1995
  3.  
  4.  
  5. Disclaimer
  6.  
  7.      Novell, Inc. Makes no representations or warranties with
  8.      respect to any software or to the contents or use of this
  9.      document, and specifically disclaims any express or implied
  10.      warranties of merchantability, title or fitness for any
  11.      particular purpose. Further, Novell, Inc. Reserves the right
  12.      to modify or replace any and all parts of the software, this
  13.      document, or the contents of this document at any time,
  14.      without any obligation of any person or entity of such
  15.      changes.
  16.  
  17. Copyright
  18.  
  19.      (C)Copyright 1993, Novell, Inc. All rights reserved. No part
  20.      of this package (NLMDEBUG) may be redistributed without the
  21.      express prior written consent of the publisher.  
  22.  
  23. Overview  
  24.  
  25.      The NLM Application Debugging Tool provides the ability to
  26.      debug your NLM applications and ready them for
  27.      certification. This NLM gives you the capability to check
  28.      your NLM's resources, semaphores, memory overwrites, and
  29.      debug NCPs. You can set the debugger to break or delay after
  30.      each packet, at a specific function code or sub-function
  31.      code, or just on errors. The NLM Application Debugger gives
  32.      you the information needed to quickly debug your NLM
  33.      applications and where the NLM needs to relinquish the CPU
  34.      so that it can certify easily.  
  35.  
  36. Setting Up and Using NLM Debugger  
  37.  
  38.      To use the NLM Debugger, simply copy nlmdebug.nlm to the
  39.      server where the NLM you want to debug is loaded. At the
  40.      prompt type LOAD NLMDEBUG. The NLM Debugging Tool main
  41.      screen opens.   
  42.  
  43.           NOTE:  Make sure that CLIB.NLM v.4.11 is loaded.  
  44.  
  45.      The main screen displays the Debug Options Menu. Select the
  46.      debug option you want by using the up and down arrow keys to
  47.      highlight the option and press Enter.  
  48.  
  49. Setting CLib Debug Options  
  50.  
  51.      From the CLib Debug Options menu you can set the debugger to
  52.      check for resources not freed, memory overwrites, semaphores
  53.      not freed, and have the debugger report if a CLib call is
  54.      used when you don't have CLib Context. You can even set the
  55.      debugger to ring a bell when information is written to the
  56.      console.  
  57.  
  58.      To set CLib Debug options:  
  59.  
  60.      1.   From the NLM Debugger main menu select CLib Debug
  61.           Options and press Enter.
  62.  
  63.      The CLib Debug Options menu displays.  
  64.  
  65.      2.   Select the options you want the debugger to check and
  66.           press Y.  
  67.  
  68.      3.   Press Enter.  
  69.  
  70.      4.   When you are done, press Esc.  
  71.  
  72.      Once the options are set, they stay set until you change
  73.      them, even if NLMDEBUG is unloaded and reloaded.  
  74.  
  75.      Clib Resource Checking  
  76.  
  77.      When the CLib Resource Checking option is set to Yes, the
  78.      NLM Debugger checks for various resources allocated by your
  79.      NLM that are not subsequently freed. A Stack Walk to the
  80.      location of the allocated resources not freed displays on
  81.      the console screen.
  82.  
  83.      Clib Memory Checking  
  84.  
  85.      When the CLib Memory Checking option is set to Yes, the NLM
  86.      Debugger checks for memory overwrites on all memory API
  87.      calls. A Stack Walk to the location of the memory overwrites
  88.      displays on the console screen. If you want to force the
  89.      checking at a certain point in your code call free (NULL).
  90.  
  91.      Clib Semaphore Checking
  92.  
  93.      When the CLib Semaphore Checking option is set to Yes, the
  94.      NLM Debugger checks for any semaphores allocated by your NLM
  95.      and not subsequently freed. A Stack Walk to the location of
  96.      the allocated semaphores not freed displays on the console
  97.      screen. (Unfreed semaphore allocated through CLib no longer
  98.      ABEND the server.)  
  99.  
  100.      Report No CLib Context  
  101.  
  102.      When the Report No CLib Context option is set to Yes, if a
  103.      CLib call that requires CLib Context is used when you don't
  104.      have it, the error is reported to you on the console.
  105.  
  106.      Ring the Bell on Error  
  107.  
  108.      When Ring the Bell on Error is set to Yes, whenever an error
  109.      is detected as per the conditions set in CLib Debug Options
  110.      and an error message is printed to the console screen, a
  111.      bell rings.   
  112.  
  113. Using NCP Debugger  
  114.  
  115.      Use the NCP Debugger to watch request and reply packet
  116.      activity for your NLMs. Set the NCP Debugger so that you can
  117.      watch activity for every packet, only when there are errors,
  118.      or for specific functions and/or sub-functions.  
  119.  
  120.      To use NCP Debugger:  
  121.  
  122.      1.   From the NLM Debugger main menu select NCP Debugger
  123.           Menu and press Enter.
  124.  
  125.           The NCP Debugger Setup Menu displays.  
  126.  
  127.      2.   Enter the server your NLM is communicating with. If
  128.           left blank all servers are monitored.  
  129.  
  130.      3.   Set the conditions you want for monitoring packets and
  131.           press Enter.  
  132.  
  133.      4.   Press Esc.  
  134.  
  135.           The NCP Debugger Setup Menu closes and the Waiting for
  136.           Beginning Request Packet and Waiting for Beginning
  137.           Reply Packet windows display. Run your NLM and from
  138.           this screen watch the packet activity based on the set
  139.           conditions. To view the buffer information for either
  140.           the Request Packet Activity or the Reply Packet
  141.           Activity, highlight the screen you are interested in
  142.           with the Pg Up and Pg Dn keys. Then scroll through the
  143.           information in the buffer of the highlighted screen
  144.           using the up and down arrow keys.  
  145.  
  146.      Press F4 from the NCP Debugger window to display the NCP
  147.      Debugger Setup Menu again. You can make any changes to the
  148.      NCP Debugger Setup at any time, even while your NLM is being
  149.      monitored.  
  150.  
  151.      Break On Connection Number  
  152.  
  153.      To have the debugger break on a specific connection number:  
  154.  
  155.      1.   From the NCP Debugger Setup Menu, highlight the Break
  156.           on Connection Number edit box using the up and down
  157.           arrow keys.  
  158.  
  159.      2.   Enter the connection number you want the NLM debugger
  160.           to break on and press Enter.
  161.  
  162.      The debugger will break on the connection number entered.  
  163.  
  164.      If you do not want the debugger to break on a connection
  165.      number, enter 0 in the edit box.  
  166.  
  167.      Break on Function Code  
  168.  
  169.      To have the debugger break on a specific function code:  
  170.  
  171.      1.   From the NCP Debugger Setup Menu, highlight the Break
  172.           on Function Code edit box using the up and down arrow
  173.           keys.  
  174.  
  175.      2.   Enter the function code as a hex number and press
  176.           Enter.  
  177.  
  178.      If you do not want to break on a function code, enter a 0 in
  179.      the edit box.
  180.  
  181.      Break on Sub-Function Code  
  182.  
  183.      To have the debugger break on a specific sub-function code:  
  184.  
  185.      1.   From the NCP Debugger Setup Menu, highlight the Break
  186.           on Sub-Function Code edit box using the up and down
  187.           arrow keys.  
  188.  
  189.      2.   Enter the sub-function code as a hex number and press
  190.           Enter  
  191.  
  192.      If you do not want the debugger to break on a function code,
  193.      enter a 0 in the edit box.  
  194.  
  195.      Break on Error  
  196.  
  197.      To have the debugger break on errors: 
  198.  
  199.      1.   From the NCP Debugger Setup Menu, highlight the Break
  200.           on Error edit box. using the up and down arrow keys.  
  201.  
  202.      2.   Press Y and press Enter.  
  203.  
  204.           The debugger will break wherever an error is
  205.           encountered sending an NCP packet.  
  206.  
  207.      If you do not want the debugger to break on errors, enter a
  208.      No in the edit box.  
  209.  
  210.      Break on Every Packet 
  211.  
  212.      To have the debugger break on every packet:  
  213.  
  214.      1.   From the NCP Debugger Setup Menu, highlight the Break
  215.           on Every Packet edit box using the up and down arrow
  216.           keys.  
  217.  
  218.      2.   Press Y and press Enter.  
  219.  
  220.      The debugger will break after each packet and only continue
  221.      after you press the Space bar.  
  222.  
  223.      If you do not want the debugger to break on every packet,
  224.      enter a No in the edit box. 
  225.  
  226.      Delay between Packets  
  227.  
  228.      To have the debugger break after each packet for a specified
  229.      amount of time:  
  230.  
  231.      1.   From the NCP Debugger Setup Menu, highlight the Delay
  232.           Between Packets edit box using the up and down arrow
  233.           keys.   
  234.  
  235.      2.   Enter the delay time in seconds and press Enter.  
  236.  
  237.      The debugger will break after each packet for the specified
  238.      time before continuing.  
  239.  
  240.      If you do not want the debugger to delay between packets,
  241.      enter 0 in the edit box.  
  242.  
  243.      Packet Header Information  
  244.  
  245.      To view the Packet Header Information:  
  246.  
  247.      1.   From the NCP Debugger main screen, press F3.  
  248.  
  249.           The Packet Header Information screen displays.  
  250.  
  251.      Checksum  
  252.  
  253.      This field displays the packet's checksum. 
  254.  
  255.      Packet Length  
  256.  
  257.      This field displays the entire length of the packet,
  258.      including the length of the header and the length of the
  259.      data.   
  260.  
  261.      Transport Control  
  262.  
  263.      This field displays the packet transport control. IPX always
  264.      sets this field to zero before sending the packet.  
  265.  
  266.      Destination Socket  
  267.  
  268.      This field displays the destination socket address. The
  269.      following sockets are reserved for use by NetWare:  
  270.  
  271.           451  File Service Packet  
  272.           452  Service Advertising Packet  
  273.           453  Routing Information Packet  
  274.           455  NetBIOS Packet  
  275.           456  Diagnostic Packet  
  276.  
  277.      Therefore, NetWare file servers accept requests addressed to
  278.      socket 0x0451.  
  279.  
  280.      From  
  281.  
  282.      This field displays the physical address of the packet's
  283.      source node.  
  284.  
  285.      Source Socket  
  286.  
  287.      This field displays the socket address of the packet's
  288.      source node.  
  289.  
  290.      NCP Type  
  291.  
  292.      This field displays the packet NCP type.  
  293.  
  294.      Sequence Number  
  295.  
  296.      This field displays the packet sequence number.  
  297.  
  298.      Low Slot  
  299.  
  300.      This field displays the low slot connection number.  
  301.  
  302.      Task  
  303.  
  304.      This field displays which client task is making the service
  305.      request.  
  306.  
  307.      High Slot  
  308.  
  309.      This field displays the high slot connection number.  
  310.  
  311.      Return Code  
  312.  
  313.      This field displays the packet return code as a hex value.  
  314.  
  315.      Connection Status  
  316.  
  317.      This field displays the packet connection status.  
  318.  
  319.      Stack Walk Information 
  320.  
  321.      To view the Stack Walk information: 
  322.  
  323.      1.   From the NCP Debugger main screen, press F2.  
  324.  
  325.           The Stack Walk Information screen opens and displays
  326.           the Stack Walk information to the call generating the
  327.           received packet.  
  328.  
  329.      Error Status 
  330.  
  331.      To view the NCP Error Status for a specific error:  
  332.  
  333.      1.   From the NCP Debugger main screen, press F5.  
  334.  
  335.           The Error Status screen opens displaying information
  336.           about the detected error.  
  337.      
  338.           The Return Code field displays the error string
  339.           associated with the error.  
  340.  
  341.           The Connect Status information field tells you whether
  342.           the connection is OK or Bad.  
  343.  
  344.           The Reply ECB Status field tells you if there are
  345.           buffer overflows or if it was successful.
  346.  
  347.  Using NLM Process Timer  
  348.  
  349.      Use the NLM Process Timer to determine where your NLM needs
  350.      to relinquish the CPU.  
  351.  
  352.      To use NLM Process Timer:  
  353.  
  354.      1.   From the NCP Debugger Tool main menu select NLM Process
  355.           Timer and press Enter.
  356.  
  357.           The NLM Process Time screen displays.  
  358.  
  359.      2.   Enter the maximum time slice in milliseconds and press
  360.           Enter.  
  361.  
  362.      3.   Press Enter.  
  363.  
  364.      4.   The NLM Process Stack Trace screen displays. Whenever
  365.           your NLM takes longer than the entered number of ms to
  366.           relinquish CPUs, a Stack Walk to the problem displays
  367.           in this screen.  
  368.  
  369.      5.   To quit the NLM Process Stack Trace, press Esc.
  370.