Debugging A REMOTE PROCEDURE

for now, this guide assumes you are running the xinetd program with GT.M on Linux. It will need to be updated for any other configuration.

Since the RPC Broker normally runs in the background (with no terminal or screen attached), one way to debug a REMOTE PROCEDURE is run in the foreground to use the MUMPS debugger for the RPC Broker.

The First Step is decide which port your CPRSCHART.exe will use to connect to your RPC Broker.

1) Use the same port as you usually use to connect to your VistA system. For the sake of this discussion, let us say this is running on port 9100. Using the same port has the advantage that you don't have to change your shortcuts to CPRS, and you don't have to open another port on a virtual machine, which sometimes requires rebooting the VM. One of the disadvantages of using the same port is that this really only is useful if only one person is using CPRS at a time. This is because the debugging entrypoint (DEBUG^XWBTCPM) is a single listener application and doesn't allow multiple connections at the same time.

a) First you need to make sure that a program is listening to the port 9100.

The command is: sudo netstat -anp | grep 9100
The output could be: tcp        0      0 0.0.0.0:9100            0.0.0.0:*               LISTEN      3949/xinetd

This is running the netstat program as root (sudo), which allows the output to include the process id and program name (the 3949/xinetd above). The text 0.0.0.0.0:9100 specifies that xinetd is looking for any activity on any of the network addresses currently being used by this machine. The text 0.0.0.0:* means that xinetd is not limiting what machine can connect, nor what port the connecting machine is using to connect to this one (on port 9100). The grep command specifies which port number to look for in the output because the 'n' is in the netstat option list of '-anp' none of the names for ports are used and only the numeric values are output.

b) Next, you need to edit the port configuration file which xinetd is using to control itself. This is done by searching the directory used by xinetd (i.e. /etc/xinetd.d )

The command is: grep 9100 /etc/xinetd.d/* | grep 'port'
the output could be: /etc/xinetd.d/cprs-gui-9100:        port = 9100

The output means that the file named 'cprs-gui-9100' and that the configuration includes important information that port for xinetd to listen on is 9100. Now you need to edit that file. Be sure you have proper Linux user permissions to save it after you edit it. Look for a line which says:

disable = no

edit the line to disable the port configuration.

disable = yes

and then save the file from the editor.

c) The next thing to do is tell xinetd to review all its port configuration files and use the current information re whether a listener should run or not. Since we disabled the CPRS listener, the port 9100 will not come up when we run the netstat command.

 The command is: sudo /etc/init.d/xinetd restart
 There should not be any output.
 The command is: sudo netstat -anp | grep 9100
 There should not be any output.

d) At this point, the normal CPRS port has no RPC Broker program listening to it. If you used the CPRS shortcut at this time, you will get an error.

e) Now we need to start up our debugging RPC listener. To do this, get into the command line of the MUMPS system. Then we will start the listener. Usually, if you are just generally trying to understand how the RPC Broker works, you would put a breakpoint at the suggested entry points ie: 'SERV+1^XWBTCPM', 'MAIN+1^XWBTCPM' or 'CAPI+1^XWBPRS.' Since this document is about debugging a REMOTE PROCEDURE, look up the procedure in FILE 8994 and get the TAG and ROUTINE for that procedure. For example, the TIU DELETE RECORD remote procedure has TAG: DELETE and ROUTINE: TIUSRVP. You can list the current breakpoints to make sure it is there. Do this for each remote procedure you wish to include in the debugging. If you are debugging an error, you can use DO ^XTER to find the line of the error.

 At the  GT.M prompt the command is: ZBREAK DELETE^TIUSRVP
 There should not be any output, and the GT.M prompt will appear.

 At the  GT.M prompt the command is:  ZSHOW "B"
 The lines of breakpoints should be output
 You should see a line: DELETE^TIUSRVP

f) Now we actually start the debugging CPRS listener

 At the  GT.M prompt the command is: DO DEBUG^XWBTCPM
 The output should look like this:

Before running this entry point set your debugger to stop at
the place you want to debug. Some spots to use:
'SERV+1^XWBTCPM', 'MAIN+1^XWBTCPM' or 'CAPI+1^XWBPRS.'

or location of your choice.

IP Socket to Listen on: 

You would type 9100 into the prompt "IP Socket to Listen on

"

at this point you are running the broker in Foreground.

2) Use a port solely defined for debugging. This allows each developer to have her own RPC Broker, but requires a special form of the shortcut that has PORT=XXXX where the XXXX is replaced with the port used for this developer. For this example, 1234 is used.

  NOTE: (Edit later, include much the same instructions as above but using 1234 at the prompt "IP Socket to Listen on: " and not stopping the RPC Broker running on the regular port.

Second use CPRSCHART to connect to the proper port and look at the putty/terminal emulator session.

1) At this point, you should have used the ZBREAK command with the label/Tag/Routine name wherever we wish to start debugging (can get the name using D ^XTER), and then started the debugging CPRS broker using the DO DEBUG^XWBTCPM command

2) Run the CPRS till this breakpoint is encountered. Mumps would wait in the console.... so we shift from CPRS client system to server console/Putty When it occurs you should see something like this on your screen

 %GTM-I-BREAKZBA, Break instruction encountered during ZBREAK action

At M source location CAPI+1^XWBPRS

 %GTM-W-NOTPRINCIO, Output currently directed to device SCK$115322

At the GT.M prompt type the command

USE $PRINCIPLE

No output should occur, but now all WRITE and READ commands will talk to the principal MUMPS login terminal instead of the TCP/IP port

3) When the breakpoint is encountered, use the Debugging with GT.M page which lists the commands, such as

ZWRITE, ZSTEP INTO, ZSTEP OUTOF, ZPRINT @$ZPOS, Then you debug the process/code to see where it fails.

4) if you use the HALT command at the GT.M command prompt, you will stop the debugging RPC Broker.

5) On completion of debugging, change back the Listener port to the original port as before debug and restart the GT.M

a) edit the /etc/init.d/ file which says

disable = yes

edit the line to disable the port configuration.

disable = no

and then save the file from the editor.

b) restart xinetd using the command

sudo /etc/init.d/xinetd restart

In this please confirm the name of the file in which we need to change the port number and about point (e) .

Thank you once again for your valuable help.