24
Sun, Nov
1 New Articles

Using APIs to Edit Data Areas

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

Historically, APIs have been a bit of an enigma to most of the AS/400 programming community. To use them, you had to be familiar with mostly foreign objects like receiver variables, user spaces, and variable-length fields. And, in that respect, nothing much has changed. What has changed is the AS/400 programmer’s point of view. The cause may be global warming or a rise in UFO sightings. Or maybe it is because most AS/400 programmers realized that the ostrich approach (living with their heads in the sand) is not going to work in a world in which the equipment and software they work on changes on a daily basis.

Think about this: The computer you buy today may be outdated by next year, but the software you write today could very well be running decades from now. If Y2K taught us anything, it taught us that software often outlives its author. We were performing Y2K fixes to RPG code written back in the ’60s, for crying out loud!

The point is that, if your only goal is to remain gainfully employed in some oneman shop, working on some broken down CISC-based AS/400, just keep doing what you are doing. But the fact is, the previous depiction does not describe you, or you would never have read past the first few lines of an article with the acronym API in the title. No, you are more interested in learning about new tools and techniques and making yourself more valuable to your company or future potential employers. So, now that we have established that you are a hard-charging, up-and-coming dude (or dudette), let’s get down to the nitty-gritty and learn all about the Retrieve Data Area API (QWCRDTAA).

Who Wants to be an API Programmer?

An AS/400 data area is a single record file used to store information. Its beauty is in its simplicity. You can write data to it, and you can read data from it, but you have no record management to deal with. Consequently, you don’t have to deal with other complicated associations like logical views, multiple record formats, and a long list of other baggage generally associated with a physical file. Unfortunately for you, the programmer, IBM carried this simplicity thing a little too far with the tools that work with data areas.

You can create a data area using the Create Data Area (CRTDTAARA) command, display a data area using the Display Data Area (DSPDTAARA) command, retrieve a data area using the Retrieve Data Area (RTVDTAARA) command, change a data area using the Change Data Area (CHGDTAARA) command, or delete a data area using the Delete Data


Area (DLTDTAARA) command. Hello! Do you see something missing here? What about the ability to edit a data area? Did you think that the CHGDTAARA command would actually show you the data you were changing? If that is what you thought, guess again. Nope. You can specify the new value of the data and the position and length of the data to be changed. This seems an awful lot like the children’s game of pin the tail on the donkey. Just think of the data area as the donkey, and your data as the tail with the pin. One wrong move and you will end up making an ass out of yourself (pun intended). To blindly go where no man has gone before.... Sorry about that—went into a time warp for a minute
there. Back to the subject at hand....

Since IBM saw no need to give you the ability to edit a data area, this article shows you how to use APIs to do this very thing. It’s cool, and it’s fast!

What IBM did give us was an API to retrieve a data area, and it is named the Retrieve Data Area API (QWCRDTAA). We determined that we could use the API, combined with running the Change Data Area (CHGDTAARA) command (run via the QCMDEXC API), to create our own Edit Data Area (EDTDTAARA) command.

Would You Like to Use One of Your Lifelines?

This Edit Data Area utility consists of three objects: the RPG IV program EDT101RG; the associated display file, EDT101DS; and the EDTDTAARA command. The source code is too long for publication, but you can download it from the Midrange Computing Web site, (www.midrangecomputing.com/mc).

Figure 1 provides a sample of output for the command. The RPG program accepts one parameter that contains the name of the data area you wish to edit and the library where it resides. It passes the input parameter on to the Retrieve Data Area API (QWCRDTAA). The table in Figure 2 (page 114) describes the parameters for the Retrieve Data Area API. This is a relatively easy API to use because it only needs five parameters plus the obligatory, standard error data structure.

Parameter 1 is the name of the receiver variable, to hold the output from the API. Parameter 2 is the length of the receiver variable, named in Parameter 1. Parameter 3 is the qualified name of the data area. The qualified name of an object is simply the name of an object, directly followed by the library name where the object resides. Parameter 4 is the starting position within the data area to begin retrieving data. A -1 is used for this parameter, which tells the API to retrieve all the data in the data area from the beginning. And last, but not least, parameter 5 is the length of the data to retrieve.

Parameter 5 can be used in conjunction with parameter 4 to substring out part of the data from the data area. In this example, 32 KB is specified, which is roughly the maximum size of a variable field. This is used because, initially, you do not know the size of the data area you are going to edit. Therefore, you call the API twice; the first time to find the size of the receiver variable, and the second time to actually retrieve the data. This technique is pretty common when using the retrieve APIs.

The bottom line is that we are using the technique of double calling the API to determine the true size of the variable. So we call the API the first time, specifying 32 KB as the number-of-bytes-to-return parameter and specifying 8 bytes as the length of the receiver. After the first call of the API, the first field in the receiver variable (BYTESPOSS) contains the number of bytes that could have been returned by the API. This is also the length that the receiver variable should be. Once the length is established, we use the ALLOC command to allocate storage for that amount and call the API again, this time specifying the BYTESPOSS field as the size of the receiver variable.

The rest of the program parses through the returned receiver variable in 50-byte increments. There’s nothing magical about the number 50, we just decided that the size just fits pretty well on the screen in a subfile record. So each 50-byte chunk of data area equals one subfile record. This is pretty easy code if you are dealing with character-type data areas.


Most of the retrieve APIs have a parameter that describes the data to be returned. But, in the case of the Retrieve Data Area API (QWCRDTAA), the parameter was omitted because there is only one possible format.

The receiver variable definition, in Figure 2, shows the format of the returned data. The first two fields are the bytes-returned and total-bytes-possible fields, common to most retrieve type APIs. The third field is the type of data area that we are dealing with. The fourth field is the library name field, which contains the name of the library where the system finds the data area. The fifth field is the length of the data area. The sixth field is the number of decimal positions used when dealing with a decimal data area. If you total the lengths of all of these fields, you get the number 36. Consequently, the actual data that resides in the data area begins in position 37. Therefore, we defined the beginning of the data in 37 and run for a length of 2,000 more bytes, which happens to be the maximum length of a data area. We will only substring out the actual length of the data area as given in the field RtnLength in the receiver variable.

We found that we had a slight problem though. Why is nothing ever as simple as it seems? We found that the data returned in the receiver variable is packed data in a character variable. We found that we had to unpack the data to make it useable. Since the actual size of the data varies from data area to data area, we can’t code a simple move to a properly sized packed field. But that is what we need to do to unpack the data. So we needed to get a little creative when unpacking decimal data. We defined a data structure with 15 subfields. Each subfield is defined as packed and increases in size by one byte over the previous definition. So all we have to do is move the packed data into the inclusive data structure, determine the actual size of the data, and then move the correctly sized packed field definition to the character output field.

In looking through the code, you might see something else that looks a little unusual. We defined our subfile so that each subfile record is 50-bytes long and underlined.

But we did not want the underlined field to extend past the actual end of the data, and the length of every data area is not always going to be divisible by 50. So we needed to concatenate the protect and nondisplay control characters to the end of the last subfile record. The reason for doing this was purely cosmetic, but we liked the end result better this way.

As you can see, this program is both simple and functional. In the interest of brevity, we did not perform any edits on the data entered to ensure validity of data types. In other words, you can key alpha characters on the screen into a numeric data area. The program would blow up if you tried to do this. If you are going to use this utility, you should probably add your own edit routines.

Is That Your Final Answer?

APIs are a great way to retrieve data that is not otherwise readily available. Take a few minutes and browse through the API manuals. You may be surprised at how much information you can retrieve on your AS/400. If the information is there, there is probably a way to get it. All you need is to know is how.


Using_APIs_to_Edit_Data_Areas04-00.png 406x176

Figure 1: EDTDTAARA looks similar to DSPDTAARA and is as easy to use.


Parameter Description Type Attribute Size

1 Receiver variable takes Output Char Varies the following format:

From To Description
Attribute

Size

1

4

4

5

8

Possible bytes to return Binary

Actual number of bytes returned Binary 4

9

18

Type of data area Char 10

19

28

Library name Char

10

29

32

Length of data area Binary 4

33

36

4

37

??

Varies

2 Receiver length Input Binary 4

Length of receiver variable specified in parameter 1.

3 Data area name Input Char 20

Qualified data area name. First 10 bytes is data area name, second 10 bytes is library name.

Special Name Values

Value Description

*LDA Local data area

*GDA Group data area

*PDA Program initialization parameter data area

Special Library Values

*LIBL Library list

*CURLIB Jobs current library

4 Starting position Input Binary 4

Starting position with the data area to begin retrieving data. -1 indicates retrieve all data from the data area. 2000 bytes maximum.

5 Length of data to retrieve Input Binary 4

Cannot be zero. This length plus starting position -1 cannot exceed actual length of data area.

6 Error data structure I/O Char Varies

Standard error data structure.


Number of decimal positions Binary

Information stored in data area Char

Figure 2: The Retrieve Data Area API parameters are few and easy to understand.


BLOG COMMENTS POWERED BY DISQUS

LATEST COMMENTS

Support MC Press Online

$

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: