Detect errors when using the API system.

In last month's column, "Automating Recovery, Part II," we looked at the Process Commands (QCAPCMD) API and the flexibility the API provides for determining just what went wrong when attempting to run a CL command and the command fails for one reason or another. In this article, we will look at what's available with the API system when it comes to determining what went wrong when a CL command fails in the middle of our RPG application and attempting to recover from the error situation.

But First…

Before we do that, though, I would like to briefly return to the QCAPCMD API. In response to last month's article, Loek M. sent me a note regarding the QCAPCMD API and a problem that was encountered during application development—namely, that the QCAPCMD API is provided with a public authority of *EXCLUDE. This surprised me as a quick check on several systems showed the public authority as *USE (and I never change the public authority of IBM commands or APIs on my systems), but a check of the IBM Information Center did indicate that the API is provided with a public authority of *EXCLUDE. Clearly, some investigation was warranted as I use the API extensively in my applications and no one had ever reported an authority problem to me.

With the assistance of Guy Vig with IBM, also known as Mr. CL, we discovered what was going on. When the QCAPCMD API initially became available in V2R3, it was mistakenly defined with a public authority of *EXCLUDE. This error was later reported and, since V4R1, the API has been shipped by IBM with a public authority of *USE. This change in public authority may not, however, be reflected on all systems.

Any system that has been installed (from IBM media) starting with V4R1 will have the public authority to QCAPCMD set as *USE. This will be the case for any newly installed system or any pre-existing system that has been scratch installed (from IBM media) since V4R1 became available.  Systems that may have the public authority to QCAPCMD still as *EXCLUDE will be those that predate V4R1 and meet one or more of the following conditions:

• Have done release upgrades through all the years—in this case, the release upgrade will have retained the previous release public authority setting of the API (propagating the incorrect setting)
• Predate V4R1 and have done scratch reloads using previous saved media (where the saved media retained the incorrect *EXCLUDE setting of the API)
• Have explicitly set *EXCLUDE using various security-related commands (in which case I hope they realize that the APIs QCMDEXC and system have always been provided with a public authority of *USE)

If you encounter a system with the public authority of QCAPCMD set to *EXCLUDE, and the user did not explicitly set this authority value (which they generally wouldn't as it's really the authority to the command to run that's important, and the authority to the command is checked by the API), then you should change the public authority to *USE. This change would be consistent with IBM's current public authority for the API. Unfortunately, and further complicating things, the developer responsible for this authority change back in V4R1 did not realize that the Information Center documents the public authority for system APIs, so this change has not been reflected in the online API documentation. This will be corrected over time as the various release levels of the Information Center are updated.

We'll Now Return to Our Regularly Scheduled Program

With that out of the way, let's now turn to the API system and the ability to determine what went wrong when attempting to run a CL command using the API. Below is an enhanced version of the sample program originally published in the article "Running CL Commands from RPG" that utilizes the API system.

h dftactgrp(*no) bnddir('QC2LE')                                 

dRunCmd           pr            10i 0 extproc('system')          

d Cmd                             *   value options(*string)     

dSndMsg           pr                  extpgm('QSYS/QMHSNDPM')    

d MsgID                          7    const                      

d QualMsgF                      20    const                      

d MsgDta                     65535    const options(*varsize)    

d LenMsgDta                     10i 0 const                      

d MsgType                       10    const                       

d CSE                        65535    const options(*varsize)    

d CSECtr                        10i 0 const                      

d MsgKey                         4                               

d QUSEC                               likeds(QUSEC)              

d LenCSE                        10i 0 const options(*nopass)     

d CSEQual                       20    const options(*nopass)   

d DSPWaitTime                   10i 0 const options(*nopass)   

d CSEType                       10    const options(*nopass)   

d CCSID                         10i 0 const options(*nopass)   

/copy qsysinc/qrpglesrc,qusec                                  

dPSDS            sds           429    qualified                 

d JobUsr                254    263                              

dCmd              s            512                              

dMsgID            s              7    import('_EXCP_MSGID')     

dMsgKey           s              4                              

 /free                                                           

  QUSBPRV = 0;                                                  

  Cmd = 'CLRPFM FILE(SOMEFILE) MBR(' + PSDS.JobUsr + ')';       

  if RunCmd(Cmd) = 1;                                           

     select;                                                    

        when MsgID = 'CPF3141';                                 

             Cmd = 'ADDPFM FILE(SOMEFILE) MBR(' + PSDS.JobUsr + ')'; 

             if RunCmd(Cmd) = 1;                                     

                SndMsg('ESC0002' :'OURMSGS   *LIBL'                  

                       :MsgID :%size(MsgID)                           

                       :'*ESCAPE' :'*PGMBDY' :1 :MsgKey :QUSEC);     

             endif;                                                  

        when MsgID = 'CPF3142';                                      

             Cmd = 'CRTPF FILE(SOMEFILE) MBR(' + PSDS.JobUsr +       

                   ') MAXMBRS(*NOMAX) OPTION(*NOSRC *NOLIST)';       

             if RunCmd(Cmd) = 1;                                      

                SndMsg('ESC0002' :'OURMSGS   *LIBL'                  

                       :MsgID :%size(MsgID)                          

                       :'*ESCAPE' :'*PGMBDY' :1 :MsgKey :QUSEC);     

             endif;                                                   

        other;                                                       

             SndMsg('ESC0002' :'OURMSGS   *LIBL'                  

                    :MsgID :%size(MsgID)                          

                    :'*ESCAPE' :'*PGMBDY' :1 :MsgKey :QUSEC);     

     endsl;                                                       

  endif;                                                           

  // Do further processing                                        

  *inlr = *on;                                                     

  return;                                                         

 /end-free                

The message description ESC0002 was previously created with this command:

ADDMSGD MSGID(ESC0002) MSGF(OURMSGS) +

   MSG('Unexpected error &1 encountered .') FMT((*CHAR 7))

At first glance, use of the API system appears to provide the same level of function as our previous examples using the APIs QCMDEXC and QCAPCMD—and with less coding on your part. There are fewer parameters to pass to the API system, there is no need to calculate the length of the command string to run because the options(*string) specification for the system prototype enables the API to determine the length based on the presence of a null byte, there is no need to establish a monitor group as with QCMDEXC or a non-zero Bytes provided error code structure as with QCAPCMD, and so on (though I will return to this point later in this article). And for simple errors in the running of the command, where you only need access to the CPF error message ID, recovery can be automated in a manner very similar to what is used with the QCMDEXC and QCAPCMD APIs.

However, more complex error recovery when using the API system can be like trying to pull firmly attached teeth; it can be a very painful and lengthy process. When developing an application, I tend to be a pessimistic optimist. I anticipate that anything that can go wrong will (eventually and typically at the absolute worst time) and that I can successfully automate recovery from any application error if I choose to (with some recovery procedures just not being worth the effort, unless of course the user feels otherwise). In order to effectively recover from errors, I prefer to utilize system interfaces that will tell me everything possible about an error situation. And it is in this "everything possible" desire of mine that I find the API system to be lacking.

As we saw last month when running the CLRPFM command, we are using a library qualifier of *LIBL to identify the file containing the member to be cleared. If, after a failure is encountered clearing the member, we wanted (or needed) to determine the name of the library associated with SOMEFILE, the QCAPCMD API provides this information very easily. The name of the library is readily available as variable CPF3141.Library, which is mapped over the message replacement subfield of the QCAPCMD error code data structure. With the QCMDEXC, the library name is also available (though you do need to call another API in order to receive the escape message CPF3141 from your program message queue). With the API system, you will however find that determining the name of the library can be a non-trivial task.

All three APIs will, if the file SOMEFILE is found and the specified member does not exist, be sent CPF3141 from the CL command CLRPFM. When this CPF3141 message is received by the API, these things happen:

• QCMDEXC will resend the escape message to your program, allowing you to detect the error (a monitor group, a PSSR, etc. if provided).
• QCAPCMD will, if the error code Bytes provided field is zero, resend the escape message to your program, allowing you to detect the error (a monitor group, a PSSR, etc. if provided).
• QCAPCMD will, if the error code Bytes provided field is non-zero, provide the escape message information (message ID and message replacement data) in the error code data structure, allowing you to detect the error.
• system will return a return value of 1 allowing you to detect the error, store the message ID in exported variable _EXCP_MSGID, and remove the escape message from the job log.

Note that the API system removes the message, so it's not just difficult to access the additional information provided by the CPF3141 escape message replacement data (the library name in our example); the message is simply not there anymore.

The API system has additional error-related characteristics that I find troubling. Some CL commands, in addition to sending escape messages, will also send diagnostic messages in response to a failure when attempting to run a command. Let's say for instance that in response to the CPF3141 error, our program attempts (as the example does) to add the member to the file using the ADDPFM command (not caring at this point about the name of the library containing the file). If the file member count is currently at its maximum, the ADDPFM command will send the diagnostic message CPF3213 (Members for file SOMEFILE more than maximum allowed) followed by the escape message CPF7306 (Member xxxxxx not added to file SOMEFILE in yyyyyy). In the same manner as the three APIs handled the escape CPF3141, so will they handle the CPF7306. CPF7306, however, does not tell us why the member was not added—just that the ADDPFM command failed. If the program wants/needs to automate recovery when the maximum member count has been reached (for instance, change the MAXMBR value of SOMEFILE), the program requires access to the associated diagnostic message to determine the underlying reason for the failure. That is, there is no reason to change MAXMBR if the diagnostic is not CPF3213. For diagnostic messages such as CPF3213, the behavior of the API used is this:

• QCMDEXC will move the diagnostic message(s) to the caller of QCMDEXC.
• QCAPCMD will move the diagnostic message(s) to the caller of QCAPCMD.
• system will leave the diagnostic message(s) as is.

QCMDEXC and QCAPCMD, by moving the diagnostic message(s) to the caller of the API, enables the application program to easily receive the message using message-handling APIs, determine the message ID, access the message replacement data (if needed), and determine the appropriate recovery process (for instance, run the CHGPF CL command if CPF3213 is found as the underlying reason for the failure). The API system, by not moving the message, makes access to the message (while not impossible as in the case of removing the underlying escape message) much less direct.

The location of the diagnostic message(s) is important due to the message-handling functions of the i operating system being call stack–oriented. When using an API to receive a program message, you can use the special value '*' to specify the current call stack entry (you) and 0 as a counter relative to the call stack entry where the message to receive can be found (that is, your program again). In the case of QCMDEXC and QCAPCMD, these two API parameter values correctly, and easily, identify where to find the diagnostic messages: your program message queue. The API system, however, did not move the messages to "you"; rather, they're still back where the CL command initially sent them. The message-handler APIs can access messages associated with another call stack entry, but the call stack entry must exist (or, if it doesn't exist, you must have a message key to specify the message, which the API does not provide to us, or you must derive the message key similar to what is shown in the Information Center here). In the case of the API system, the diagnostic message(s) were associated with the API call stack entry and the API is no longer on the call stack as it has returned to our application program. To access the message(s) when using the API system, the application program needs to process the job log and, while there are also message-handling APIs enabling access to the job log, this access is nowhere near as direct as when using QCMDEXC or QCAPCMD. Trying to, within a program, find the CPF3213 message when using the API system will be a true learning experience....

The API system is provided with the i operating system as part of C runtime support and is very good at its primary function: running CL commands with an API interface and providing implementation that is consistent with what's found with other operating systems. The API has, in addition, been extended with _EXCP_MSGID support to allow a basic level of error recovery.

When developing an application, I prefer to use one consistent interface for a given purpose (such as running a CL command) and to use an interface that is as flexible as possible. For the following reasons, I use the QCAPCMD API for the running of CL commands (from within a non-CL based application program):

• QCAPCMD gives me access to the basic function: running a CL command.
• QCAPCMD provides me with flexibility in terms of receiving monitorable escape messages or error information in the form of variables within the error code parameter for first-line error recovery.
• QCAPCMD enables easy access to much more extensive error-related information when I need it (which admittedly is not often, but I like knowing it's there).

Due to these reasons, I recommend the use of QCAPCMD, though in your environment, you may have good reasons for selecting one of the other APIs (such as consistency with C implementations in other areas of your company).

Earlier in this article, I mentioned that one perceived drawback of the QCAPCMD API is the number of parameters required by the API (at least relative to QCMDEXC and system). For my own application development, I have implemented a procedure named RunCmd that accepts two parameters: the CL command to run and an error code parameter. So in my own programs I would code the following…

RunCmd(Cmd :ErrCde);

or

RunCmd(Cmd :QUSEC);

rather than

RunCmd(Cmd :%len(%trim(Cmd)) :QCAP0100 :%size(QCAP0100)            

         :'CPOP0100' :NotUsedChr :0 :NotUsedInt :ErrCde);            

or

RunCmd(Cmd :%len(%trim(Cmd)) :QCAP0100 :%size(QCAP0100)            

         :'CPOP0100' :NotUsedChr :0 :NotUsedInt :QUSEC);            

…depending on whether or not I wanted escape messages sent directly to my program. My RunCmd procedure then calculates the length of the Cmd value, initializes the QCAP0100 input parameter (among other parameters to the API), resends and/or moves messages returned by the API, and so on. In this way, I get all of the function and flexibility found with QCAPCMD and avoid cluttering my application program source with unnecessary parameters. A win-win situation for me!

Questions?

If you have any API questions, send them to me at This email address is being protected from spambots. You need JavaScript enabled to view it.. I'll see what I can do about answering your burning questions in future columns.  

as/400, os/400, iseries, system i, i5/os, ibm i, power systems, 6.1, 7.1, V7,

Bruce Vining is president and co-founder of Bruce Vining Services, LLC, a firm providing contract programming and consulting services to the System i community. He began his career in 1979 as an IBM Systems Engineer in St. Louis, Missouri, and then transferred to Rochester, Minnesota, in 1985, where he continues to reside. From 1992 until leaving IBM in 2007, Bruce was a member of the System Design Control Group responsible for OS/400 and i5/OS areas such as System APIs, Globalization, and Software Serviceability. He is also the designer of Control Language for Files (CLF).A frequent speaker and writer, Bruce can be reached at This email address is being protected from spambots. You need JavaScript enabled to view it.. 

---

MC Press books written by Bruce Vining available now on the MC Press Bookstore.

		IBM System i APIs at Work Leverage the power of APIs with this definitive resource. List Price $89.95 Now On Sale

Also Read

The API Corner: Moving Jobs Within and Across Job Queues

The API Corner: What Time Zone Do You Want That Date and Time In?

The API Corner: How Do You Want That Date and Time?