I must admit, I haven't written any new 5250 green-screen applications for a while. Most of my work has entailed doing Web browser-based applications and, of course, the infamous file maintenance applications.

But recently, I needed to create a new application for a handheld scanner that uses a Telnet emulator. The screen is small, and most applications that run on it have been designed to work with the 40-column by 12-row screen dimensions.

When I ran the application, I discovered that if a message is sent to the device, either by an application or by the system, particularly an inquiry message, all bets are off. The end user has to manually scroll the screen to see the message. Of course, the end users' skill in using iSeries/i5 applications is virtually nonexistent, so it's a challenge for them to continue working when a message is sent.

I remembered that back in the days of Q38 I designed the first windowed 5250 application using DDS. One of the biggest problems was word wrapping/pagination, i.e., the ability to adjust the output of a text field so that the breaks in the text appear on the space between the words, rather than at a fixed location.

I had written a word-wrap routine, and thought I could locate it and use it for this particular problem. So I fired up my old AS/400 Model 400 that I keep on OS/400 V3R7 (mostly because I can't afford to upgrade it) and began searching for my old code.

As the system was IPLing, I began flipping through the OS/400 V4R2 DDS manual, and just for the heck of it, I looked up "word wrap" in the index. To my astonishment, I found it!

The WRDWRAP keyword automatically paginates an input field. I thought that would be a showstopper, but by definition, a Both field is also an Input field, so I could simply create a field as Both (i.e., input and output) on my display file and then use the "protect" attribute to make it output-only. Fortunately, this worked.

I also knew IBM had added the Continued Field keyword a long time ago, and I thought that if I could use that, I could effectively create a little text box within a window that might fit on my 40-by-12 devices.

Continued Fields

A continued field is a long text field that is wrapped to multiple lines. You provide the field's overall length and the "line size." Then the system wraps the field over multiple lines, each to the length you've specified.

To create a continued field, use the CNTFLD keyword as follows:

In this example, the field named MSGTEXT is 320 positions long. The CNTFLD keyword indicates that 40 characters per line are allowed. This means the MSGTEXT field will occupy 8 lines (320/40) of 40 characters each.

Word Wrap

The bad news is that CNTFLD alone will give you little more that what we already had, positional wrap. As you type, the text will wrap to the field, based on the line length and character position, not based on the content of the field itself. This provides somewhat unpleasant looking data.

Enter WRDWRAP. This keyword will cause the wrapping of the text in the continued field to be at the location of a space (i.e., between words). This provides a much more attractive look to the data.

Remember, WRDWRAP may be used only on an input-capable field, so the field must be "I" (input only) or "B" (input/output or "Both"); output-only fields are not supported by WRDWRAP.

To use the WRDWRAP keyword, simply specify it at the record format level or on the specific field itself, as follows:

In the example, the MSGTEXT field will now be word wrapped while typing or when text is output to the field. This is exactly what I needed.

Of course, my requirement was to have output-only text. To accomplish this, I had to add the DSPATR(PR) keyword as follows:

This causes the field to be output only, but it still fulfills the requirements of WRDWRAP by being both input- and output-capable.

There is one thing still missing, however. The output is underlined. This isn't what I wanted (but you may want an underlined appearance).

To get rid of the underline, I simply added the CHGINPDFT keyword to the field itself:

Ah, perfection! Now, I have an output field that paginates within the dimensions of the device limitations. Next, all I have to do is put this inside a window.

When I create a window, I often omit the border because the 5250 emulators today use a nice drop shadow box as the default border for windows. A window with periods and colons as a border was interesting in 1987 but is just ugly today.

Here's the window definition:

The *DFT parameter on the WINDOW keyword causes the window to be located relative to the cursor location. This isn't good enough for what I needed, so adding an absolute location was required. And don't ask me what USRRSTDSP does; I just use it now in place of all the PUTOVR and OVRATR keywords, which I never fully understood anyway, and it seems to work OK.

CL Break Handler

Designing an output window and word wrapping was only half the battle. Next was remembering how to code a break message handler. Fortunately, I'm still good friends with Greg Veal, so I called him up for the answer. He suggested I look in his book CL Programming for the AS/400. Within two minutes, I located and was able to review how to create a simple break message handling program.

A break handler is a program that is called when a break message (such as an inquiry message) is sent to the display. Instead of breaking in on the device, the break handling program is called and passed just enough information to be useful.

The break handler is passed to the Message Queue and Message Queue Library names, along with the so-called "message key." Each message delivered to a message queue has a unique key associated with it. You can retrieve, remove, and reply to a message by its message key.

These three pieces of information are passed to your break handling program as three separate parameters:

In CL, you might code these parameters as follows:

Once your break-handling program is called, you can do anything you want, but it would be good to do something with the message that evoked the program.

To receive the actual message, use the RCVMSG command as follows:

The &MSGTEXT variable is the field we've specified on our display file (in the window). The &MSGTYPE variable is 2-byte code that indicates the type of message that is being received.

Once we receive the message, we can display its text in our continued/word-wrapped field within the window on the handheld device, thereby avoiding the scrolling screen problem we were encountering

Figure 1contains the full DDS source for the word-wrap text in a window display file named MSGWINDOW. Note the extra "dummy" format that is used to avoid having the system clear the screen as the window pops up. This is useful on regular displays because it provides that overlapping look and feel people are used to.

Figure 1: This is the display file DDS for the pop-up window.

Listed in Figure 2 is some example CL source for a break-handling program that pops up the message window. In addition, the program reacts to standard DSPMSG-like function keys including F3, F11, F12, and F13, performing the same type of function.

Figure 2: This break-handling program pops up the message window.

Bob Cozzi is a programmer/consultant, writer/author, and software developer. His popular RPG xTools add-on subprocedure library for RPG IV is fast becoming a standard with RPG developers. His book The Modern RPG Language has been the most widely used RPG programming book for more than a decade. He, along with others, speaks at and produces the highly popular RPG World conference for RPG programmers.