Using a Debug Attach Server

The following topics are covered below:


General Information

The debug attach server is only available for Windows. It is delivered with the local Natural runtime of NaturalONE and with Natural for Windows as of version 6.3.13.

In order to debug workplace applications (that is, Natural for Ajax pages of type MFPAGE), Natural RPC applications or other external Natural applications, a debug attach server is required. The debug attach server acts as a broker between the NaturalONE clients and the attachable sessions. It enables the NaturalONE debugger to attach to a running application and links the debugger with the appropriate Natural runtime.

Debug overview

The debug attach server must be accessible to all NaturalONE clients and to all executing Natural sessions that want to participate in debugging.

  • Preparing the NaturalONE client
    To enable debugging for a NaturalONE client, you have to enable the debug attach server in the Natural preferences of NaturalONE, and you have to specify the appropriate settings (host name and port number). See Debug Attach Settings in Setting the Preferences.

    All relevant sources for the application to be debugged must be contained in a Natural project. For example, you can download the sources from a Natural server into a Natural project, or you can check out the sources from your version control system.

    A Natural source is registered on the debug attach server if it contains a breakpoint. You have to set at least one breakpoint in the source with which you want to start your debug session.

    When you debug an application from within NaturalONE (that is, a workplace application or Natural RPC application), the sources containing the breakpoints are automatically registered.

    If you want to debug an external Natural application (that is, an application that is started, for example, with Natural for Windows), you have to register the sources containing the breakpoints explicitly using the command Activate Debug Attach.

  • Starting the Natural runtime in debug attach mode
    The Natural runtime to be debugged has to be started in debug attach mode.

    When you debug an application from within NaturalONE (that is, a workplace application or Natural RPC application), this mode is set automatically.

    If you want to debug an external Natural application (that is, an application that is started, for example, with Natural for Windows), you have to set the debug attach mode explicitly using the Natural profile parameter DBGAT.

At runtime, when a registered breakpoint is hit during the execution of the application, a debugging session for the corresponding Natural runtime is launched and you can debug as described in Debugging Natural Applications.

All Natural objects that have been registered for a specific client are automatically removed from the debug attach server when you exit NaturalONE.

Notes:

  1. The debug attach server uses a client ID to manage its attach records. It is recommended that you always use the unique client ID which is automatically generated. However, if you want to debug an external Natural application or, if necessary, for testing purposes, you can manually define a custom client ID in the properties of a project. See Debug Attach Settings in Changing the Project Properties.
  2. How to debug Natural RPC applications and external Natural applications is described below. For information on how to debug workplace applications, see Executing and Debugging Workplace Applications in the Natural for Ajax documentation.

Starting the Debug Attach Server

It is not required that each NaturalONE client starts its own debug attach server. It is sufficient to start one debug attach server which can be accessed by all NaturalONE clients, even if the clients run on different machines. It is only required that all NaturalONE clients define the appropriate debug attach settings in the Natural preferences.

The debug attach server is started using natdas.exe. You can find this program in the \naturalone\natrun\bin folder of your NaturalONE installation.

The syntax for starting the debug attach server is the following (the elements contained within the square brackets are optional):

natdas [-p port-number] [-o file-name]

where port-number is the number of the listener port, and file-name is the name of your trace file.

If you do not specify any parameters when starting the debug attach server using natdas.exe, the default port 2500 is used.

If you want to use a port other than the default port, or if you want to create a trace file, you have to specify additional parameters. For example:

natdas -p 9999 -o c:\temp\natdas.log

If you want to start the debug attach server using a Windows shortcut, you can specify the parameters as shown in the following example:

D:\SoftwareAG\NaturalONEnn\naturalone\natrun\bin\natdas.exe -p 9999 -o c:\temp\natdas.log

When you specify that a trace file is to be created and if a trace file with the same name already exists, the existing file is overwritten.

Debugging a Natural RPC Application

A Natural RPC application switches to a different Natural runtime environment.

The following steps assume that you have already created a Natural project containing the relevant sources for the Natural RPC application in NaturalONE (for example, a main program which invokes two subprograms using the CALLNAT statement).

Start of instruction setTo debug a Natural RPC application

  1. Open the source editor for one of the subprograms which is invoked by the main program and set at least one breakpoint.

  2. In the Project Explorer view or in the Natural Navigator view, select the main program.

  3. Invoke the context menu and choose Debug As > Natural Application.

    Or:
    Press ALT+SHIFT+D, N.

    Or:

    The main program is now started in debug mode. You can use the Debug perspective as described in the section Debugging Natural Applications.

    When the first breakpoint which has been set in the subprogram is reached, the main debugging session turns into wait state. Since the RPC is executed on a different machine, a new debugging session is launched and debugging stops on the breakpoint.

    With Step Return, you return to the debugging session for the main program.

Debugging an External Natural Application

If you want to debug a Natural application that is started outside of NaturalONE (for example, a batch application which is started with Natural for Windows or UNIX), you have to start the application using the Natural profile parameter DBGAT. This parameter specifies the client ID to be used, and the name and port of the debug attach server. For detailed information, see the description of the DBGAT parameter in the Natural documentation for the appropriate platform.

The following steps assume that you have already created a Natural project containing the relevant sources for the Natural application in NaturalONE.

Start of instruction setTo debug an external Natural application

  1. Open the source editor for a Natural program which belongs to the application and set at least one breakpoint.

  2. In the Project Explorer view or in the Natural Navigator view, select the Natural project.

  3. Invoke the context menu, choose Properties and then specify a custom client ID. See also Debug Attach Settings in Changing the Project Properties.

  4. Invoke the context menu for the Natural project once more and choose NaturalONE > Activate Debug Attach.

    This command registers the existing breakpoints in the debug attach server.

    Note:
    This command is only visible when the debug attach server has been enabled in the Natural preferences.

  5. Go to your external Natural application and start it using the DBGAT parameter.

    Important:
    The parameters for the host name and port number that have been specified for the external Natural application using the DBGAT parameter must be the same as defined in your Natural preferences. The client ID that has been specified with the DBGAT parameter must be the same as in your project properties.

    When the program in which the breakpoint has been set is about to be executed inside the corresponding Natural session, the debugger is launched and the application stops at the first breakpoint. You can now use the Debug perspective as described in the section Debugging Natural Applications.

  6. If you do not want to continue debugging, you have to remove the application from the debug attach server. To do so, select the Natural project, invoke the context menu and choose NaturalONE > Deactivate Debug Attach.

    Note:
    If you do not choose the above command, the application is automatically removed from the debug attach server when you exit NaturalONE.