You are currently on IBM Systems Media’s archival website. Click here to view our new website.


New D-Specs Break the Limit

RPG extends maximum size limits and adds new keywords

The RPG IV 6.1 release featured two major upgrades we feel are of immediate benefit to all RPG programmers:

  1. Improvements in data-definition capabilities including maximum-size increases of data items
  2. The capability to define files in subprocedures and, perhaps even more importantly, to pass files as parameters.

In this article, we’ll focus on the first of these—the new D-spec capabilities.

Sometimes Size Does Matter

If you’ve used RPG’s built-in XML support (see “A Traditional Approach to a Modern Technology” and “More on RPG’s XML Support”), then you’ll have almost certainly run into RPG’s size limitations. Before 6.1, variables in RPG—which in this context includes named data structures (DSs)—were limited to a maximum size of 65,535 bytes. Sounds reasonable, doesn't it? But consider the following relatively simple XML structure:

    <Name>Jones and Co.</Name>
    <Street1>68 Westchester Avenue</Street1>
    <Street2>Suite 427</Street2>

To process this with a straightforward XML-INTO would require that we define a DS something like this:

d Customers     DS          Qualified
d   Customer                LikeDS(Customer)
d                           Dim(400)

d Customer      DS
d   name                30
d   street1             40
d   street2             40
d   city                20
d   state               2
d   zip                 8

This is fine as long as the number of Customer entries in the XML document is relatively small, as it is in this example (400). But suppose we need to handle 1,000 or 2,000 entries at a time. Can we accommodate that? With 6.1, the answer is yes, but if you’re running 5.4, it’s a different story. Some simple math will show you that the largest number we could handle would be 468, because that’s how many occurrences of 140 characters (the length of a single Customer entry) we can accommodate within RPG IV's old limit of 65,635 characters. 65K sounds like a lot until you divide it up like this. So how many can we handle in 6.1? The answer is a massive 119,807 elements—which should be enough for all but the biggest jobs. That’s the number of 140-character items we can fit into the new limit of 16,773,104 bytes.

To fully exploit these new limits, not only has the maximum DS size increased, but so has the maximum number of array elements that can be defined. The old limit was 32,767. (For some strange reason, it was never raised to 65,635 when the variable size limit was raised to that level.) So, what’s the new limit? That’s a harder question to answer than it used to be because the limit now is based on the maximum structure size. Given a maximum structure size of 16,773,104 bytes, we can have an array of 16,773,104 one-byte elements, or 8,386,552 two-byte elements, etc.

Another change in 6.1—the introduction of the new keyword TEMPLATE—can also help in situations like this. If you study the provided code sample, you'll realize the DS Customer will probably never be used to store data. Its whole purpose is so we can define the array Customers.Customer as looking like the DS Customer. In practice, we’d often code it like this:

d Customer     DS      Based(pCustomersTemplate)
d   name ...

This way, if we accidentally reference the fields in it directly, the program will blow up at run time during testing because the basing pointer, pCustomersTemplate, wouldn’t have been set. It’d show us the error of our ways. But in addition to this technique being confusing to those unfamiliar with it, it has two other disadvantages. First, the compiler can’t detect erroneous references to its fields, and second, BASED structures can’t have initialization values defined. In this case, that’s not significant but there are occasions when it can be useful. Both of these limits are removed by the new TEMPLATE support:

d Customer    DS        Template
d   ...
d   city            20   Inz('Los Angeles')
d   state            2   Inz('CA')
d   ...

We can now set initialization values for the fields if desired—and these will apply to the LIKEDS structure if we also code the keywords INZ(*LIKEDS). Additionally, if we attempt to assign a value (for example) to the field city, the compiler will issue the severity 30 error “Item CITY was defined with TEMPLATE and cannot be used in this context” and the program will fail to compile. Much, much nicer.

TEMPLATE can also be used when defining files, but we'll deal with that in a later article when we look at the new file facilities.

Jon Paris is a technical editor with IBM Systems Magazine and co-owner of Partner400.

Susan Gantner is a technical editor with IBM Systems Magazine and co-owner of Partner400.



2019 Solutions Edition

A Comprehensive Online Buyer's Guide to Solutions, Services and Education.

New and Improved XML-INTO

Namespace support makes the opcode a viable option

Authenticating on the Web

The finer points of OpenRPGUI, Part 1

The Microphone is Open

Add your voice: Should IBM i include open-source RPG tools?

IBM Systems Magazine Subscribe Box Read Now Link Subscribe Now Link iPad App Google Play Store
IBMi News Sign Up Today! Past News Letters