Brief: Are you looking for a way to reduce the number of indicators in your interactive programs? Here's a technique that can help. Using a new V2R3 enhancement to the DDS DSPATR keyword, you can modify the attributes of a field at run time without using indicators.

Using indicators in an interactive program is practically unavoidable since indicators are often the only means of controlling display file keywords. But these indicators can make programs difficult to understand. For instance, suppose you're looking at a program you wrote a year ago and you come across an undocumented statement that sets on indicator 67. Would you remember that this indicator causes the customer number to display in high intensity? Probably not. However, as you'll see in a moment, you can eliminate the need for such indicators.

A new feature in V2R3 can reduce the number of indicators needed to control screen attributes. Using fewer indicators makes programs easier to understand and maintain. This article describes how to take advantage of this new feature and gives you some design considerations.

The DSPATR Keyword

The DDS DSPATR (Display Attributes) keyword allows you to select one or more display attributes for a screen field. As of V2R3, this keyword has two formats. I'll show you both so you can see how this keyword has evolved.

The Old Format

In its original implementation, you supply the DSPATR keyword with one or more attributes. The old format of the DSPATR keyword is:

DSPATR(attrib-1 [attrib-2 [...]])

1 shows the valid attri-butes for the DSPATR keyword.

Figure 1 shows the valid attri-butes for the DSPATR keyword.

Here are a couple of examples.

o DSPATR(RI) displays a field in reverse image. o DSPATR(BL HI) displays a field as blinking and high-intensity.

You can code multiple DSPATR keywords for the same screen field and use option indicators to control screen attributes at run time. In your program, you select the attribute you want to activate by setting on the appropriate indicator. Using this method gets the job done but makes it difficult to remember which indicators control which attributes. With the new format of the DSPATR keyword, you can accomplish this task without using indicators.

The New Format

IBM has added a new optional format of the DSPATR keyword in V2R3 of OS/400. The keyword now accepts a program-to-system field in place of hard-coded attributes. The optional format of the DSPATR keyword is:

DSPATR(&program-to-system-field)

The only parameter is a program-to-system field or P-field, as I'll call it. P- fields pass data between a program and the system. Here are some general rules concerning P-fields.

o A P-field is defined in a display file as usage P (position 38). o A P-field must be defined in the same record format as the keyword which uses it. o Since P-fields do not appear on the display, screen coordinates are not allowed. o The P-field name must be preceded with an ampersand (&) when used as a keyword parameter.

With the DSPATR keyword, you must define the P-field as a one-byte, character field. In your program, you load the P-field with a hexadecimal value to represent the attribute you want the field to have. The table in 2 shows the valid hexadecimal values and their corresponding attributes.

With the DSPATR keyword, you must define the P-field as a one-byte, character field. In your program, you load the P-field with a hexadecimal value to represent the attribute you want the field to have. The table in Figure 2 shows the valid hexadecimal values and their corresponding attributes.

The table includes hexadecimal values for all the supported attributes; most of the combinations of attributes you would want are available. A separate hexadecimal value is necessary for each combination because DDS only allows one DSP-ATR P-field per screen field. For example, to display a field as highlighted and in reverse image, you would load the P-field with hex '23'. This gives you both attributes at once. Some hexadecimal values, such as '3B', provide as many as four attributes at a time. The table in 2 actually contains two similar sets of attributes. The top half of the table (hex 20-3F) contains only unprotected attributes while the bottom half (hex A0-BF) contains only protected ones. Other than that, the two sets of attributes are identical.

The table includes hexadecimal values for all the supported attributes; most of the combinations of attributes you would want are available. A separate hexadecimal value is necessary for each combination because DDS only allows one DSP-ATR P-field per screen field. For example, to display a field as highlighted and in reverse image, you would load the P-field with hex '23'. This gives you both attributes at once. Some hexadecimal values, such as '3B', provide as many as four attributes at a time. The table in Figure 2 actually contains two similar sets of attributes. The top half of the table (hex 20-3F) contains only unprotected attributes while the bottom half (hex A0-BF) contains only protected ones. Other than that, the two sets of attributes are identical.

An Example

Here's an example of how to use the new version of the DSPATR keyword in an application program. 3 shows a sample display file for an inventory inquiry application. The highlighted code shows the definition of a quantity- on-hand field ($QOH) as well as the P-field (@QOH) which controls its attribute. I have given the two fields the same name except for the first character, replacing the dollar sign ($) with an at sign (@) for the attribute field. Although this is not a requirement, you might consider adopting this standard because it clearly identifies related screen and attribute fields.

Here's an example of how to use the new version of the DSPATR keyword in an application program. Figure 3 shows a sample display file for an inventory inquiry application. The highlighted code shows the definition of a quantity- on-hand field ($QOH) as well as the P-field (@QOH) which controls its attribute. I have given the two fields the same name except for the first character, replacing the dollar sign ($) with an at sign (@) for the attribute field. Although this is not a requirement, you might consider adopting this standard because it clearly identifies related screen and attribute fields.

4 shows a partial RPG program which uses the display file in 3. The highlighted code labeled as A shows a series of named constants containing hexadecimal values. These values are screen attributes from the table in 2. Although there are many more possible values, I chose a sample of some of the attributes you are likely to need in an interactive program. Here again, I have adopted the standard of starting each attribute field with an at sign (@) for easy recognition.

Figure 4 shows a partial RPG program which uses the display file in Figure 3. The highlighted code labeled as A shows a series of named constants containing hexadecimal values. These values are screen attributes from the table in Figure 2. Although there are many more possible values, I chose a sample of some of the attributes you are likely to need in an interactive program. Here again, I have adopted the standard of starting each attribute field with an at sign (@) for easy recognition.

Look at the highlighted code labeled as B in 4. In this program, I want $QOH to display in reverse image if it contains a negative value. The program accomplishes this by moving @RI (reverse image) to @QOH (attribute byte for $QOH). If $QOH does not contain a negative value, then the program moves @NRML (normal attribute) to @QOH. This removes any attribute left over from the previous transaction.

Look at the highlighted code labeled as B in Figure 4. In this program, I want $QOH to display in reverse image if it contains a negative value. The program accomplishes this by moving @RI (reverse image) to @QOH (attribute byte for $QOH). If $QOH does not contain a negative value, then the program moves @NRML (normal attribute) to @QOH. This removes any attribute left over from the previous transaction.

In this case, the new format of the DSPATR keyword eliminates the need for indicators to control the attribute of the quantity-on-hand field. Using this technique, the code is practically self-documenting. Even without the comments, you could look at this code a year from now and still understand the program.

Choose the Right Format for the Job

The new format of the DSPATR keyword does not support all the possible attributes. Normally, this isn't a problem, since most applications don't require the MDT (Modified Data Tag), OID (Operator Identification) or SP (Select with Light Pen) attributes. Unfortunately, the new format doesn't support one very important attribute, PC (Position Cursor). If IBM decides to support this attribute in a future release, it will be a welcomed enhancement.

While the new format of the DSPATR keyword is a definite improvement, it doesn't make the old format obsolete. You may still want to use the old format when you don't need to change an attribute at run time. You'll have to use it when you want to use the position cursor (PC) attribute, as well as a few others I just mentioned. But if you're looking for a way to reduce the number of indicators in your programs (a worthy goal), you should consider using this new feature.

Robin Klima is a senior technical editor at Midrange Computing.

REFERENCE DDS Reference (SC41-9620, CD-ROM QBKA7402).

Run-time Screen Attributes

Figure 1 Valid Attributes for Original Format of DSPATR Key

 All Fields Display Attribute Description BL Blink CS Column Separator HI High Intensity ND Non-display PC Position Cursor RI Reverse Image UL Underline Input-capable Fields Display Attribute Description PR Protect MDT Set Modified Data Tag OID Operator Identification SP Select by Light Pen 
 
 Run-time Screen Attributes
 
 Figure 2 Valide DSPATR P-field Values
 
 UNABLE TO REPRODUCE GRAPHIC 
 
 Run-time Screen Attributes
 
 Figure 3 Item Inquiry Display File
 
 *=============================================================== * To compile: * * CRTDSPF FILE(XXX/XRK003DF) SRCFILE(XXX/QDDSSRC) * *=============================================================== *. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 A DSPSIZ(24 80 *DS3) A CA03(03) A R ITMINQ A 1 35'Item Inquiry' A DSPATR(HI) A 5 2'Item number . . . . .' A $ITMNO 5Y 0B 5 25EDTCDE(3) A 7 2'Description . . . . .' A $DESC 30A O 7 25 A 9 2'Quantity on hand . .' A $QOH 5Y 0O 9 25EDTCDE(L) A DSPATR(&@QOH) A @QOH 1A P A 23 2'F3=Exit' A COLOR(BLU) *. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 
 
 Run-time Screen Attributes
 
 Figure 4 Partial Item Inquiry Program
 
 *=============================================================== * To compile: * * CRTRPGPGM PGM(XXX/XRK003RG) SRCFILE(XXX/QRPGSRC) * *=============================================================== *. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 FXRK003DFCF E WORKSTN * I X'20' C @NRML I X'21' C @RI I X'22' C @HI I X'24' C @UL I X'27' C @ND I X'28' C @BL I X'30' C @CS I X'A0' C @PR * C *IN03 DOUEQ*ON * C EXFMTITMINQ * * Retrieve requested record from database * and load screen fields * . * . * . * * If quantity-on-hand is less than zero * then display in reverse image C $QOH IFLT 0 C MOVE @RI @QOH reverse image C ELSE C MOVE @NRML @QOH normal C ENDIF * C ENDDO * C MOVE *ON *INLR *. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 

Also Read

Practical Middleware: Architecting for the Future

Practical Middleware: Starting the Journey

IBM i 7.2: The Carrot Versus the Stick