As IBM continues to enhance RPG to allow reducing the use of indicators, RPG developers should also be looking for ways to decrease the use of indicators. Using display attribute fields is one way.

One common use of indicators is to conditionally set the display attributes of fields on display files--for example, highlighting or reverse imaging the field, or setting the field's color.

Setting the display attributes on a field is done using the COLOR and DSPATR field-level keywords. Different display attributes are usually set with conditioning indicators. However, there is a way to set these attributes without using indicators--by coding a special form of DSPATR and defining attribute fields.

An attribute field is a one-character field defined in the display file DDS. It is a program-to-system field (specified with a usage of "P"). The RPG application loads an attribute byte into this field, which controls the display attributes of the display field linked to the attribute field.

A display field is linked to an attribute field by using the DSPATR keyword: The format is DSPATR(&ATTRFLD), where ATTRFLD is the name of the attribute field. A field can have only one attribute field, although any number of fields can share a single attribute field; thus, one attribute field can be used to set the same attributes for more than one field simultaneously.

Attribute Bytes

An attribute byte is a special one-byte value that controls the color and effect of a display field. By "effect," I mean highlighting, underlining, and reverse imaging. These values are expressed in hexadecimal format--for example, x'20' (for normal attribute).

IBM's documentation for the DSPATR keyword gives a list of 30 attribute byte values: Some establish a color (such as x'38' for pink), some establish an effect (x'24' for underscore), and some establish a combination (x'3C' for pink and underscore). These 30 attribute byte values are used for input-capable fields. There is another set of 30 values for use with non-input-capable fields. That is a total of 60 values.

To set display attributes for a field, we simply load the desired attribute byte value into the field's linked attribute field:

And then we write the screen format.

Attribute Value Bit Manipulation

It's easier, and recommended, to define a named constant for each attribute byte value. It is also a good idea to put these named constants into a copybook. We can define a named constant for each of the 60 values. However, we don't necessarily need to define that many named constants.

These attribute values were not arbitrarily chosen. Each bit of an attribute value has a certain function:

• The high order bit (bit 0 in RPG-ese) is the Protected Attribute bit. It is on for a protected field, off for an input-capable field.
• Bits 1 and 2 are always 0 and 1, respectively.
• Bits 3 and 4 determine the color (00=green, 01=red, 10=turquoise, 11=pink).
• Bit 5, if on, underscores the field.
• Bit 6, if on, highlights the field.
• Bit 7, if on, reverse images the field. Setting on bits 5, 6, and 7 at the same time results in the non-display attribute.

We can then use bit manipulation to derive any of the 60 attributes we want. Now, we would only need a minimum of eight named constants:

• One constant for each of the four color attributes
• One constant for each of the three effect attributes
• One constant for the protect attribute

We derive the attribute value by assigning the named constant to the attribute field:

To combine color with an effect and/or the protect attribute, use the %bitor built-in function (BIF). As an example, to set an attribute field to pink with reverse image, you would use the statement:

Or, prior to V5R2:

To determine if a certain attribute is on in an attribute field, use the %bitand BIF. For any named constant atrXX, the format would be this:

For example, to check to see if the reverse image attribute is on:

or

To check for a combination, use %bitor wherever atrXX is (or use an and clause).

I mentioned that we would need only eight named constants, but for the sake of a program's readability and ease of maintenance, I suggest a couple more:

• Named constants for white, yellow and blue. These are actually highlighting colors, derived by turning on highlighting with the following colors: green, which highlights to white; turquoise, which highlights to yellow; and pink, which highlights to blue.
• A named constant for the non-display attribute.

Example: Calendar Date Prompt Window

To best see attribute fields in action, I present this example (which you may download and use).

This program is a date prompt window. When called, it presents a calendar, from which the user may select a date to pass back to the caller, either by double-clicking on the desired day, or by putting the cursor on the desired day and pressing Enter.



As you can see in the figure above, the days in the calendar have various attributes. Workdays are green. Weekends and holidays are pink. Today's date is reversed imaged.

The program has three parameters:

• A one-digit numeric field that returns either zero (if the user exits the prompt without selecting a day) or a number representing the day of the week of the user's selected day (1=Monday...7=Sunday).
• An *ISO date field that contains the user's selected date. (Careful! If the user exits without selecting a date, this will contain the system date.)
• An optional one-character field (defined in the program as an indicator field) that contains '1' if the selected date is a workday, '0' otherwise.

Display File Source (PMTCALD)

In order for this program to work properly and for the calendar to be displayed properly, we need to set up 42 fields--one for each day of the month, keeping in mind that a month could span six calendar week rows (as May 2004 does). Also, keep in mind that the first of the month could start on any of the seven days of the week.

The goal is to differentiate between workdays (which may include weekend days) and non-workdays, including holidays. Non-workdays will be pink. To accomplish changing the attribute to pink using indicators, we would need to use 42 separate indicators, one for each day field. To also reverse image today's day, we would need another 42 separate indicators.

By using attribute fields, we will use no indicators:

Display File Notes

Note that the code above shows a bolded 1 and 2 in the left margin:

1. These are the attribute fields. Notice their length, data type, and usage; they are one-character program-to-system fields.
2. These are the day fields that will display on the screen. Look at the DSPATR keyword. This is where the field is linked to the corresponding attribute field.

RPG Source (PMTCAL)

RPG Program Notes

Again, refer to the bolded numbers in the left column:

1. The code between D***/copy and D***/end-copy are normally in a copybook.
2. These are the hexadecimal named constants for the various display attributes. We will create an attribute value by bit manipulation on a color, an effect, and the protect attribute. The color is required, and the effect is optional. The protect attribute is only required for output fields, or input-capable fields you want to protect. There is also a one-character attribute work field defined here.
3. These are fields that will contain default attribute values. They are defined LIKE the attribute work field. One, aWorkDay, will be used for the workday, and the other, aNotWorkDay, will be used for non-workdays.
4. The screen day display fields and the corresponding attribute fields are put into an array for easier manipulation. You will need to enter the rest.
5. You will need to substitute your shop's program to determine if a date is a workday.
6. Here is where we establish the default attributes. The day display fields are output, so the protect attribute is required. We also establish the appropriate color for each: green (normal) for workdays, pink for non-workdays. These attributes are set using bit manipulation with %bitor.
7. This subroutine is looking for today among the day fields, by looping through the array of attribute fields. It knows today has been found when the reverse image attribute has been found to be on. %bitand is used to determine if the reverse image attribute is on in the attribute field.
8. This is where we assign the attribute value to the attribute field. We start by defaulting all the attribute fields to aWorkDay (green). Note that this is a simple assignment. As we loop through, building the calendar, we see if the day is a workday. If it isn't, we assign aNotWorkDay (pink). Again, this is a simple assignment. Also in this loop, if the day is today, we turn on the reverse image effect in the attribute field. %bitor is used, because we are combining reverse image with what is already in the attribute field--protected, green or pink.
9. This is another check to see if an attribute is on. In this case, we are checking to see if the attribute value in aWorkDay is on.

Other Points to Consider

Attribute fields are ideal for use in subfile records, as there would be no worry about keeping track of attribute indicators, either in the record or in the indicator area.

These same attribute values can be embedded in character fields to allow mixing display attributes (including the non-display attribute) in one field.

In our quest to reduce indicator usage, the use of attribute fields goes a long way toward that goal. They are simple to use, and deriving the attribute values is also simple with bit manipulation. Attribute values are also invaluable when needing to mix attributes in a field, which cannot be done with indicators.

Give them a try.

Doug Eckersley is the iSeries programmer with a premier homebuilder in Columbus. He has been programming on the iSeries for 10 years and has been in the business for 15. He is certified by IBM.

Also Read

Advanced/Free - Function Calls and Return Values

PRACTICAL ILE - ILE Service Programs

Data-Manipulation Operations Using Free Format, Part Two