As explained at the beginning of the chapter, DDS is not intuitive and may be the most difficult programming language on the i5. The primary reason for this is that DDS is so flexible and allows you to define so many different types of files. Coding DDS for display files is so difficult that, at this early stage, you should not attempt to code DDS for display files yourself. You should let the Screen Design Aid (SDA) do the work. Later, when you gain confidence and experience, you can start coding DDS manually if you prefer.
Using SDA is an easier way to design display files. You can see everything you are designing right on the screen, including special attributes such as underline, color, and the like. Because the DDS for display files can be so complicated, and SDA eliminates the need to learn all the intricacies, concepts rather than code syntax will be discussed.
Each display panel is a separate record format in the display file. However, these records don't have to paint the entire screen. The records can paint only a small area if you prefer. DDS window keywords can also be used to specify the size or area for a record format, and DDS will manage the border and screen overlay for you.
To enable a particular function key, you must include a keyword that is appropriate for the key. For example, you can enable the F3 key by including either CA03 or CF03 at the file level or at the record level.
If you want to enable a particular function key in all record formats, place the appropriate DDS keyword at the file level, before the first record is defined. If you want to enable it only in certain (but not all) records, do not put the DDS keyword at the file level, but at the record level. You must put the DDS keyword once on each record that must have it enabled.
For the F1 to F24 keys, use keywords CA01 to CA24, or CF01 to CF24. The difference between CA XX and CF XX is that the CA XX keywords ignore all input the user may have entered, while CF XX keywords accept it. Because the F3 key means "Exit" and is used to terminate a program, it should probably always be coded with a CA03 key. On the other hand, F4 usually means "Prompt," which requires input from the user. CF04 would be appropriate in this case.
The Roll keys use DDS keywords ROLLUP and ROLLDOWN, or alternatively, PAGEDOWN and PAGEUP, respectively. Note that the UP and DOWN directions are reversed: ROLLUP and PAGEDOWN are the same thing. The name "roll keys" comes from the 5250-type display stations. The name "page keys," on the other hand, come from the PC world. The trend is to use "page" instead of "roll" nowadays, but you can use either.
The DDS keyword should include an indicator within parentheses, although it is not required for CA XX and CF XX keywords. This indicator turns on when the user presses the corresponding function key. The application program using the display file can, therefore, sense that the function key was pressed.
For example, CA03(17) enables F3. If the user presses F3, indicator 17 turns on. If the user presses any other key (including Enter), indicator 17 turns off.
The PRINT keyword must be included at either the file level or the record level to allow the user to press the Print key and obtain a facsimile of the screen. If you omit PRINT, the user gets an error message when he presses Print. This error can be a problem if the user needs to copy the screen. Unless you have a compelling reason for disabling PRINT in certain record formats, consider placing it at the file level so that all records can use it.
IBM-supplied panels (including the sign-on displays) always blink the cursor. To do the same, you must use the BLINK keyword. Unfortunately, BLINK cannot be placed at the file level, so you need to repeat it on each record. BLINK is not a requirement but is a little cosmetic feature that makes your screens more IBM-like.
You can display the contents of a variable by coding the name of the variable in 19–28 and its location (beginning row and column) in 39–41 and 42–44, respectively. In addition, the variable must be defined either directly or by reference.
Constants can be displayed by coding their location (their beginning row and column) and the actual text of the constant 45–80 (enclosed in single quotes). If you need more space, you can put a + or – sign at the end and continue on the next line.
In the following example (Figure 22.16), a display file record prompts for field UNIT.
Figure 22.16: DDS and display files.
Note that the text "Unit of Measure" appears on row 5, column 2. The letter U in "Unit of Measure" falls on column 2. The field itself has a location of +1 in the column specification. This number indicates that field UNIT is located after the constant "Unit of Measure" in such a way that there is one space in between the two.
Display files let you specify DDS keywords that can control what user input is acceptable. This process relieves the application program from performing much validation checking.
For example, you can design a display file that, among other things, prompts for a code. If you want the display file to accept only certain values, you can do so by using the VALUES keyword at the field level.
Other keywords are:
CHECK. You can allow blanks (AB) or demand that the user enter a valid name (VN). Example: check(VN).
COMP. Lets you specify a comparison, such as COMP(GT 20). The user must then enter a numeric value greater than 20.
RANGE. Lets you specify a range of valid values, such as range(‘A’ ‘M’). The user must then enter a character between A and M.
VALUES. Lets you specify what values are considered valid, such as VALUES (1 2 3 5 9). The field will then accept values of 1, 2, 3, 5, or 9 and no other.
If the workstation user enters a value that doesn't meet the criteria you have selected, the workstation controller sends a generic error message, highlights the offending field, and locks the keyboard. The user must press Reset, correct the error, and try again.
In RPG, display files are used in the following ways:
Define the file in the F-spec as Combined Full-Procedural, place an E in 19 (to use the external definition provided by DDS), and workstn beginning in 40. If needed, you can code one or more continuation F-specs to use the INFDS, for example.
To display a panel, use the WRITE operation (for output only) or the EXFMT operation (for output immediately followed by input), with the record name in Factor 2. You will use EXFMT more often than WRITE because normally you want to present a panel, wait for input, and process the input. You can also use a WRITE immediately followed by a read.
To determine if the user has pressed any function keys, test the response indicators associated with such function keys. For example, if the display file contains CF04(82), indicator 82 turns on if the user presses F4. You can then check if *IN82 is on (‘1’) in your program and take whatever action is appropriate in that case. If none of the function key response indicators is on, it means that the user pressed the Enter key.
If you have conditioned fields, display attributes (such as high-intensity or color), or error messages with indicators, you can activate them by turning on the associated indicator before presenting the panel. For example, suppose you have conditioned the COLOR(RED) keyword with indicator 17. If you want to display the field in normal color (green), turn off indicator 17 before the WRITE or EXFMT operation is issued. If you want to show the field in red, however, turn on indicator 17.
There are many ways to display error messages. You can use one particularly simple method for the time being. At a later time, you can investigate other more sophisticated methods.
The method in question involves the use of the ERRMSG or the ERRMSGID keywords at the field level and the ERRSFL keyword at the file level. Figure 22.17 is an example.
Figure 22.17: DDS and ERRSFL display files.
Record PANEL prompts for two fields: CODE (which accepts only the letters A, B, or C) and AMOUNT (which must be less than 950.75). The user sees the panel, enters D for CODE and 1000 for AMOUNT, and presses Enter.
At that point, the workstation controller realizes that both fields are incorrect. It turns on indicators 91 and 92 and displays the error messages included in the ERRMSG keywords in a subfile. If you had omitted ERRSFL, the system would have shown only the first error message. In this case, only half the errors made by the user would have been reported.
To make this technique work, you must make sure to use the same indicator (as indicator 91 is used above) twice in the ERRMSG line: first as a conditioning indicator (left-hand side) and then inside the ERRMSG keyword.
Display files are noticeable because the user actually sees them on the screen. If you want to design application programs or other software to look like IBM's, you need to adhere to the Commson User Access (CUA) standards, because the panels presented by i5/OS adhere to CUA.
All panels must have a title that is centered in high intensity (white color) at the top (line 1). This title must briefly describe the purpose of the panel.
If any special instructions for the user are required, enter them beginning on line 3, left-adjusted, in blue. You undoubtedly have seen IBM's "Type options, press Enter" in that spot many times.
The available function keys and their purpose must be documented on line 23, left-adjusted, in blue. If you need more space than line 23 provides, use lines 22 and 23. The general format is: Fx=Description.
Leave line 24 for error messages, which should always appear in high intensity (white).
Most function keys also have a standard meaning. The most important ones are:
F1. Equivalent to the Help key. The user should be allowed to press either Help or F1 to request help. Although it wastes a function key, it is the standard. The system can equate for you F1 (or any other key) to the Help key. You need to use the ALTHELP keyword in the DDS of the display file.
F3. Exit. Ends the program immediately.
F4. Prompt. If a field accepts many values, you can define F4 to present a list of the allowed values.
F5. Refresh. Restores the panel as it was when it was presented first. If the user has entered anything, input is ignored.
F12. Cancel. Takes you back to the previous panel (if there is one). If there is no previous panel, it performs the same function as F3.