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.

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.)

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()); 

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 

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.)

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.

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>
*******************************

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.      

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.