The following topics are covered below:
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.
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 .
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:
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.
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).
To debug a Natural RPC application
Open the source editor for one of the subprograms which is invoked by the main program and set at least one breakpoint.
In the Navigator view or in the Natural Navigator view, select the main program.
Invoke the context menu and choose .
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 , you return to the debugging session for the main program.
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.
To debug an external Natural application
Open the source editor for a Natural program which belongs to the application and set at least one breakpoint.
In the Navigator view or in the Natural Navigator view, select the Natural project.
Invoke the context menu, choose and then specify a custom client ID. See also Debug Attach Settings in Changing the Project Properties.
Invoke the context menu for the Natural project once more and choose .
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.
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.
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 .
Note:
If you do not choose the above command, the application
is automatically removed from the debug attach server when you exit NaturalONE.