IBM i > DEVELOPER > GENERAL

Service Entry Points Help Simplify CGI Debugging


Developers of CGI programs face two problems associated with multijob debug scenarios. First, it's often hard to find the job that you want to debug. Second, it's often difficult to get the job to stop where you want. These problems are particularly acute when debugging short-running CGI programs that run under one of many prestarted jobs and usually run for shorter periods.

To effectively debug CGI problems, many programmers have resorted to changing their code, inserting timing loops and developing other delays so they can gain control of their programs. With service entry points those days are over.

Service entry points provide a mechanism to locate the correct job and begin servicing it at the exact point the user desires. A service entry point is a line breakpoint that fires when the program isn't under debug. Covered by U.S. patent 6,658,650, service entry points utilize the single-level store architecture of the System i5* platform to provide an advanced feature that helps simplify CGI debugging. For details on getting the debugger, see the sidebar, "Obtaining the Graphical System Debugger."

Unlike other platforms, the System i5 server only loads a single copy of the program into memory regardless of how many users are running the program. Breakpoints are set by replacing instructions within the program with machine instructions that will cause a trap to occur. The breakpoint handler gets control and determines if the job encountering the breakpoint was the job that set the breakpoint. If so, the breakpoint is allowed to fire normally. If not, the breakpoint is ignored and an execution is allowed to proceed. This is how breakpoints are normally processed.

Service entry points, however, are different. A service entry point takes advantage of the fact that all jobs encounter the breakpoint whether or not they're under debug and provides a mechanism for the debugger to gain control of a job and begin to service it. Consider the CGI example in Code Sample 1, which is essentially the "Hello World" of CGI programs. Once this program is created and placed in the correct directory, it can be evoked from the browser (see Figure 1).

The first problem is that this program doesn't run very long. The second problem is that it's hard to determine which of several prestarted APACHEDFT jobs it will run in. With service entry points, all we need to know is where the program is located, that it will be run under the QTMHHTP1 user profile and we can debug it.

Creating a Service Entry Point

With service entry points, there are really two debug sessions involved: the debug session where the service entry point is set and the debug session that resulted from hitting the service entry point. Using the i5/OS* graphical system debugger, this program could be debugged using service entry points.

First, start a new debug session using the debug manager (see Figure 2). The goal is to start a debug session that will be used as a "job catcher." The program won't be debugged directly from this debug session, but this session will be used to catch and begin servicing the running CGI program.

Select "Start Debug" from the Debug pull-down menu. Select "Submit and debug program in batch job" in the "Select debug method" (see Figure 3). Press "OK."

Once the program source appears, set a regular breakpoint at the location where you desire your service entry point. Right-click on the breakpoint pointer to bring up a Breakpoint Properties dialog (see Figure 4). The breakpoint style box contains two possibilities: normal and service entry point. Make sure the breakpoint style is set to service entry point. Notice that a new User field appears and your current user ID is entered. (Note: This user ID is the one a job must be running under in order for the service entry point to fire.) For the CGI program, enter "QTMHHTP1" and press "OK." Notice that the breakpoint indicator arrow changes from a solid fill to ingredient fill, which indicates that the breakpoint is now a service entry point. Whenever this program is run in another job that's running under the user profile specified in the User field, the service entry point will fire, and the user will have the opportunity to begin servicing the job at that point in the program.

This is how it works. Run your CGI program from the browser command line. A dialog box will pop up over your debug session asking you if you wish to debug the program that encountered the service entry point (see Figure 5). Clicking yes starts a new debug session that will service the CGI program running whichever APACHEDFT job it ran in. The debugger will start debugging the CGI program at the point at which the service entry point was set (see Figure 6). That's all there is to it. You don't need to locate the correct Apache job or figure out how to hold the program. Service entry points handle all of this for you.

Service Entry Point User Profile Matching

As we saw on the Breakpoint Properties dialog box, a different user can be specified when establishing the service entry point. In general, if the user ID running the debug session has authority to service a job running under a second user ID, then the second user ID can be specified within the breakpoint dialog box. (In our example the second user ID was QTMHHTP1.)

Cary Bates is a senior software engineer with IBM. Cary can be reached at clbates@us.ibm.com.


comments powered by Disqus

Advertisement

Advertisement

2019 Solutions Edition

A Comprehensive Online Buyer's Guide to Solutions, Services and Education.

Are You Multilingual?

Rational enables development in multiplatform environments

IBM Systems Magazine Subscribe Box Read Now Link Subscribe Now Link iPad App Google Play Store
IBMi News Sign Up Today! Past News Letters