I have never cared for the way RPG handles exceptions that occur when you run a CL command via the QCMDEXC API. Using the *PSSR just never seemed to work the way I needed it to. By way of comparison, the MONMSG command in CL seemed graceful. Fortunately, I found a way to solve this problem. It's an API like QCMDEXC, but it provides more flexibility and allows for much better error handling. The API is QCAPCMD, and it has been around since V2R3. I, for one, was amazed that it had been around for so long and I had never heard of it--much less used it. Better late than never, I guess.
QCAPCMD has several important advantages over QCMDEXC. For the purposes of this tip, I am going to focus on the error handling abilities of QCAPCMD. However, it would be worth your time to check out the IBM documentation on the QCAPCMD and find out what the other differences are.
To understand the difference between the way QCMDEXC handles errors and the way QCAPCMD handles errors it is necessary to understand the way most system APIs handle exceptions. Most system APIs use an error structure called QUSEC (or Qus_EC_t if you are using C) to return information regarding exception conditions and error data. You can find the layout of this structure in the QSYSINC library (QUSEC in QRPGLESRC). This structure is what nearly all APIs use to provide exception data back to the calling program. It is interesting to note that QCMDEXC is somewhat of an exception (no pun intended) in the way it handles exception conditions because it does not use the QUSEC structure.
What you gain by using the QUSEC structure is that if an exception condition occurs when the QCAPCMD command is executed, then the information regarding the exception is returned via the QUSEC structure. More importantly, the exception condition is "trapped" and not passed up the stack to the RPG program that ran it (i.e., a program exception condition will not be triggered and no *PSSR). This gives you much more flexibility in the way that you handle these types of conditions.
On a separate note, if you are going to be using system APIs and have access to C, then I would highly recommend creating simple C "wrappers" for commonly used APIs. By using "wrappers," regardless of language, you can usually reduce the number of parameters that you need to pass and create a simpler interface to the API. Also, when you can use C, the program code is simpler (and usually shorter) and you have access to structure field names that makes sense. Maybe it's just me, but "Err->Exception_Id" is much clearer than "QUSEI." In the downloadable code, I have included both a C wrapper and an RPG wrapper for the QCAPCMD so you can be the judge as to which is simpler to read and use.
Use CRTRPGMOD to create both the TESTCMD module and the RPG version of the RUNCMD module. Use CRTCMOD to create the RUNCMD module from the C source. The TESTCMD program will function the same regardless of which RUNCMD module you bind it to.
Jeff Olen is a member of the AS/400 development team at Gauss Interprise, a content management software company located in Irvine, California. He can be reached by email at jeff.olen@gaussvip.com.
Jeff Olen is co-founder of Olen Business Consulting Inc. and co-author of the best-selling book The IBM i Programmer's Guide to PHP. He has over 20 years of experience working with IBM midrange systems, including all the incarnations of the System i. In addition to extensive development experience using RPG, he also has expertise with PHP, JavaScript, C, C++, MySQL, and HTML.
Jeff is an accomplished author with numerous technical articles to his credit. Jeff continues to develop custom applications and even writes code (not as much as he'd like). Jeff can be reached at jmo@olen-inc.com.
QCMDEXC can be greatly enhanced by placing it in a CL wrapper. I have written a CMD which I called MONQCMD. You pass it the command string and it passes the command string to QCMDEXC. The MONMSG for QCMDEXC only monitors for CPF0006 (all other messages dealt with by a standard CLP global error message routine which passes all messages up the stack). The calling program can then monitor for specific messages. [size="1">Code[/size>
[size="1">Code[/size>