Coding windows in DDS can be tricky; here's how to avoid the pitfalls.
Brief: If you have ever tried to code windows using DDS, you know it can be a frustrating experience. This article gives you some simple guidelines which make the job much easier.
The widespread use of Microsoft Windows and the Apple Macintosh operating system has had an impact on the way we code our interactive applications. Even if you never use PCs or Macs yourself, you probably want to give your AS/400 users the ability to display information using windows. All excited, you make this decision (after all, it will improve user friendliness) and pick up the DDS Reference manual to see how to code windows in display file DDS.
...And the enthusiasm in your expression gives way to a look of discouragement when you realize that display file DDS is as complicated as DDS can get. SDA takes away a bit of the pain, but what remains might still intimidate and confuse you.
The WINDOW Keyword
Take heart. Programming with windows has become considerably easier with the availability of the WINDOW DDS keyword. This keyword was released in PTF SF07915 under V2R1M0. WINDOW simplifies window programming so much that there's no reason for using any other method. For an introduction to the WINDOW keyword and related concepts see the "AS/400 Window Basics" sidebar.
The WINDOW keyword is used at the record level for two purposes: to define a window, or to add to an existing window. Like any other display panel, a window can be comprised of several records which gradually "paint" the window, component by component. The first record that writes to the window must be the window definition record. All other records (which add to the existing window) are window reference records.
The window definition record must have the WINDOW keyword coded with four numeric parameters:
1. Starting line number.
2. Starting column number.
3. Number of lines for the window (height).
4. Number of columns for the window (width).
The first two parameters indicate the coordinates of the upper-left corner of the window border. The window height and width are specified without counting the borders. By default, a window displays a border made up of dots. You can modify the attributes of the border with the WDWBORDER record-level keyword. This keyword presents no mysteries and, in any case, only performs a cosmetic function. I'll illustrate how the four numeric parameters define a window with an example.
WINDOW(8 60 10 15)
Here I have indicated that the upper-left corner of the window border will be on line 8, column 60. The window is to have 10 usable lines (total of 12, counting the border) and be 15 columns wide (19, including the border).
The first two parameters can be given as variables instead of hard-coded constants. This allows you to dynamically position the window at execution time. To do that, you must code the WINDOW keyword as follows:
WINDOW(&STRLIN &STRCOL 10 15)
...where &STRLIN and &STRCOL are two program-to-system fields in the same record format as the display file. These fields must be defined in the DDS as signed numeric (data type S) with a length no greater than three and with zero decimal positions. A "P" in column 38 (usage) makes them program-to-system fields.
It is up to you to initialize these fields to values that are acceptable before you write the window on the screen.
Enough Theory!
When you're working with only one display file, the WINDOW keyword takes care of saving the contents of the screen before the window appears and then restores the previous contents when the window disappears, in essence, removing the window without leaving a hole. It also automatically overlays the contents of the screen.
When you work with multiple display files (one display file per program, in a modular application), however, WINDOW fails you. Consider the following scenario: Program A outputs a full-screen panel and then calls program B. Program B puts a small window on the screen.
If the windowing support had been designed for modular programs in a programmer-friendly fashion, the WINDOW keyword would be all you would need. What happens, in reality, is that the window erases the previous contents of the screen. When the window appears, then, everything else disappears. That's not how windows are supposed to work.
The DDS Reference manual contains no information about how to make this (all too typical) scenario work correctly. The Programming with Displays manual contains only partial information. Read on to find out what it takes to make windows work in a modular environment.
The Solution, Plain and Simple
Here's what you need to do. No IBM manual that I know of puts all the pieces together, to make it easy for you to understand the technique in full.
To make WINDOW work across display files and programs, do the following:
o Compile all but the last display file with RSTDSP(*YES). If the display files used are A, B and C (in that order), then you must compile A and B with RSTDSP(*YES). Com-pile C either way (with *YES or *NO).
o Every display file but the first one must contain a dummy record including the ASSUME keyword. In the same example, this means that display files B and C need to have this keyword. Display file A doesn't.
o Every display file but the first one should have the KEEP keyword in the record format which contains the WINDOW keyword. This prevents the screen from blinking when the windows are removed.
A Demonstration
Seeing is believing, as the saying goes. I am including three display files and three CL programs in this article. You can use them to see how the technique works.
When you call the first program (1 - pg. 35), it outputs a full-screen panel filled with Fs. If you press Enter, a large window appears, filled with Ls. Both panels are in the first display file, XEM007DF. (2 - pg. 38)
When you call the first program (Figure 1 - pg. 35), it outputs a full-screen panel filled with Fs. If you press Enter, a large window appears, filled with Ls. Both panels are in the first display file, XEM007DF. (Figure 2 - pg. 38)
Press Enter again. XEM007CL calls XEM008CL (3), which has its own display file (4) with one window record format. A small window appears on the screen, filled with Ss. The previous contents of the screen (the full- screen panel and the large window) are still there.
Press Enter again. XEM007CL calls XEM008CL (Figure 3), which has its own display file (Figure 4) with one window record format. A small window appears on the screen, filled with Ss. The previous contents of the screen (the full- screen panel and the large window) are still there.
Finally, press Enter once more. Program XEM008CL calls XEM009CL (5) which, again, has its own display file with a window record (6). A medium-sized window appears on the screen, filled with Ms. Nothing is erased- the window overlays what's already there, as shown in 7.
Finally, press Enter once more. Program XEM008CL calls XEM009CL (Figure 5) which, again, has its own display file with a window record (Figure 6). A medium-sized window appears on the screen, filled with Ms. Nothing is erased- the window overlays what's already there, as shown in Figure 7.
You can press F3 at any time to terminate the demo program, or F12 to go back one step at a time. When you press F12, the current window disappears, restoring the layer immediately underneath.
Other Details
Notice that display files XEM008DF and XEM009DF have the USRRST-DSP keyword. This saves time when the windows appear on the screen. Under normal circumstances, you wouldn't use USRRSTDSP; you would let the system save and restore the contents of the screen when manipulating windows. But since WINDOW fails across display files, you must take charge of saving and restoring, which is why the display files need to be compiled with RSTDSP(*YES). Had you omitted USRRSTDSP, that saving and re-storing would be performed twice, resulting in slower response time.
I'm not entirely sure about the performance implications of compiling all display files with RSTDSP(*YES), but it seems to me that you could compile almost every display file with this parameter value. That way you wouldn't have to worry about changing it at a later time when you design a window to lay on top of it. If you want to compile all your display files with RSTDSP(*YES), you could change the default value for this parameter in the Create Display File (CRTDSPF) command.
Window Happy?
Armed with this new knowledge, you may turn into a window-happy programmer. Resist the temptation. Windows are wonderful tools to build a better computer- to-user interface, but you can easily overdo them. Full-screen panels, in general, perform better than windows, especially for remote users connected to small AS/400 models.
And yet, windows can increase productivity tremendously and help close the gap between micro- and minicomputer applications. You can use windows to display small data entry panels, informative panels and selection subfiles.
Ernie Malaga has been working with IBM midrange computers for 10 years.
Article Side Bar
AS AS/400 Window Basics
Those readers already familiar with the DDS window keywords may want to skip this section or just browse through it. It is intended to present the basics to newcomers so that you'll have a basis for the specialized information presented in the article.
A window is nothing more than a bordered display file record format with special properties that allow it to overlay the currently displayed panel (all display characters underneath the window are automatically cleared). After the user is finished with the window, the overlayed portion of the previous panel is automatically restored.
There are only four keywords related to windows: WINDOW (window), WDWBORDER (window border), RMVWDW (remove window) and USRRSTDSP (user restore display). A1 illustrates the format of the WINDOW and WDWBORDER keywords. (RMVWDW and USRRSTDSP have no format since they have no parameters.)
There are only four keywords related to windows: WINDOW (window), WDWBORDER (window border), RMVWDW (remove window) and USRRSTDSP (user restore display). Figure A1 illustrates the format of the WINDOW and WDWBORDER keywords. (RMVWDW and USRRSTDSP have no format since they have no parameters.)
Of the four, the record-level keyword WINDOW is the only required keyword. It identifies a record format as a window. As shown in A1, the keyword accepts four parameters. The first two are for positioning the window at a row/column and the second two are for sizing the window in terms of rows and columns. Note that the start-row and the start-column can be literals or variables.
Of the four, the record-level keyword WINDOW is the only required keyword. It identifies a record format as a window. As shown in Figure A1, the keyword accepts four parameters. The first two are for positioning the window at a row/column and the second two are for sizing the window in terms of rows and columns. Note that the start-row and the start-column can be literals or variables.
Window size means the number of rows and columns your display file record information will occupy within the window border or frame. The space occupied by the window, including the frame, will always be larger than the window size specified in your DDS. Horizontally it will be four columns greater than the number_of_columns indicated in parameter four of the WINDOW keyword (one column for the left border, one column for the right border, one column for the leading window attribute byte and one column for the right border attribute byte). Vertically the window will be two greater than the number_of_rows indicated in parameter three of the WINDOW keyword (one row for the top border and one row for the bottom border).
After calculating the num-ber_of_rows required for your window, always add one to it. The reason for the extra row is because the last row of the window is reserved as a message line. You must always add one row to your window to allow the displaying of error messages, since the panel overlayed by the window is no longer active. For example, you might have a window displayed that doesn't allow the use of function key F6. When F6 is used, the system will display error message "Function key not allowed" in the last row of the window. If the message won't fit in the window, the system truncates the message on the right and substitutes ellipsis in the last three characters of the message line to indicate there is more text to display. Therefore, depending on the size of the window, the message might appear as "Function key not ...". If you are unable to interpret the messages that are truncated, simply use the Help key to display the entire message.
The optional WDWBORDER keyword describes the border (frame) of the window in terms of color and display attributes. It can be specified at the file or record level. If it is not used, the default border uses periods (.) for the top and bottom of the window frame and colons (:) for the left and right sides. The border characters' color defaults to blue. I normally use blanks as my border characters with reverse-image green as illustrated by the DDS in A2. This window is written to row 8, column 40 with a size of 10 rows and 20 columns. A3 illustrates this window as it would be displayed.
The optional WDWBORDER keyword describes the border (frame) of the window in terms of color and display attributes. It can be specified at the file or record level. If it is not used, the default border uses periods (.) for the top and bottom of the window frame and colons (:) for the left and right sides. The border characters' color defaults to blue. I normally use blanks as my border characters with reverse-image green as illustrated by the DDS in Figure A2. This window is written to row 8, column 40 with a size of 10 rows and 20 columns. Figure A3 illustrates this window as it would be displayed.
There are two ways to code the contents of a window: 1) as part of the window record format or 2) as a separate record format, in which case you link it to the window format with the WINDOW keyword; for example WINDOW(RCDFMT). With the second method, think of the window format as a frame for the content's format. If the window record format contains any fields or constants, then the second format displayed must use the OVERLAY keyword.
A maximum of 12 windows can be displayed on a screen at once. I imagine a screen with more than a few windows could start looking pretty cluttered. This is where the RMVWDW keyword can assist. By specifying it in a window format, you tell the system to clear all previously displayed windows prior to displaying the new window.
The USRRSTDSP keyword can be used to improve system performance when your windows are in a different display file or when you display a series of windows and have no need to return to an earlier window. Under these conditions, the system must perform two save screen operations: one when the display file is suspended and one when the window is displayed. The USRRSTDSP keyword eliminates the second of the two saves. This would most likely only be noticeable on a remotely attached workstation.
Perfecting DDS Windows in Modular Programs
Figure 1 CL Program XEM007CL
/*==================================================================*/ /* To compile: */ /* */ /* CRTCLPGM PGM(XXX/XEM007CL) SRCFILE(XXX/QCLSRC) */ /* */ /*==================================================================*/ XEM007CL: + PGM DCLF FILE(XEM007DF) DCL VAR(&OFFSET) TYPE(*DEC) LEN(4 0) DCL VAR(&RTNCDE) TYPE(*LGL) LEN(1) /* Prepare typical panel output */ CHGVAR VAR(&OFFSET) VALUE(1) LOOP: + CHGVAR VAR(%SST(&FULL &OFFSET 1)) VALUE('F') CHGVAR VAR(&OFFSET) VALUE(&OFFSET + 1) IF COND(&OFFSET *LE 1520) THEN(GOTO CMDLBL(LOOP)) CHGVAR VAR(&LRG1) VALUE('LLLLLLLLLLLLLLLLLLLLLLLLLLLLLL') CHGVAR VAR(&LRG1) VALUE(&LRG1 *TCAT &LRG1) CHGVAR VAR(&LRG2) VALUE(&LRG1) CHGVAR VAR(&LRG3) VALUE(&LRG1) CHGVAR VAR(&LRG4) VALUE(&LRG1) CHGVAR VAR(&LRG5) VALUE(&LRG1) CHGVAR VAR(&LRG6) VALUE(&LRG1) CHGVAR VAR(&LRG7) VALUE(&LRG1) CHGVAR VAR(&LRG8) VALUE(&LRG1) CHGVAR VAR(&LRG9) VALUE(&LRG1) CHGVAR VAR(&LRG10) VALUE(&LRG1) /* Initialize large window coordinates */ CHGVAR VAR(&STRLIN) VALUE(2) CHGVAR VAR(&STRCOL) VALUE(5) /* Display full screen */ DSP_FULSCN: + SNDRCVF RCDFMT(FULSCN) IF COND(&IN03 *OR &IN12) THEN(RETURN) /* F3 or F12 pressed */ ELSE CMD(DO) /* Enter pressed */ DSP_LARGE: + SNDRCVF RCDFMT(LARGE) IF COND(&IN03) THEN(RETURN) /* F3 pressed from window */ ELSE CMD(IF COND(&IN12) THEN(GOTO CMDLBL(DSP_FULSCN))) /* F12 + pressed from window */ ELSE CMD(DO) /* Enter pressed from window */ CALL PGM(XEM008CL) PARM(&RTNCDE) IF COND(&RTNCDE *EQ '1') THEN(RETURN) ELSE CMD(GOTO CMDLBL(DSP_LARGE)) ENDDO ENDDO ENDPGM
Perfecting DDS Windows in Modular Programs
Figure 2 Display File XEM007DF
*=============================================================== * To compile: * * CRTDSPF FILE(XXX/XEM007DF) SRCFILE(XXX/QDDSSRC) + * RSTDSP(*YES) * *=============================================================== *. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ...+... A DSPSIZ(24 80 *DS3) A PRINT A CA03(03 'Exit') A CA12(12 'Cancel') *===================================================================== A R FULSCN A BLINK A 1 2'FULSCN' A COLOR(BLU) A 1 33'Title Goes Here' A DSPATR(HI) A FULL 1520 O 3 1 A 23 2'F3=Exit F12=Cancel' A COLOR(BLU) *===================================================================== A R LARGE A BLINK A WINDOW(&STRLIN &STRCOL 15 60) A 1 1'LARGE' A COLOR(BLU) A STRLIN 3S 0P A STRCOL 3S 0P A LRG1 60 O 3 1 A LRG2 60 O 4 1 A LRG3 60 O 5 1 A LRG4 60 O 6 1 A LRG5 60 O 7 1 A LRG6 60 O 8 1 A LRG7 60 O 9 1 A LRG8 60 O 10 1 A LRG9 60 O 11 1 A LRG10 60 O 12 1 A 14 1'F3=Exit F12=Cancel' A COLOR(BLU) *. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ...+...
Perfecting DDS Windows in Modular Programs
Figure 3 CL Program XEM008CL
/*==================================================================*/ /* To compile: */ /* */ /* CRTCLPGM PGM(XXX/XEM008CL) SRCFILE(XXX/QCLSRC) */ /* */ /*==================================================================*/ XEM008CL: + PGM PARM(&F3_KEY) DCLF FILE(XEM008DF) DCL VAR(&F3_KEY) TYPE(*LGL) LEN(1) DCL VAR(&RTNCDE) TYPE(*LGL) LEN(1) /* Prepare typical panel output */ CHGVAR VAR(&SML1) VALUE('SSSSSSSSSSSSSSSSSSSS') CHGVAR VAR(&SML2) VALUE(&SML1) CHGVAR VAR(&SML3) VALUE(&SML1) /* Display small window */ DSP_SMALL: + SNDRCVF RCDFMT(SMALL) IF COND(&IN03) THEN(DO) /* F3 pressed */ CHGVAR VAR(&F3_KEY) VALUE('1') RETURN ENDDO ELSE CMD(IF COND(&IN12) THEN(DO)) /* F12 pressed */ CHGVAR VAR(&F3_KEY) VALUE('0') RETURN ENDDO ELSE CMD(DO) /* Enter pressed */ CALL PGM(XEM009CL) PARM(&RTNCDE) IF COND(&RTNCDE *EQ '1') THEN(CHGVAR VAR(&F3_KEY) VALUE('1')) ELSE CMD(DO) CHGVAR VAR(&F3_KEY) VALUE('0') GOTO CMDLBL(DSP_SMALL) ENDDO ENDDO ENDPGM
Perfecting DDS Windows in Modular Programs
Figure 4 Display File XEM008DF
*=============================================================== * To compile: * * CRTDSPF FILE(XXX/XEM008DF) SRCFILE(XXX/QDDSSRC) + * RSTDSP(*YES) * *=============================================================== *. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ...+... A DSPSIZ(24 80 *DS3) A PRINT A CA03(03 'Exit') A CA12(12 'Cancel') *===================================================================== A R SMALL A KEEP A BLINK A WINDOW(15 50 8 20) A USRRSTDSP A 1 1'SMALL' A COLOR(BLU) A SML1 20 O 3 1 A SML2 20 O 4 1 A SML3 20 O 5 1 A 7 1'F3=Exit F12=Cancel' A COLOR(BLU) *===================================================================== A R DUMMY A ASSUME A 1 2' ' *. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ...+...
Perfecting DDS Windows in Modular Programs
Figure 5 CL Program XEM009CL
/*==================================================================*/ /* To compile: */ /* */ /* CRTCLPGM PGM(XXX/XEM009CL) SRCFILE(XXX/QCLSRC) */ /* */ /*==================================================================*/ XEM009CL: + PGM PARM(&F3_KEY) DCLF FILE(XEM009DF) DCL VAR(&F3_KEY) TYPE(*LGL) LEN(1) /* Prepare typical panel output */ CHGVAR VAR(&MED1) VALUE('MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM') CHGVAR VAR(&MED2) VALUE(&MED1) CHGVAR VAR(&MED3) VALUE(&MED1) CHGVAR VAR(&MED4) VALUE(&MED1) CHGVAR VAR(&MED5) VALUE(&MED1) CHGVAR VAR(&MED6) VALUE(&MED1) CHGVAR VAR(&MED7) VALUE(&MED1) /* Display medium window */ DSP_MEDIUM: + SNDRCVF RCDFMT(MEDIUM) IF COND(&IN03) THEN(DO) /* F3 pressed */ CHGVAR VAR(&F3_KEY) VALUE('1') RETURN ENDDO ELSE CMD(DO) /* F12 or Enter pressed */ CHGVAR VAR(&F3_KEY) VALUE('0') RETURN ENDDO ENDPGM
Perfecting DDS Windows in Modular Programs
Figure 6 Display File XEM009DF
*=============================================================== * To compile: * * CRTDSPF FILE(XXX/XEM009DF) SRCFILE(XXX/QDDSSRC) * *=============================================================== *. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ...+... A DSPSIZ(24 80 *DS3) A PRINT A CA03(03 'Exit') A CA12(12 'Cancel') *===================================================================== A R MEDIUM A KEEP A BLINK A WINDOW(6 25 12 37) A USRRSTDSP A 1 1'MEDIUM' A COLOR(BLU) A MED1 37 O 3 1 A MED2 37 O 4 1 A MED3 37 O 5 1 A MED4 37 O 6 1 A MED5 37 O 7 1 A MED6 37 O 8 1 A MED7 37 O 9 1 A 11 1'F3=Exit F12=Cancel' A COLOR(BLU) *===================================================================== A R DUMMY A ASSUME A 1 2' ' *. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ...+...
Perfecting DDS Windows in Modular Programs
Figure 7 Desired Output
UNABLE TO REPRODUCE GRAPHICS
Perfecting DDS Windows in Modular Programs
Figure A1 Formats of Record-level Keywords
WINDOW(start_row || &start-row-variable start_column || &start-column-variab number_of_rows number_of_columns) WDWBORDER([(*COLOR color)] [(*DSPATR display_attribute)] [(*CHAR 'border_characters')]) Valid *COLOR codes are: BLU, GRN, WHT, RED, TRQ, YLW, and PNK Valid *DSPATR (display attribute codes) are: BL - Blink CS - Column separator HI - High intensity ND - Nondisplay RI - Reverse image UL - Underline The *CHAR expression requires eight border characters which have positional significance. The meaning and the default characters of the eight positions in order are: Window Border Position Default Character top-left-corner period (.) top-border period (.) top-right-corner period (.) left-border colon (:) right-border colon (:) bottom-left-corner colon (:) bottom-border period (.) bottom-right-border colon (:) If the *CHAR expression is used, you must specify all eight characters. For more detail about these keywords, see the AS/400 Data Description Specifications Reference (SC41-9620, CD-ROM QBKA7401).
Perfecting DDS Windows in Modular Programs
Figure A2 DDS for a Window Using the Window Keywords
... 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ...+ A R TESTFMT WINDOW(08 40 10 20) A WDWBORDER((*COLOR GRN) + A (*DSPATR RI) + A (*CHAR ' ')) * The KEEP keyword is used to prevent the screen from blinking when * this display file overlays a screen format from another * display file. A KEEP A 01 01'The size of this ' A 02 01'window is ' A 03 01'20 columns wide ' A 04 01'and ' A 05 01'10 rows deep. ' A 06 01'The last row is ' A 07 01'reserved for a ' A 08 01'message line. ' ... 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ...+
Perfecting DDS Windows in Modular Programs
Figure A3 Window for the DDS in Figure A2 as it would appear
UNABLE TO REPRODUCE GRAPHICS.
More than ever, there is a demand for IT to deliver innovation. Your IBM i has been an essential part of your business operations for years. However, your organization may struggle to maintain the current system and implement new projects. The thousands of customers we've worked with and surveyed state that expectations regarding the digital footprint and vision of the company are not aligned with the current IT environment.
TRY the one package that solves all your document design and printing challenges on all your platforms. Produce bar code labels, electronic forms, ad hoc reports, and RFID tags – without programming! MarkMagic is the only document design and print solution that combines report writing, WYSIWYG label and forms design, and conditional printing in one integrated product. Make sure your data survives when catastrophe hits. Request your trial now! Request Now.
Forms of ransomware has been around for over 30 years, and with more and more organizations suffering attacks each year, it continues to endure. What has made ransomware such a durable threat and what is the best way to combat it? In order to prevent ransomware, organizations must first understand how it works.
Disaster protection is vital to every business. Yet, it often consists of patched together procedures that are prone to error. From automatic backups to data encryption to media management, Robot automates the routine (yet often complex) tasks of iSeries backup and recovery, saving you time and money and making the process safer and more reliable. Automate your backups with the Robot Backup and Recovery Solution. Key features include:
Business users want new applications now. Market and regulatory pressures require faster application updates and delivery into production. Your IBM i developers may be approaching retirement, and you see no sure way to fill their positions with experienced developers. In addition, you may be caught between maintaining your existing applications and the uncertainty of moving to something new.
IT managers hoping to find new IBM i talent are discovering that the pool of experienced RPG programmers and operators or administrators with intimate knowledge of the operating system and the applications that run on it is small. This begs the question: How will you manage the platform that supports such a big part of your business? This guide offers strategies and software suggestions to help you plan IT staffing and resources and smooth the transition after your AS/400 talent retires. Read on to learn:
LATEST COMMENTS
MC Press Online