Detect Errors when using the QCAPCMD API.

In last month's column, "Automating Recovery (or Keeping the Help Desk Out of the Loop)," you saw how to use the Execute Command (QCMDEXC) API to run a CL command and then recover from a variety of possible error situations related to the running of the CL command. Today, we'll look at how to provide similar, though to my thinking improved, recovery using the Process Commands (QCAPCMD) API documented here.

Unlike the QCMDEXC API, the QCAPCMD API supports an error code parameter. As you saw in the second article of this series, "Running CL Commands from RPG," the error code parameter enables you to control whether or not escape messages are returned to the RPG program in error situations. If you set the Bytes Provided field of the error code parameter to 0, then escape messages are sent by the API and you effectively have the same level of error-handling capability as you saw with the QCMDEXC API reviewed last month. If, however, you set the Bytes Provided field to a non-zero value, then you pick up some ease-of-use characteristics that I find attractive. Here is a sample program patterned after the QCMDEXC example used last month, but using a non-zero error code Bytes Provided value when calling the QCAPCMD API.

h dftactgrp(*no)                                                  

dRunCmd           pr                  extpgm('QCAPCMD')           

d SourceCmd                  65535    const options(*varsize)     

d LenSrcCmd                     10i 0 const                       

d CtlBlk                     65535    const options(*varsize)     

d LenCtlBlk                     10i 0 const                       

d CtlBlkFmt                      8    const                       

d ChgCmd                         1    options(*varsize)           

d LenAvlChgCmd                  10i 0 const                       

d LenRtnChgCmd                  10i 0                             

d QUSEC                               likeds(QUSEC)               

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)      

dMaxInt           pr            10i 0                             

d Input1                        10i 0 const                       

d Input2                        10i 0 const                       

 /copy qsysinc/qrpglesrc,qcapcmd                                  

 /copy qsysinc/qrpglesrc,qusec                                    

dPSDS            sds           429    qualified                   

d JobUsr                254    263                                  

dErrCde           ds                  qualified                     

d Common                              likeds(QUSEC)                 

d ErrMsgDta                    512                                  

dCmd              s            512                                   

dMsgKey           s              4                                  

dNotUsedChr       s              1                                  

dNotUsedInt       s             10i 0                               

 /free                                                              

  QUSBPRV = 0;                                                      

  ErrCde.Common.QUSBPRV = %size(ErrCde);                            

  QCAP0100 = *loval; // initialize input structure to nulls         

  QCACMDPT = 0;      // Run command                                   

  QCABCSDH = '0';    // Ignore DBCS                                  

  QCAPA = '0';       // Do not prompt command                        

  QCACMDSS = '0';    // User i5/OS syntax                            

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

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

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

  if ErrCde.Common.QUSBAVL > 0;                                      

     select;                                                         

        when ErrCde.Common.QUSEI = 'CPF3141';                        

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

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

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

             if ErrCde.Common.QUSBAVL > 0;                           

                SndMsg(ErrCde.Common.QUSEI :'QCPFMSG   *LIBL'        

                       :ErrCde.ErrMsgDta                             

                       :MaxInt(0 :ErrCde.Common.QUSBAVL - %size(QUSEC))

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

                SndMsg('ESC0001' :'OURMSGS   *LIBL' :' ' :0           

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

             endif;                                                   

        when ErrCde.Common.QUSEI = 'CPF3142';                         

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

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

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

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

             if ErrCde.Common.QUSBAVL > 0;                            

                SndMsg(ErrCde.Common.QUSEI :'QCPFMSG   *LIBL'         

                       :ErrCde.ErrMsgDta                              

                       :MaxInt(0 :ErrCde.Common.QUSBAVL - %size(QUSEC))

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

                SndMsg('ESC0001' :'OURMSGS   *LIBL' :' ' :0           

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

             endif;                                                    

        other;                                                        

             SndMsg(ErrCde.Common.QUSEI :'QCPFMSG   *LIBL'            

                    :ErrCde.ErrMsgDta                                 

                    :MaxInt(0 :ErrCde.Common.QUSBAVL - %size(QUSEC))  

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

             SndMsg('ESC0001' :'OURMSGS   *LIBL' :' ' :0               

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

     endsl;                                                           

  endif;                                                              

  // Do further processing                                            

  *inlr = *on;                                                         

  return;                                                             

 /end-free                                                  

pMaxInt           b                                         

dMaxInt           pi            10i 0                       

d Input1                        10i 0 const                 

d Input2                        10i 0 const                 

 /free                                                      

  if Input1 > Input2;                                       

     return Input1;                                         

  else;                                                     

     return Input2;                                         

  endif;                                                     

 /end-free             

pMaxInt           e    

Similar to last month's QCMDEXC example program, this program starts by prototyping the QCAPCMD and QMHSNDPM APIs. The current program, however, does not prototype the QMHRMVPM API (used in last month's example program in order to leave a "clean" job log when recovering from an error situation). There will not be any error messages to remove from the job log when this month's program encounters an error that it can recover from as the QCAPCMD API would not have sent the message in the first place (due to a non-zero Bytes Provided value in the error code structure).

Following the prototype for QMHSNDPM, there is, however, a new prototype for an internal function named MaxInt. This function is not actually required in the current program, but I find it handy for a reason that we'll get into later in this article.

The program then includes (or copies) the QSYSINC-provided header files QCAPCMD and QUSEC. These header files provide the IBM-supplied definitions for the structures associated with the QCAPCMD API and the API error code parameter, respectively. As with the QCMDEXC example program, the current program defines the Program Status Data Structure in order to access the current user's name. Unlike with the QCMDEXC example, though, the PSDS subfield MsgID is not defined. The message ID of any error detected by the QCAPCMD API will instead be accessed using the error code Exception ID (QUSEI) subfield of the error code parameter (which is defined within the QUSEC header file). Using the QUSEC error code structure defined by the QUSEC header file, the program then defines the data structure ErrCde using the base IBM-provided definition of the error code parameter with an additional 512 bytes allocated for error message replacement data (ErrMsgDta). It is this ErrCde data structure that the program will use as an error code parameter when calling the QCAPCMD API and not wanting escape messages to be sent in the case of error situations.

As with the previous QCMDEXC example, the program also defines the two standalone fields Cmd and MsgKey. The program also defines two new standalone fields, NotUsedChr and NotUsedInt. These fields are used to represent QCAPCMD API character and integer parameters, respectively. These fields are used as placeholders for parameters that, while not being utilizing per se, are defined as outputs of the API and therefore cannot be specified as constants on the API call.

With the data definitions out of the way, the program initializes the Bytes Provided field of the QUSEC and ErrCde error code data structures to 0 and 528, respectively. The QUSEC error code data structure will be used when calling system APIs and where any failure encountered by the API would generally indicate a situation outside the control of the program. For instance, a failure when calling the QMHSNDPM API to send an error message (assuming appropriate testing of the call parameters during development) would generally indicate a failure beyond the application program's control. Also initialized are various control fields of the QCAPCMD QCAP0100 data structure used with format CPOP0100. The initializations essentially indicate that we want to run a CL command.

As with the previous QCMDEXC example program, the current program now formats and attempts to run a CLRPFM command. In this example, though, the QCAPCMD API is used to run the command, and the error code parameter passed to the API is the ErrCde data structure. With the preceding explanations out of the way, we have now set the environment for the meat of this article: namely, recovering for errors when running a CL command.

If an error is encountered in running the CLRPFM command, then the Bytes Available field (QUSBAVL) of the ErrCde data structure will be returned with a positive value, and the program will enter a Select group to determine which error occurred. In the previous program using QCMDEXC, the logic related to handling errors such as CPF3141 and CPF3142 included removing the message from the job log. With QCAPCMD and an error code with a non-zero Bytes Provided field, there is no need to remove the message as it was never sent by the API (see above). Using QCAPCMD and the ErrCde error code data structure, the recovery for these error situations is to simply select and run the appropriate CL command given the error message ID returned in ErrCde.Common.QUSEI. If this attempt to recover from the error succeeds—for instance, ErrCde.Common.QUSBAVL is 0 following the ADDPFM recovery action when CPF3141 is returned from the CLRPFM command—then the program simply continues on to its "further processing." No additional work, such as removing the CPF3141, is needed.

There is, of course, a downside to the QCAPCMD API not sending error messages—namely, that the message is not in the job log if our recovery action is unsuccessful (for instance, the ADDPFM fails when attempting to recover from CPF3141) or if the error encountered is one that the program is unprepared to handle (for instance, the CLRPFM command fails with a CPF3134 – Referential constraint error). In this case, the program needs to send the CPF message as a diagnostic, followed by the escape message ESC0001. Fortunately, this is very easy as we know the error message ID from the ErrCde subfield QUSEI and we have the message replacement data readily available in the ErrCde subfield ErrMsgDta. To send the necessary messages to the job log, we can use the QMHSNDPM API as shown in the sample program.

It's in the sending of the CPF error messages that the program uses the MaxInt function mentioned previously. Strictly speaking, MaxInt is not needed for the example program. In an error situation when running the CLRPFM, ADDPFM, or CRTPF commands, the program could simply use the following QMHSNDM API call to send the appropriate CPF error message.

      SndMsg(ErrCde.Common.QUSEI :'QCPFMSG   *LIBL'          

             :ErrCde.ErrMsgDta                              

             :ErrCde.Common.QUSBAVL - %size(QUSEC)

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

In the preceding call, the value of the fourth parameter when using the QMHSNDM API, Length of message data, can be determined by taking the number of bytes available in the ErrCde data structure (ErrCde.Common.QUSBAVL) and then subtracting the size of the QUSEC Common subfield of ErrCde. This will leave us with the size of the message data associated with the error message being sent. The size of the QUSEC data structure is 16, so we effectively have (ErrCde.Common.QUSBAVL – 16). This, however, only works because all of the error messages returned by CLRPFM, ADDPFM, and CRTPF return message replacement data.

There are some CL commands (and some APIs, ignoring QCAPCMD for the moment) that can return error message information in the ErrCde parameter and the message does not utilize message replacement data. In the situation of no message replacement data, the value of ErrCde.Common.QUSBAVL is 15 (due to the 16th byte of QUSEC being reserved and not representing any meaningful error-related data being returned). If we then use the preceding QMHSNDM API call, we'll end up with the fourth parameter being set to the value -1 as we will be subtracting 16 (the size of QUSEC) from 15 (the number of bytes available in the ErrCde data structure). This negative value will result in a runtime error when calling the QMHSNDM API. As I prefer to write generic code that can be widely utilized (as opposed to using one way of calculating the Length of message data for some API calls and other ways for other API calls), I use the MaxInt function to set the fourth parameter to the value of 0 when the calculation (ErrCde.Common.QUSBAVL - %size(QUSEC)) returns a negative value. Then, I can simply copy this QMHSNDM API call logic to any program I'm writing.

At this point, I should also mention that even the QMHSNDM call shown in the example program is not what I actually use in my application development environment. Though it's not directly relevant to this article, I have written a set of functions that are used by my applications and are what I really code to in my application programs. One function, for instance, will simply send whatever system message is currently found in the ErrCde data structure as a diagnostic message to the current program boundary. So, in my program, I can simply code SendDiag(). It's then the SendDiag function that utilizes the MaxInt function to set the value of the fourth parameter when calling the QMHSNDM API, sets the fifth parameter (Message type) to *DIAG, determines what message file really stores the message ID value found in ErrCde.Common.QUSEI (you may notice that the example program has hardcoded QCPFMSG, which may not be the case for all commands and API calls), etc. For my application-oriented diagnostic messages, I have another function where I can pass parameters defining what error message ID I want sent, the data structure containing the replacement data I want sent with the message, and the length of the data within the data structure. In this way, I generalize the sending of diagnostic messages within my application programs.

Returning to the main topic of this article, error recovery, the ErrMsgDta subfield of the ErrCde data structure also provides some additional "free" information when compared to recovering from an error using the QCMDEXC API. When running the CLRPFM command, you may have noticed that the file SOMEFILE is not library-qualified, so the CLRPFM command is, by default, using the jobs library list to locate SOMEFILE. What if you wanted to know the library SOMEFILE was located in when error message CPF3141 is encountered?

Using QCMDEXC, you do have access to the first-level text of the message in the PSDS, but unfortunately the library name is in the second-level text, not the first-level text. And even if the library name was in the first-level text, the PSDS returns the message with the message replacement data merged into the text of the message, making access to the replacement data extremely error-prone. To access the library name, you will need to call another API in order to receive the error message.

With QCAPCMD, the message replacement data is readily available to you. To be able to access error message replacement data in a generic fashion, you can use an approach such as shown below.

dErrMsgDtaPtr     s               *   inz(%addr(ErrCde.ErrMsgDta))

dCPF3141          ds                  qualified                   

d                                     based(ErrMsgDtaPtr)         

d File                          10                                

d Member                        10                                

d Library                       10                                

If you know you may need additional information related to an error situation, you can define a based data structure, such as CPF3141 shown above, where the basing pointer is initialized to the address of the ErrMsgDta subfield of the ErrCde data structure. In this case, when error situation CPF3141 is returned and you're using the ErrCde data structure, you can directly access the library name using the variable CPF3141.Library. There is no need for additional API calls, for parsing of the message replacement text, etc. Just directly use the data within your error recovery logic. Admittedly, this example of determining the library used is trivial, but there are many error situations where you need access to additional information that can be found only in the error message replacement data (for instance, reason codes). With the error code parameter provided with QCAPCMD, access to this additional information is a snap.

Both the QCMDEXC and the QCAPCMD APIs can be successfully used to run CL commands from an RPG application program. Both of the APIs also provide for recovery from errors encountered when attempting to run CL commands. The choice is yours as to which API you may prefer to use. My preference is QCAPCMD as I find it easier to work with in terms of no "cleanup" in my error recovery when I want to leave a clean job log and much easier access to error-related information. QCAPCMD does, however, when using a non-zero error code Bytes Provided value, mean that the application program needs to send error messages when all attempts to recover from the error fail. To me, calling additional system APIs (sending diagnostic and escape information) in the "hard failure" case is preferable to calling additional APIs (remove messages, receive messages, etc.) in the scenarios where the application program is able to continue functioning.

Next month, we will look at error recovery using the API system, a third API that can be used to run CL commands from an RPG application program.

Questions?

In the meantime, 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.

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?