Error messages may not always provide enough information to diagnose a problem. When such is the case, you can take advantage of the additional debugging options provided with xfNetLink and xfServerPlus. You may also want to run the test program; see Testing xfNetLink Synergy
Running an xfServerPlus session in debug mode from xfNetLink Synergy
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 Synergy 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.
When running in debug mode, you have the option of logging the packets sent from and received by the client. You can display them on screen or write them to a file. See Viewing packets on the client side.
|
If you do not need to view packets on the client side and the operating system of your xfServerPlus is Windows or Unix, we recommend that 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 in step 4 below. (Note: 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 %RX_DEBUG_INIT function to initiate a debug session. This routine binds a port number and IP address for listening, and then returns the port, IP, and a network connection ID. You need to include code that displays the IP address (in hex) and port on the screen. For example: |
status = %rx_debug_init(netid, ip, port) writes(output_chan, "IP address is " + %hex(ip)) writes(output_chan, "Port number is " + %string(port))
| 2. | When the IP and port display on the screen, write them down. You’ll need them in step 4. For example: |
IP address is 6F16212C Port number is 1082
|
Once the IP address, etc. displays on the screen, you have a limited amount of time in which to manually start xfServerPlus in debug mode, specify a breakpoint, and type “go”. This time is controlled by the variable XF_RMT_DBG_TIMOUT (see Connect session time-out) or by passing a session time-out value when you make the call. If no time-out is specified, the default value of 10 minutes applies. If you delay longer than this, xfNetLink will time out while waiting for a response from xfServerPlus. |
| 3. | Use %RX_DEBUG_START to complete the connection process. Be sure to pass the same net ID that was returned by the corresponding %RX_DEBUG_INIT routine. For example: |
status = %rx_debug_start(netid)
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 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 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, the program will break at each method call, so using the OPENELB command is more efficient.) |
|
|
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 a new, unused port. |
|
|
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> *******************************
|
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 (i.e., execute %RX_START_REMOTE). After it 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. |
Viewing packets
At times, it may be helpful to see the complete packets sent back and forth between the client application and xfServerPlus. You can view packets on either the client side or the server side.
|
|
What’s the difference between the packets viewed on the client side and those viewed on the server side? If everything is working properly—nothing. The debug trace option (client side) allows you to view packets as they look when sent from and received by xfNetLink Synergy. The xfServerPlus log (server side) allows you to view packets as they look when received by and sent from xfServerPlus. Under normal circumstances they should be the same. Having these two ways to view the information is primarily for your convenience in troubleshooting. |
Viewing packets on the client side
The debug trace option allows you to view the actual packets that are sent and received on the client side. This option is available only when running in debug mode (see Running an xfServerPlus session in debug mode from xfNetLink Synergy).
If encryption is enabled, the log will display a string of 10 asterisks instead of the actual data for packets that contain encrypted data.
|
|
You cannot view packets on the client if you have an OpenVMS server. However, OpenVMS users can view packets on the server side in the xfServerPlus log. See Using server-side logging. |
To activate the debug trace option, set the trace_flag argument to ‘1’ when you call the %RX_DEBUG_START routine. By default, the packets are printed to the screen of the client machine. To write them to a file, pass a filename in the %RX_DEBUG_START call or specify the XFNLS_LOGFILE variable in the synergy.ini file (or as an environment variable on Unix).
As shown in the sample below, the connection information prints once for each session; sent and received data prints for each call.
------------------------------------------------------ Local host: tiger XFPL connection port: 1217 Call timeout = 1800 seconds Session timeout = 600 seconds ------------------------------------------------------- send: size = 166 Dxfpl_tst2;10;ID13#1234567890.12;ID10#12345.6789;ID10#12345.6789; ID11#12345678.91;DE10#1234567890;ID8#0.123456;ID6#1.2345;DE8#12345678; ID8#123456.7;DE9#123456789; recv: size = 107 Rxfpl_tst2;005;001ID14#1234567891.12;002ID7#333.334;006ID9#0.9988332; 008DE9#-88991010;009ID8#654321.0; send: size = 9 S;0;;
Viewing packets on the server side
The xfServerPlus log shows you the packets that are received by and sent from xfServerPlus. To record packets in the xfServerPlus log, set the XFPL_DEBUG option to ON in the xfpl.ini file. See XFPL_DEBUG for details on what information is recorded in the log.
