Mon, May
3 New Articles

The API Corner: Automating Recovery, Part III

  • Smaller Small Medium Big Bigger
  • Default Helvetica Segoe Georgia Times

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                              




  QUSBPRV = 0;                                                  


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

  if RunCmd(Cmd) = 1;                                           


        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);     



        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);     




             SndMsg('ESC0002' :'OURMSGS   *LIBL'                  

                    :MsgID :%size(MsgID)                          

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




  // Do further processing                                        


  *inlr = *on;                                                     





The message description ESC0002 was previously created with this command:



   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);




RunCmd(Cmd :QUSEC);


rather than


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

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



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!


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

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 IBM System i APIs at Work
Leverage the power of APIs with this definitive resource.
List Price $89.95

Now On Sale



Support MC Press Online

$0.00 Raised:

Book Reviews

Resource Center

  • SB Profound WC 5536 Have you been wondering about Node.js? Our free Node.js Webinar Series takes you from total beginner to creating a fully-functional IBM i Node.js business application. You can find Part 1 here. In Part 2 of our free Node.js Webinar Series, Brian May teaches you the different tooling options available for writing code, debugging, and using Git for version control. Brian will briefly discuss the different tools available, and demonstrate his preferred setup for Node development on IBM i or any platform. Attend this webinar to learn:

  • SB Profound WP 5539More than ever, there is a demand for IT to deliver innovation. Your IBM i has been an essential part of your business operations for years. However, your organization may struggle to maintain the current system and implement new projects. The thousands of customers we've worked with and surveyed state that expectations regarding the digital footprint and vision of the company are not aligned with the current IT environment.

  • SB HelpSystems ROBOT Generic IBM announced the E1080 servers using the latest Power10 processor in September 2021. The most powerful processor from IBM to date, Power10 is designed to handle the demands of doing business in today’s high-tech atmosphere, including running cloud applications, supporting big data, and managing AI workloads. But what does Power10 mean for your data center? In this recorded webinar, IBMers Dan Sundt and Dylan Boday join IBM Power Champion Tom Huntington for a discussion on why Power10 technology is the right strategic investment if you run IBM i, AIX, or Linux. In this action-packed hour, Tom will share trends from the IBM i and AIX user communities while Dan and Dylan dive into the tech specs for key hardware, including:

  • Magic MarkTRY the one package that solves all your document design and printing challenges on all your platforms. Produce bar code labels, electronic forms, ad hoc reports, and RFID tags – without programming! MarkMagic is the only document design and print solution that combines report writing, WYSIWYG label and forms design, and conditional printing in one integrated product. Make sure your data survives when catastrophe hits. Request your trial now!  Request Now.

  • SB HelpSystems ROBOT GenericForms of ransomware has been around for over 30 years, and with more and more organizations suffering attacks each year, it continues to endure. What has made ransomware such a durable threat and what is the best way to combat it? In order to prevent ransomware, organizations must first understand how it works.

  • SB HelpSystems ROBOT GenericIT security is a top priority for businesses around the world, but most IBM i pros don’t know where to begin—and most cybersecurity experts don’t know IBM i. In this session, Robin Tatam explores the business impact of lax IBM i security, the top vulnerabilities putting IBM i at risk, and the steps you can take to protect your organization. If you’re looking to avoid unexpected downtime or corrupted data, you don’t want to miss this session.

  • SB HelpSystems ROBOT GenericCan you trust all of your users all of the time? A typical end user receives 16 malicious emails each month, but only 17 percent of these phishing campaigns are reported to IT. Once an attack is underway, most organizations won’t discover the breach until six months later. A staggering amount of damage can occur in that time. Despite these risks, 93 percent of organizations are leaving their IBM i systems vulnerable to cybercrime. In this on-demand webinar, IBM i security experts Robin Tatam and Sandi Moore will reveal:

  • FORTRA Disaster protection is vital to every business. Yet, it often consists of patched together procedures that are prone to error. From automatic backups to data encryption to media management, Robot automates the routine (yet often complex) tasks of iSeries backup and recovery, saving you time and money and making the process safer and more reliable. Automate your backups with the Robot Backup and Recovery Solution. Key features include:

  • FORTRAManaging messages on your IBM i can be more than a full-time job if you have to do it manually. Messages need a response and resources must be monitored—often over multiple systems and across platforms. How can you be sure you won’t miss important system events? Automate your message center with the Robot Message Management Solution. Key features include:

  • FORTRAThe thought of printing, distributing, and storing iSeries reports manually may reduce you to tears. Paper and labor costs associated with report generation can spiral out of control. Mountains of paper threaten to swamp your files. Robot automates report bursting, distribution, bundling, and archiving, and offers secure, selective online report viewing. Manage your reports with the Robot Report Management Solution. Key features include:

  • FORTRAFor over 30 years, Robot has been a leader in systems management for IBM i. With batch job creation and scheduling at its core, the Robot Job Scheduling Solution reduces the opportunity for human error and helps you maintain service levels, automating even the biggest, most complex runbooks. Manage your job schedule with the Robot Job Scheduling Solution. Key features include:

  • LANSA Business users want new applications now. Market and regulatory pressures require faster application updates and delivery into production. Your IBM i developers may be approaching retirement, and you see no sure way to fill their positions with experienced developers. In addition, you may be caught between maintaining your existing applications and the uncertainty of moving to something new.

  • LANSAWhen it comes to creating your business applications, there are hundreds of coding platforms and programming languages to choose from. These options range from very complex traditional programming languages to Low-Code platforms where sometimes no traditional coding experience is needed. Download our whitepaper, The Power of Writing Code in a Low-Code Solution, and:

  • LANSASupply Chain is becoming increasingly complex and unpredictable. From raw materials for manufacturing to food supply chains, the journey from source to production to delivery to consumers is marred with inefficiencies, manual processes, shortages, recalls, counterfeits, and scandals. In this webinar, we discuss how:

  • The MC Resource Centers bring you the widest selection of white papers, trial software, and on-demand webcasts for you to choose from. >> Review the list of White Papers, Trial Software or On-Demand Webcast at the MC Press Resource Center. >> Add the items to yru Cart and complet he checkout process and submit

  • Profound Logic Have you been wondering about Node.js? Our free Node.js Webinar Series takes you from total beginner to creating a fully-functional IBM i Node.js business application.

  • SB Profound WC 5536Join us for this hour-long webcast that will explore:

  • Fortra IT managers hoping to find new IBM i talent are discovering that the pool of experienced RPG programmers and operators or administrators with intimate knowledge of the operating system and the applications that run on it is small. This begs the question: How will you manage the platform that supports such a big part of your business? This guide offers strategies and software suggestions to help you plan IT staffing and resources and smooth the transition after your AS/400 talent retires. Read on to learn: