This month’s technical article is a contribution from Adam Flynn, an mrc-Productivity Series expert from our mrc UK office.
If you've ever had cause to debug an external object or an mrc application, then you'll know just how useful IBM's Interactive Source Debugger (ISDB) can be. By stepping through the source member, logic errors in your code can be identified and remedied quickly. ISDB is simple to use and is invoked through a single CL command, STRISDB.
Unfortunately, the ISDB doesn't work with the ILE environment and all mrc CGI applications are, by necessity, ILE programs. However, there is a method for debugging ILE programs, it just takes a little more work. Assume there is an mrc CGI application (retriever or maintainer) which makes use of an external object. The following steps describe how to use the built-in module source debugger to step through the external object source code.
1. The first task is to establish which job on the server is running your program. Open a browser, and visit the URL of the mrc CGI application. Go to a green screen command line and type WRKSBSJOB QHTTPSVR. There will be several active jobs within this subsystem. The quantity and names of these jobs will depend on how your HTTP server is configured. To find the relevant job, ignore any named ADMIN and any of type BATCH. For the remaining jobs place a 5 against each one in turn and then type 10 to display the job log. The job you are looking for should have a message near the top reading 'This is a CGI job for IBM HTTP server instance XXXXXXXX'. Press F18 to get to the bottom of the messages. If it is the correct job you should see some messages that relate to your mrc CGI application such as 'Library MRCAPPLLIB added to library list' or 'Library MRCAPPLLIB already exists in library list'. Place the cursor on one of the messages, press F1, and check that the time corresponds to the time you visited the URL in the browser. Make a note of the job name, user and number.
2. The next task is to start servicing the job you identified in step 1. Type STRSRVJOB and prompt it with F4. Now enter the job name, user and number you noted in step 1, and press Enter.
3. Now place the program you are going to step through into debug mode. You can debug either the mrc CGI application or the external object (or both). Type STRDBG PGM(libname/pgmname) DSPMODSRC(*YES) and press Enter. Your source code should now appear on screen. If it doesn't and you see the message '(Source not available.)', it will be because of one of two reasons. Either the source member containing the code for the module can't be found, or the module was compiled with the option not to generate debug data. In the first case, you need to locate the source file member by using DSPMOD. In the second case, you will need to re-compile the module with the DBGVIEW option set to *ALL. It may be necessary also to re-create the program object using CRTPGM. If so, be careful that you bind the required CGI service programs (use DSPPGM to view before re-creating).
4. Assuming you've got through step 3, you should now be looking at a screen full of source code. It's not color-coded in the way that the ISDB is, but some might consider this an improvement! The first thing you should do is insert a breakpoint in the code somewhere near the start, by placing the cursor over a line and pressing F6. If you don't do this, the program will run all the way through without you being able to stop it. When you've done this, go back to the browser and re-visit (or refresh) the mrc CGI application URL. Go back to your green screen, and you can start stepping through your code. Don't be too leisurely: there's a script timeout directive in the HTTP config that limits you to about 5 minutes. This can be changed of course, but not without stopping and re-starting the server instance.
5. When you've finished type ENDDBG followed by ENDSRVJOB.
