VMS Help DEBUG  *Conan The Librarian (sorry for the slow response - running on an old VAX)

    Invokes the OpenVMS Debugger.

    For a complete description of the OpenVMS Debugger, refer to the
    OpenVMS Debugger Manual.

    To get help on debugger commands from DCL level, type the
    following command:

    $ HELP/LIBRARY=SYS$HELP:DBG$HELP DEBUG

    Format

      DEBUG

1 - Heap Analyzer

    The Heap Analyzer provides a graphical representation of memory
    use in real time. This allows you to quickly identify inefficient
    memory usage in your application such as allocations that are
    made too often, memory blocks that are too large, fragmentation,
    or memory leaks.

    For details on running the Heap Analyzer from within the
    debugger, refer to the OpenVMS Debugger Manual.

    To run the standalone Heap Analyzer, issue the following
    commands:

    $ DEFINE/USER/NAME=CONFINE LIBRTL SYS$LIBRARY:LIBRTL_INSTRUMENTED
    $ RUN/NODEBUG program

2 - Qualifiers

 2.1 - /CLIENT

    Invokes the DEBUG client MOTIF interface. From the client, use
    the network binding string displayed by the server at startup
    to establish the connection. The first client to connect to
    the server is the primary client, and controls the number of
    secondary clients allowed to connect to the server.

 2.2 - /KEEP

    Invokes the kept debugger. The kept debugger includes a Run/Rerun
    capability that allows you to debug an image multiple times or
    debug a series of distinct images without exiting the debugger.

    Issuing the DEBUG/KEEP command is the only way to invoke the kept
    debugger.

 2.3 - /RESUME

       /RESUME (default)

    Reinvokes the non-kept debugger after a Ctrl/Y key sequence has
    interrupted the execution of a program you are debugging. (The
    interrupted program must not have been linked with a /NOTRACEBACK
    qualifier on the LINK command.)

    If you issue the DEBUG/RESUME command without a previous Ctrl/Y
    key sequence, no action occurs.

 2.4 - /SERVER

       /SERVER
       [=( [BINDING_INFO=filespec] [,PROTOCOLS=(protocol[,...])]
       )]

    Invokes the DEBUG server. The DEBUG server allows up to 30
    simultaneous connections from clients on the same or remote
    OpenVMS nodes, or from PC nodes running Microsoft Windows 95
    or Microsoft Windows NT.

    (Optional) If specified, the BINDING_INFO keyword specifies that
    the server binding identification strings are to be written to
    filespec. If not specified, no file is created.

    (Optional) If specified, the PROTOCOLS keyword specifies which
    network protocols should be enabled for connection to the
    DEBUG server. Only the specified protocols are enabled. If not
    specified, all protocols are enabled. The protocol argument can
    be one or more of the following keywords:

       ALL
       [NO]DECNET
       [NO]TCP_IP
       [NO]UDP

    The first client to connect to the server is the primary client.
    A client that connects to the server after the primary client
    establishes the connection is a secondary client. The primary
    client controls the number of secondary clients allowed to
    connect to the server.

    The server displays a series of RPC binding strings that identify
    the port numbers through which the client can connect to the
    server. The port number appears in square brackets ([]) at the
    end of the identification strings.

    When connecting from the client, the simplest port identification
    string consists of the node name of the server followed by the
    port number in square brackets. The following are all valid
    binding identification strings:

       NODNAM[1234]
       NCACN_IP_TCP:16.32.16.25[1112]
       16.32.16.25[1112]
       NCACN_DNET_NSP:63.1004[RPC20A020DD0001]

                                   NOTE

       You must hold the DBG$ENABLE_SERVER identifier in the rights
       database to be able to run the debug server. Exercise care
       when using the debug server. Once a debug server is running,
       anyone on the network has the ability to connect to the
       debug server.

    Before granting the DBG$ENABLE_SERVER identifier, the system
    manager must create it by entering the command DEBUG/SERVER
    from an account with write access to the rights database. The
    system manager needs to do this only once. The system manager
    can then run the Authorize utility to grant the DBG$ENABLE_SERVER
    identifier to the user's account in the rights database.

3 - Examples

    1.$ FORTRAN/DEBUG/NOOPTIMIZE WIDGET
      $ LINK/DEBUG WIDGET
      $ RUN WIDGET

                      [ Debugger Banner and Version ]

      %DEBUG-I-INITIAL, language is FORTRAN, module set to WIDGET
      DBG>

      The FORTRAN and LINK commands both specify the /DEBUG qualifier
      to compile the program WIDGET.FOR with debugger symbol table
      information. Because the program has been compiled and linked
      with debug information, the debugger is automatically invoked
      by the image activator upon starting the program with the
      RUN command. No program code has yet been executed when the
      debugger is invoked.

    2.$ FORTRAN/DEBUG/NOOPTIMIZE WIDGET
      $ LINK/DEBUG WIDGET
      $ RUN/NODEBUG WIDGET

        NAME:
        NAME:
        NAME:
      ^Y
      $ DEBUG/RESUME

                   [ Debugger Banner and Version ]

        %DEBUG-I-INITIAL, language is FORTRAN, module set to WIDGET
        DBG>

      The FORTRAN and LINK commands both specify the /DEBUG qualifier
      to compile the program WIDGET.FOR with debugger symbol table
      information. The RUN command begins execution of the image
      WIDGET.EXE, which loops uncontrollably. Ctrl/Y interrupts the
      program, and the DEBUG/RESUME command gives control to the
      debugger.

    3.$ CC/DEBUG/NOOPTIMIZE ECHOARGS
      $ LINK/DEBUG ECHOARGS
      $ ECHO == "$ sys$disk:[]echoargs.exe"
      $ DEBUG/KEEP

                         [ Debugger Banner and Version ]

      DBG> RUN/COMMAND="ECHO"/ARGUMENTS="fa sol la mi"
      %DEBUG-I-INITIAL, language is C, module set to ECHOARGS
      %DEBUG-I-NOTATMAIN, type GO to get to start of main program
      DBG>
         .
         .
         .
      DBG> RERUN/ARGUMENTS="fee fii foo fum"
      %DEBUG-I-INITIAL, language is C, module set to ECHOARGS
      %DEBUG-I-NOTATMAIN, type GO to get to start of main program
      DBG>
         .
         .
         .
      DBG> RUN/ARGUMENTS="a b c" ECHOARGS
      %DEBUG-I-INITIAL, language is C, module set to ECHOARGS
      %DEBUG-I-NOTATMAIN, type GO to get to start of main program
      DBG>

      The CC and LINK commands both specify the /DEBUG qualifier
      to compile the program ECHOARGS.C with debugger symbol table
      information.

      The symbol definition command defines a foreign command for use
      during the debugging session.

      The DEBUG/KEEP command invokes the kept debugger.

      The first RUN command uses the /COMMAND qualifier to specify
      a foreign command to invoke the image file and the /ARGUMENTS
      qualifier to specify a string of arguments.

      The RERUN command reinvokes the same image file and uses the
      /ARGUMENTS qualifier to specify a new string of arguments.

      The second RUN command specifies a new image file and a new
      string of arguments.

    4.$ PASCAL/DEBUG/NOOPTIMIZE 8QUEENS
      $ LINK/DEBUG 8QUEENS
      $ DEFINE/USER/NAME=CONFINE LIBRTL SYS$LIBRARY:LIBRTL_INSTRUMENTED
      $ RUN/NODEBUG 8QUEENS

              [Heap Analyzer window is displayed]

      The PASCAL and LINK commands both specify the /DEBUG qualifier
      to compile the program 8QUEENS.PAS with debugger symbol table
      information.

      The DEFINE command causes the Heap Analyzer to access a
      version of LIBRTL designed to collect memory allocation and
      deallocation information.

      The RUN/NODEBUG command invokes the Heap Analyzer but not the
      Debugger.

    5.$ DEBUG/SERVER=(PROTOCOLS=(TCP_IP,DECNET))

      %DEBUG-I-SPEAK: TCP/IP: YES, DECnet: YES, UDP: NO
      %DEBUG-I-WATCH: Network Binding: ncacn_ip_tcp:16.32.16.25[1112]
      %DEBUG-I-WATCH: Network Binding: ncacn_dnet_nsp:63.1004[RPC20A020DD0001]
      %DEBUG-I-AWAIT: Ready for client connection...

      The DEBUG/SERVER command establishes a connection to the debug
      server, requesting network protocols TCP/IP and DECnet. Note
      that the binding strings are saved in file TEMP.TMP. You can
      use the TYPE command to display the contents of TEMP.TMP.