Running an xfServerPlus session in debug mode from xfNetLink Java

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 or shared images that are being called from xfServerPlus. By manually connecting an xfServerPlus session to your running Java application, you can run your Synergy routines in debug mode so that you can uncover underlying 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.)

Note

If your client application uses JavaServer Pages, you will need to use two JSP pages to run in debug mode. Use the first page to make the call to debugInit() and return the HTML that displays the IP and port. Then, you’ll need a second page with the debugStart() call. After submitting the second page, the client will go into wait mode while you start xfServerPlus.

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:

//instantiate objects
AppLogin appLog = new AppLogin();
string clientIP = new String("tiger");
StringBuffer listHost = new StringBuffer("");
StringBuffer listPort = new StringBuffer("");
//make call
appLog.debugInit(clientIP, listHost, listPort);
//display hex IP and port
System.out.println("IP = " + listHost.toString());
System.out.println("Port = " + listPort.toString()); 
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 so, call the setxfMinport() and setxfMaxport() methods in your client application prior to calling debugInit(), passing as parameters the port numbers for the range. Valid values are greater than 1024, with maxport greater than minport.

These methods are deprecated because they are not used by an ordinary connection; they are used only when running in debug mode. They are still included in your JAR file, but no longer documented in this manual.

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, etc. displays on the web server 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”. This time is controlled by the xf_DebugSessionConnectTimeout setting in the xfNetLink Java properties file (see Connect session time-out). If no time-out is specified, the default value of 10 minutes applies. If you delay longer than the time-out value, SWPConnect will time out while waiting for a response from xfServerPlus.

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

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 hexadecimal IP address 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 Synergy debugger.

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 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, the program 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.