Running an xfServerPlus session in debug mode from xfNetLink .NET

During normal operation, xfServerPlus runs as a background process without support for console operations, complex user interfaces, or debugging. This improves efficiency and minimizes memory requirements. However, there may be times when you need to run the debugger on Synergy code in the ELBs that are being called from xfServerPlus. By manually connecting an xfServerPlus session to your .NET client application, you can run your Synergy server routines in debug mode so that you can uncover problems that are showing up as errors in your distributed application.

Note

If the operating system of your xfServerPlus machine is Windows or UNIX, we recommend you use the Telnet method for debugging. See Debugging remote Synergy routines via Telnet for instructions.

Running in debug mode on Windows and UNIX

Use this procedure if the operating system of your xfServerPlus machine is Windows or UNIX.

If your SMC files or xfpl.ini file are not in the default location (DBLDIR), you will need to either move them to DBLDIR or set XFPL_SMCPATH and XFPL_INIPATH in the environment to point to the location of the files before starting xfpl.dbr (step 4 below). (When XFPL_SMCPATH and XFPL_INIPATH are set in the registry or synrc, they are read by rsynd. Since rsynd is bypassed when you run in debug mode, the registry/synrc settings do not get read.)

1. Use the debugInit() method to initiate a debug session. This method binds an IP address and port number for listening, and then returns the IP and port. You need to include code that displays the IP address (in hex) and port on the screen.

For example, in C#:

// declare variables
string listen_ip = "";
int listen_port = 0;
// instantiate object and make call
AppLogin userSess = new AppLogin();
userSess.debugInit(ref listen_ip, ref listen_port);
// display hex IP and port
Console.WriteLine ("IP = "+ listen_ip +" Port = "+listen_port);
Note

If you are debugging through a firewall, you may need to specify a port number range, and then open that range of ports on your firewall. To do this, manually edit the application configuration file to include the following lines within the <xfnlnet> section of the file:

<add key="minport" value="####" />
<add key="maxport" value="####" />

where #### is a port number greater than 1024, with maxport greater than minport.

Note that these settings are not used by an ordinary connection; they are used only when running in debug mode and, consequently, have been removed from the xfNetLink .NET Configuration Utility.

2. When the IP and port display on the screen, write them down. You’ll need them in step 4. For example:
IP = 6F16212C
Port = 1082
Important

Once the IP address and port display on the screen, you have a limited amount of time in which to manually start xfServerPlus in debug mode on the server machine, specify a breakpoint, and type “go”. The default time‑out for debug mode is 10 minutes. You can change this value by setting the connect time‑out value in the xfNetLink .NET Configuration Utility. See Creating and editing configuration files.

3. Use debugStart() to complete the connection process:
userSess.debugStart();

At this point, the client application has opened a socket and is waiting for the server to call it back.

4. Go to the machine running xfServerPlus, start xfpl.dbr, and pass the IP and port to xfServerPlus. Type the alpha characters in the IP address in uppercase.
dbr ‑d xfpl hexadecimal_ip listen_port

For example:

dbr ‑d xfpl 6F16212C 1082

xfServerPlus starts up in the debugger window.

5. Set an initial breakpoint in the xfpl program at the XFPL_DEBUG_BREAK routine. In the debugger enter
break xfpl_debug_break

and then enter

go

xfServerPlus is now connected to the client on the specified port. The server waits while the client program resumes and makes its first call. The program will then break at the XFPL_DEBUG_BREAK routine. This breakpoint occurs just after xfServerPlus has opened the ELB for the first method called by your application. (Note that any ELBs linked to this ELB will also be opened.) The ELB must be opened before you can set breakpoints in the routines within it.

6. If the Synergy routine you need to debug is in one of the opened ELBs, just specify a breakpoint in that routine. If the routine you want to debug is in a different (unopened) ELB, use the OPENELB debugger command to open that ELB. (You can also continue running your client application until the ELB is opened by xfServerPlus. However, because you set a breakpoint at XFPL_DEBUG_BREAK, it will break at each method call, so using the OPENELB command is more efficient.)
Note

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

Running in debug mode on OpenVMS

Use this procedure if the operating system of your xfServerPlus machine is OpenVMS.

1. Make sure xfServerPlus is running on an unused port. If necessary, restart it to ensure that it’s using an unused port.
Note

Remember, the account used to run xfServerPlus sessions must have the SHARE privilege. If you use a different account when running in debug mode, make sure it has this privilege.

2. On the machine running xfServerPlus, enter
$ run DBLDIR:xfpld

You’ll see output similar to the following:

*******************************
*** DEBUG 10.3.1   ***
BREAK AT 152 IN XFPL (LAUNCHER.DBL;6) ON ENTRY
%DBG‑E‑Could not open source file "LAUNCHER.DBL;1"
DblDbg>
*******************************
Tip

If you have created shared image logicals for the shared images used by xfServerPlus, you can skip step 3. Instead, set a breakpoint for your shared image and routine as described in step 6. You’ll then be prompted for the port number (step 4). Once you start your client program (step 5), the debug session will break at the breakpoint you set.

3. Set an initial breakpoint in the xfpl program at the XFPL_DEBUG_BREAK routine. In the debugger enter
break xfpl_debug_break

and then enter

go
4. When prompted, enter the port number that xfServerPlus is running on (from step 1).
5. Start your client application in the usual manner. After xfNetLink connects, the debug session will break at the XFPL_DEBUG_BREAK routine.
6. Set a breakpoint for your Synergy shared image and routine:
break image/routine

and then enter

go

For details, see the BREAK debugger command.

Note that if you set a breakpoint at XFPL_DEBUG_BREAK, the debugger will break at XFPL_DEBUG_BREAK for each method call your client makes.    

Note

Although you do not need to use the OPENELB debugger command before setting the first breakpoint in your shared image, you may need to use it if your code does an XSUBR or RCB_SETFNC without specifying a shared image.