Debugging your remote Synergy routines

During normal operation, xfServerPlus runs as a background process (using the dbs runtime) without support for console operations such as the Synergy debugger. This improves efficiency and minimizes memory requirements. However, you may at times need to debug the Synergy routines in the ELBs that are called from xfServerPlus.

If you are running xfServerPlus on Windows or UNIX, there are three methods for debugging remotely: running an xfServerPlus session in debug mode, debugging in Visual Studio, and debugging via Telnet. If you have access to Visual Studio and and are familiar with its debugger, we recommend that method; otherwise, debugging via Telnet with the Synergy debugger is the recommended method.

If your client is xfNetLink Synergy and you want to view packets on the client side, you must run an xfServerPlus session in debug mode; neither the Telnet method nor debugging with Visual Studio support this feature. (Note that you can always view packets on the server side in the xfServerPlus log.)

If you are running xfServerPlus on OpenVMS, there is only one debug method available: running an xfServerPlus session in debug mode.

(Windows) When debugging Synergy routines using any of the methods described here, xfpl.dbr uses the regular runtime (dbr) instead of the non-interactive runtime (dbs). This means that your environment may change, because dbr always reads the synergy.ini file, whereas dbs reads it only when SFWINIPATH is set. We recommend that you use SFWINIPATH to point to the location of your synergy.ini file and thereby avoid potential problems. For more information on dbs, see Non-interactive runtimes.

Running an xfServerPlus session in debug mode

To run an xfServerPlus session in debug mode, you will need to alter your xfNetLink client code to call a special debug initialization method, start the client application, and then manually connect an xfServerPlus session to it. (On OpenVMS, you do not need to alter your client code.)

If you have a Java or .NET client that uses pooling, the pool will simply be ignored when you run an xfServerPlus session in debug mode because your application will be using the session that you start manually. However, you should verify that the pool isn’t using all available xfServerPlus licenses before you begin debugging.

The instructions for using this method vary slightly from one client to the next; refer to the topic for your client:

Debugging remote Synergy routines via Visual Studio

This method of debugging enables you to use the Visual Studio debugger rather than the Synergy debugger when xfServerPlus is on Windows or UNIX. The machine running Visual Studio may be the xfServerPlus machine, the xfNetLink client machine, or a separate machine.

To debug your remote routines in Visual Studio, you will first need to start xfServerPlus with remote debugging enabled. Starting rsynd in this manner causes it to start the xfpl.dbr session using the dbr -rd command. Then you’ll start your xfNetLink client application. Once the xfNetLink–xfServerPlus connection is made, you’ll complete the setup through a dialog in Visual Studio.

For detailed instructions see Remote debugging.

Debugging remote Synergy routines via Telnet

You can debug remote Synergy routines via Telnet when xfServerPlus is on Windows or UNIX. The Telnet method uses the Synergy debugger, but does not require that you modify your client code as does running in debug mode. The machine running the Telnet session may be the xfServerPlus machine, the xfNetLink client machine, or a separate machine.

To debug your remote routines via Telnet, you will need to do the following:

Start xfServerPlus with remote debugging enabled. Starting rsynd in this manner causes it to start the xfpl.dbr session using the dbr -rd command.
Start your xfNetLink client application.
Once the xfNetLink–xfServerPlus connection is made, you’ll start the Telnet session and access the server, then debug as usual. See below for detailed steps.

If there is a firewall between your Telnet client and xfServerPlus, the firewall must be configured to allow Telnet access on the debug port number. (Most firewalls are configured to prohibit Telnet access.) If you do not have authorization to reconfigure the firewall, you can either run Telnet on a machine within the firewall or use another debug method.

If your Java or .NET client uses pooling, you should set both the minimum and maximum pool size to 1 before using Telnet debugging.

On the xfServerPlus machine, restart the xfServerPlus session with remote debugging enabled (or, you can start a completely new session on a different port if desired).

On Windows, run the Synergy Configuration Program.
On the xfServer/xfServerPlus tab, select the desired xfServerPlus service and click the Modify Service button.
Select “Enable remote debugging”, specify a debug port number for the server to listen on for the Telnet client, and indicate a time-out value, if desired. The default is 100 seconds. This time-out measures how long the server will wait for a Telnet connection after the xfNetLink–xfServerPlus connection has been established. It should always be less than the connect time-out set on the client, which defaults to 120 seconds.
Click OK, and then click the Apply button on the xfServer/xfServerPlus tab. xfServerPlus will be restarted with debug enabled.

For details on using the Synergy Configuration Program, see Starting xfServerPlus from the Synergy Configuration Program or refer to the Synergy Configuration Program online help.

On UNIX, stop the current xfServerPlus service, and then restart it with the -rd option:

rsynd -rd debug_port[:timeout] -w -u xfspAcct

where debug_port is the port number that the xfServerPlus machine should listen on for the Telnet client, and timeout is the number of seconds that the server should wait for a Telnet connection after the xfNetLink–xfServerPlus connection has been made. The default is 100 seconds. This time-out should always be less than the connect time-out set on the client, which defaults to 120 seconds. Include any other command line options that you normally use when starting xfServerPlus.

For more information about starting xfServerPlus, see Running xfServerPlus on UNIX. For complete rsynd syntax, see rsynd program.

Run the xfNetLink client application so that a connection is made to xfServerPlus.

Start a Telnet session and connect to the xfServerPlus machine by specifying the server’s IP address (or “localhost” if you are running the Telnet session on the xfServerPlus machine) and the debug port that you specified in step 1. You can use whatever Telnet application you prefer. The xfServerPlus machine becomes the “debug server”, and the Telnet session becomes the “debug client”. The debug prompt is sent to the Telnet session window.

Once the Telnet session has connected, the remote debug session works just like any other Synergy debug session. You will need to use the OPENELB debugger command to open the ELBs containing your Synergy routines before setting a breakpoint in one of those routines. Any ELBs linked to the opened ELB will also be opened.

Because the xfpl.ini file will not have been read at this point, you cannot use logicals in the file specification used with OPENELB; you must use the full path instead.

For general information about the Synergy debugger, see Debugging Synergy Programs.

When your distributed application finishes and the xfServerPlus connection to xfNetLink is closed, the Telnet session will also close. Optionally, you can use the QUIT or EXIT commands to close the debugger. Shutting down the Telnet session while in the midst of debugging will cause the application to continue running normally, without debugging enabled.

When you are through debugging, run the Synergy Configuration Program, or restart rsynd without the -rd option, to turn off remote debugging. If you leave remote debugging enabled, the server will always wait for the specified time-out before continuing with the application.

Time-outs or other failures are logged to a file named rd.log, which is created in the DBLDIR directory (or the TEMP directory on Windows) when the first entry in the file is logged. This file contains the process ID of the instance of the runtime that logged entries, the date and time entries were logged, and specific messages. If you are having a problem debugging remotely, check this file first.

(Windows) If the TEMP logical is not set in the Synrc node in the Windows registry, rsynd will put the log file in a system-defined location, most likely somewhere in the c:\Users path. We recommend that you use the Synergy Configuration Program to explicitly set TEMP in the registry for remote debugging. (Remember that rsynd only reads environment variables set in the registry, not the environment.)