Mon, Apr
5 New Articles

API Error Handling

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

Most OS/400 APIs accept an error parameter that allows you to control what happens when an error occurs while executing the API. Usually, either you can let the system handle the error for you, or you can handle the error condition within your program. If you let the system handle the error, chances are it won't do it gracefully. In this article, I'll show you a technique you can use to trap API errors and send a message back to the user advising him what went wrong.

In general, the error parameter that most APIs accept has the same characteristics for all APIs. Once you learn to code this parameter, you can apply the same knowledge to other APIs. The technique I'm going to discuss applies to the majority of OS/400 APIs. However, a few newer types, such as the bindable APIs and sockets APIs, require different error handling techniques. I won't cover those in this article. For information on how to trap for errors with those types of APIs, see the OS/400 System API Reference V3R1 manual.

The standard API error parameter lets you trap for errors and take appropriate action when they are encountered. For example, in an interactive program, you may have the user supply a value for a parameter to a user-written command. You might then pass that value to an OS/400 API. If the API rejects the value, you can send a message to the user to let him know that the value he supplied was invalid and request that he try again. This rejection could continue until the user supplies a value the API can use. In this case, by using the error parameter, the API can be used to perform validation.

With some APIs, the error parameter is optional. With others, it is required. When the error parameter is optional, you may decide not to code it. If you don't code it and an error occurs while executing the API, the error will be handled by the system in the form of an exception error.

Even if the error parameter is required, you can still decide to let the system handle the error for you. You can do that by passing a four-byte binary field containing the value zero. In this case, you're telling the API to ignore the error parameter even though it's required. It's as if the error code were optional, and you decided not to code it. In both cases, if an error occurs during the execution of the API, the system generates an exception message.

A better approach is to code the error parameter in a way that lets the system know you want to trap for errors within your program. You do that by coding the error parameter as a data structure consisting of five subfields. 1 shows the structure of the error parameter.

A better approach is to code the error parameter in a way that lets the system know you want to trap for errors within your program. You do that by coding the error parameter as a data structure consisting of five subfields. Figure 1 shows the structure of the error parameter.

The first subfield, Bytes provided, is a four-byte binary field. This is an input field, so it must be loaded with a value before the API is executed. The value you place in this field must be either zero or a number greater than or equal to eight. If you pass a value of zero, you're telling the API to let the system handle errors for you. Otherwise, the value should be equal to the length of the data structure used to describe the error parameter.

The second subfield, Bytes available, is an output field that the API loads when it executes. Your program can use this four-byte binary field to detect if an error occurs. If the value of this field is zero after the call to the API, no error has occurred. If the value of this field is greater than zero, an error has occurred. When an error occurs, this field contains the length of the error information returned to your program. Normally, your program contains code that checks this field immediately after calling an API to see if an error has occurred.

The API loads the third subfield, Message identifier, when errors occur. This is a seven-byte character field in which the API will place a message identifier for the error condition. For example, the Retrieve Object Description (QUSROBJD) API might return a value of CPF2101 to specify that the object type parameter was loaded with an invalid value.

The fourth subfield is reserved by IBM, presumably for future use. Your program should not attempt to use this field. Any value that might be returned to your program would be meaningless and should, therefore, be ignored.

The last field, Message data, contains the data for the message identifier returned in the Message identifier field. This data does not contain the message text; it contains the substitution variables within the message text. For example, if the message text is Object type &1 not valid, the value in the Message data field contains the data that is substituted for the &1 variable.

The Message data field is a variable-length field, so you can define it any length you want. The only restrictions are those of the language you're using. For example, in RPG III, a subfield can have a maximum length of 256 bytes. I've found that 100 bytes is usually adequate. Although in extreme cases an error may require a larger message data field, 100 bytes should be large enough for most errors. If the message data is longer than the length of the message data field, it is simply truncated on the right. Even if this happens, all other aspects of the error parameter should still work normally.

After you call an API for which you have coded an error parameter, the first thing you should do in your program is to check to see if an error occurred. The Bytes available field will contain a value greater than zero if there is an error. When an error occurs, you will probably want to let the user of the program know what went wrong. You can do this by passing the message identifier and message data fields to a CL program. The CL program can then use these values to execute the Send Program Message (SNDPGMMSG) command.

The following programs illustrate API error handling. This example uses the Create User Space (QUSCRTUS) API, which uses the error parameter. It attempts to create a user space in library QTEMP. However, the call to the API has been purposely rigged to fail by passing it an invalid user space name. Although the API fails, the program does not. Because the appropriate error handling technique was used, the user of the program gets a simple error message on the bottom of the screen that tells him what went wrong. Take a look at the example programs in Figures 2 and 3.

In this example, a CL program (API001CL) calls an RPG program (API001RG). Program API001CL passes three parameters to API001RG. The first parameter is an error flag. This error flag will be returned with a Y if an error occurs. If no error occurs, it will contain an N. The second and third parameters are used to pass a message identifier and message data if an error occurs.

The program API001RG accepts these three parameters. It then attempts to create a user space using the QUSCRTUS API. However, the user space name has been deliberately loaded with an invalid value of BAD!NAME. The exclamation point character is not allowed in an object name, so the API will not be able to create the user space.

When this API is executed, the user space is not created. Instead, fields within the ERROR data structure are loaded with values to signal that an error has occurred. The program checks the Bytes available (BYTAVA) field to test for the error condition. Because this field contains a value greater than zero, the program knows that an error has occurred and loads the parameter fields ERR, MSG, and DTA. The ERR parameter is loaded with a Y to let the API001CL program know that an error has occurred. The MSG parameter is loaded with the MSGID field from the ERROR data structure, which contains the message identifier associated with the message. The DTA parameter is loaded with the MSGDTA field from the ERROR data structure, which contains the data for the message.

When control is passed back to the API001CL program, it checks the &ERR parameter. If it finds a value of Y in this field, it knows that an error has occurred, and it uses the SNDPGMMSG command to send a message back to the user to let him know. The SNDPGMMSG command uses the &MSG and &DTA parameters that were passed back from the API001RG program. The user sees a message on the bottom of his screen that says Object BAD!NAME is not valid. This not only lets the user know that an error occurred, but it also tells him why.

As you can see, this method is a good way to handle error conditions. When a problem occurs during the execution of an API, the user can be notified in a friendly way that an error occurred. It also gives users specific information about what went wrong so that they can take corrective measures without necessarily having to search through a job log. Even though the error parameter is often optional, you should consider taking advantage of it whenever possible.

Robin Klima is a senior technical editor for Midrange Computing. He can be reached by E-mail at This email address is being protected from spambots. You need JavaScript enabled to view it..


OS/400 System API Reference V3R1 (SC41-3801, CD-ROM QBKAVD00).

API Error Handling

Figure 1: The Structure of the Error Parameter

API Error Handling

Figure 2: Example Program API001CL

 /*===============================================================*/ /* To Compile: */ /* */ /* CRTCLPGM PGM(XXX/API001CL) SRCFILE(XXX/QCLSRC) */ /* */ /*===============================================================*/ PGM DCL VAR(&ERR) TYPE(*CHAR) LEN(1) DCL VAR(&MSG) TYPE(*CHAR) LEN(7) DCL VAR(&DTA) TYPE(*CHAR) LEN(100) /* CALL PROGRAM TO CREATE A USER SPACE */ CALL PGM(API001RG) PARM(&ERR &MSG &DTA) /* CHECK FOR AND PROCESS ERROR MESSAGES */ IF COND(&ERR *EQ 'Y') THEN(SNDPGMMSG + MSGID(&MSG) MSGF(QCPFMSG) MSGDTA(&DTA) + MSGTYPE(*ESCAPE)) ENDPGM 
API Error Handling

Figure 3: Example Program API001RG

 *=============================================================== * To compile: * * CRTRPGPGM PGM(XXX/API001RG) SRCFILE(XXX/QRPGSRC) * *=============================================================== *. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 * * API Error Parameter IERROR DS I I 116 B 1 40BYTPRV I B 5 80BYTAVA I 9 15 MSGID I 16 16 RESRVD I 17 116 MSGDTA I DS I B 1 40LENSPC * C *ENTRY PLIST C PARM ERR 1 C PARM MSG 7 C PARM DTA 100 * * Intentionally load an invalid name to force an error C MOVEL'BAD!NAME'USRSPC 20 C MOVEL'QTEMP' SPCLIB 10 C MOVE SPCLIB USRSPC C MOVE 'N' ERR * * Attempt to create the user space C CALL 'QUSCRTUS' C PARM USRSPC C PARM *BLANKS ATRSPC 10 C PARM 1024 LENSPC C PARM *BLANKS VALSPC 1 C PARM '*CHANGE' AUTSPC 10 C PARM *BLANKS TXTSPC 50 C PARM '*YES' RPLSPC 10 C PARM ERROR * * If an error occurred then load error parameters C BYTAVA IFGT 0 C MOVEL'Y' ERR C MOVELMSGID MSG C MOVELMSGDTA DTA C END * C MOVE *ON *INLR *. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 


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: