IBM Support

Why you should use ALIGN(*FULL)

General Page

You are in: RPG Cafe > Why you should use ALIGN(*FULL)

Short URL:


Why you should use ALIGN(*FULL)

One of the enhancements for ILE RPG in 2017 was the ability to code *FULL as the parameter for the ALIGN keyword.

Here are some of the problems that can be solved by specifying ALIGN(*FULL).

With just ALIGN, %SIZE(ds_array) might not return the distance between elements of the array

First, if you have an array of data structures, and for some reason you want to know the distance between the elements ("the stride"), %SIZE(ds) might return a smaller value than the stride. To get the stride, you have to code this ugly expression:

%SIZE(ds : *ALL) / %ELEM(ds)

An example of where that would matter is if you were calling the qsort() API. One of the parameters to qsort() is the size of each element. With the wrong size, your data structure array would be completely garbled after the call to qsort(). It would be very difficult to debug the problem, and it might even lead people to abandon qsort() thinking it was "buggy".

With just ALIGN, you might get storage corruption

Here's an example showing how not coding ALIGN(*FULL) can cause storage corruption. (The program is attached at the end of this article.)

The regex_t data structure is defined with the correct subfields, and with the ALIGN keyword. But it's 12 bytes too short compared to the C version of regex_t. That's because C always makes the size of the storage a multiple of the alignment when a data structure is aligned. C adds 12 bytes of padding to the regex_t structure.

To avoid corrupting some unknown storage, and to make sure we could see the corruption in action, I put the regex structure in a data structure with some additional storage following it. If the regex_t structure is defined correctly, the call to regcomp() should not affect the data following the regex structure. But the regcomp() API affects 12 bytes of the storage following regex. The API affects the entire parameter.

The program displays

DSPLY  Showing 16 bytes following the regex ds
           DSPLY      before calling regcomp():zzzzzzzzzzzzzzzz
           DSPLY      after calling regcomp() :            zzzz

I am using the regex_t example, because that's been the cause of several calls to IBM about an API corrupting storage. But this could happen whenever you call a function written in C where the C struct does not have the _Packed keyword, which requires the RPG data structure to have the ALIGN keyword. Now, you can code the ALIGN(*FULL) keyword, and avoid running into the problems in the first place.

Should you just starting coding ALIGN(*FULL) on every data structure?

No, don't do that. Especially don't do that with existing data structures; unless you can be sure to recompile everything that uses the data structure. I would only consider coding ALIGN(*FULL) if I was already coding the ALIGN keyword, or if my data structure contained pointers that are automatically aligned.

Why can't the ALIGN keyword be changed to default to ALIGN(*FULL)?

Unfortunately, that could cause working programs to stop working correctly.


  1. testregex.rpgle_.txt

[{"Business Unit":{"code":"BU058","label":"IBM Infrastructure w\/TPS"},"Product":{"code":"SS69QP","label":"Rational Development Studio for i"},"Component":"ILE RPG Compiler","Platform":[{"code":"PF012","label":"IBM i"}],"Version":"All Versions","Edition":"","Line of Business":{"code":"LOB57","label":"Power"}}]

Document Information

Modified date:
16 December 2019