Greenfield Technologies

Your Progress OpenEdge Database Expert

Debugging Progress 4GL Character Sessions

The New Debugger

Progress rolled out a powerful upgrade to the 4gl debugger in the 9.1d05 service pack. Unfortunately most of the documentation and demos of the new debugger concentrate on using it within the context of a Windows PC -- leaving the impression that it is only usable in those environments. However, one of the most powerful and useful features of this new debugger is its ability to attach to and debug a remote process -- including the capability of debugging UNIX character sessions.

The debugger GUI is a Java program and can be run on either a Windows PC or in an X Windows session. You do not need to have a Windows PC to run the debugger.

Preparing to Debug

To use the attachable debugger against a UNIX character session you must have the debugger installed on the server as well as on the client that runs the GUI. Check $DLC/bin for _prodebug. If you don't have it you need to get it. It should come by default in OE10.

$ ls -l $DLC/bin/*[dD]eb*
-rwxr-xr-x  1 root root 36878 2004-05-12 19:37 /home/pro10b/bin/_debugConfig
-rwx------  1 root root 33956 2004-05-12 19:37 /home/pro10b/bin/_debugEnable
-rwxr-xr-x  1 root root   615 2004-05-26 09:24 /home/pro10b/bin/proDebugConfig
-rwxr-xr-x  1 root root   615 2004-05-26 09:24 /home/pro10b/bin/proDebugEnable
-rwxr-xr-x  1 root root  3489 2004-05-26 09:24 /home/pro10b/bin/proDebugger

proDebugEnable & _debugEnable-- makes the system, as a whole, ready for attachable debugging. You must be root to run this.

proDebugConfig & _debugConfig -- selects a specific process for debugging, makes it ready and assigns a port. Any user can run this. If the process being attached to is not yours and you are not root you will receive an error.

proDebugger is a script that starts the Java debugger. On UNIX this will start as an X Windows process.

(For some reason these files are missing from my v9 install. I haven't figured out what to do to obtain it for v9 yet. I thought that it was in a service pack somewhere along the line but apparently not. If and when I figure that out I'll post an update. Current thinking on PEG is that you need to have a debugger license to have it for v9.)

This may not be necessary but -- make sure you know where Java is installed. I had to modify $DLC/bin/java_env and replace the line which defines JDKHOME for my OS (which is Linux) with one which respects the environment variable if it already exists. Like so:

    # JDK_HOME=/usr/java/jre1.3.1_06
      JDK_HOME=${JDK_HOME-/usr/java/jre1.3.1_06}

I then found it helpful to do the following prior to running any commands:

    export JDKHOME=$JAVA_HOME
    export JREHOME=$JAVA_HOME

The JAVA_HOME variable was already correctly defined in my environment. (SUSE Linux 9.0)

You may, or may not, need to do this. If your Java really is where Progress thinks that it should be then you're probably ok. If the *Debug* commands are complaining that Java isn't where it should be then this might be your cure.

Next you need to enable attachable debugging. You need to be root to do this:

    $DLC/bin/proDebugEnable -enable-all

It is not necessary to do this ahead of time -- the _progres session can already be actively running (I tested that.) Having debugging enabled at all times is a potential security problem so you may not want to do this until you have a need.

It is not clear if simply enabling debugging has any performance impact. I suspect that it does NOT. The documentation does reference polling a socket as a performance impact but the way I read that they are referring to a session which has been attached to -- not sessions that could be attached to but have not yet been.

I did not try it but setting proDebugEnable setuid to root might work if you don't want to leave it on all the time but are not concerned with the security implications.

A more sophisticated security model should probably be developed.

"-enable-all" seems to imply that "-enable" something less than all might be an option. But the obvious option of specifying a particular PID does not appear to work.

Debugging a Session

Launch a _progres session and run some code. You can be any user. Obtain that session's PID.

I didn't do anything special to make the code or listing visible -- but my test program was:

    do while lastkey <> 4:
      readkey.
      display keyfunction( lastkey ).
    end.

and I just dumped it in my home directory. It worked flawlessly. I suspect that remote debugging needs to be able to find some code somehow or other. The rules are not clear to me at this time.

Launch a debugger session. Here's something cool -- that session can be on a remote windows PC *or* it can be an X session on the local UNIX box! I haven't tried it but I see no reason why a an X session couldn't attach to and debug a remote progress -- perhaps even one running on a Windows laptop ;-) To launch a local X debugger session:

    $DLC/bin/proDebugger

I used the X session because my firewall isn't configured to let the debugger port through. If you get timeouts on your Windows box after entering a correct server and port then you probably need to open up a firewall somewhere.

If you are debugging remotely -- on the UNIX box run:

    $DLC/bin/proDebugConfig

This utility will prompt you for the target PID and provide the port number. You will need the port number for the debugger GUI.

If you are debugging a local process you do not need to run proDebugConfig although it does no harm if you do.

In your debugger session select the "debug" menu and the "attach to process" option.

If you are debugging a "local" process you can specify the PID and leave the port 0. Progress will pick a port for you.

If you are debugging remotely fill in the server name or IP address and port number.

If the process being debugged is blocking on IO you will receive a message to that effect when you attach to the process. You must satisfy the IO request (often a keystroke) in order to finish attaching to the process and set up your debugging session.

That's it! Start debugging!

Open Issues

A) When you leave port choice to the debugger how does it pick ports? Are there startup parameters to control the port range so that firewalls can be properly setup ahead of time?

B) What are the rules regarding source listings? Which process needs to be able to see them? How must the be arranged or prepared? Are they actually even necessary?

C) What about v9? Is it installed by default in any release of v9? Or is it a download? Is a "debugger" license required?

D) Yes, it's perverse, but can you use the debugger in an X session to debug a Windows Progress session?

E) Security of proDebugEnable needs to be addressed. Having to be root (or call the sysadmin) is not a good thing.

F) Will proDebugEnable eventually support options other than "all"?