One of the cool things about PC-based text-editing tools, such as Microsoft Word, is the word wrap feature. With this feature, you fill in one line with text and the word processor automatically jumps to a new line. This prevents words from being split between two lines, and makes your text look better. Now you can achieve word-wrapping functionality with this green-screen utility!

WW000R1 is an RPG IV program that runs the display file and which contains the word wrapping algorithms.

WW000C1 is a CL program used to demonstrate how to call the RPG program, so that you can plop the word wrapping functionality right into your own applications.

The word wrap utility (Figure 1) can be easily achieved in your own applications.

In fact, you don't even have to understand how the utility works to use it. Simply call it as I do in the WW000C1 example program. But just in case you want to know how it works, let's look at these source files in a bit more detail.

The CL program is used to call the RPG program. An empty field with a length of 7,500 characters is passed to the RPG program. This field will contain the formatted text that the user types into the subfile. You can increase or decrease the size of this field based on your own needs. You can pass previously formatted text into the RPG program, if you like, in this field. When you do, that text will be loaded into the subfile for you. This allows you to edit previously saved text.

A second field can be used to pass a dynamic text string that you can use for the "heading" of the word wrap utility. Enter anything you want into this field, and it will be centered into the word wrap utility's header. Finally, a numeric field is passed to the utility. This field will indicate to the calling program (the CL, in this case) how many lines of text were entered by the user. This is important because, if you reload previously formatted and saved text back into this utility, you'll need to let the utility know how many lines of text were created the first time, as opposed to what was just entered. You'll load that value into the last parameter. When control returns to the caller, you can store that value, along with the formatted text, for subsequent edits.

The display file is nothing spectacular. It's nothing more than a window that contains a subfile. If you wanted to make this a non-windowed subfile for some reason, simply remove the Window keywords.

The only other things you need to be aware of in this display file are the use of the CHECK(ER) keyword on the subfile entry line and the use of the SFLCSRRN and CSRLOC keywords.

I use the CHECK(ER) keyword because I want the RPG program to respond automatically when the cursor reaches the end of the subfile line. CHECK(ER) causes an automatic Record Advance to occur.

I use the SFLCSRRN and CSRLOC keywords so that I always know what line of the subfile the cursor is on, and also what its exact coordinates are (like the line number and the position on that line).

The RPG IV program is where the brains of the utility exist. The first thing that happens when the program is called is that the heading text passed to it is centered and then placed into the subfile heading.

Next, the subfile is initialized. Notice I didn't say cleared. The subfile is initialized, using SFLINZ instead of SFLCLR, which would clear it, so that we can display empty lines for the user to type text into. The user will then type text into the subfile. When the cursor reaches the end of the line, the CHECK(ER) keyword will kick in and the RDSFL subroutine will be executed.

The RDSFL subroutine reads the subfile. Here's where it gets slightly complicated. A work array is cleared and then loaded with all the user-entered text from the subfile. Next, the WRDWRP subroutine is executed to see if the text needs to be formatted so that word wrapping occurs.

The current subfile line number is retrieved using the SFLCSRRRN keyword from the display file. The field named SRRN is associated with this keyword and will always contain the current subfile line number. If the current subfile line (stored as text in the word array) is not blank, that line of text is loaded into a work variable. A simple use of the CHECKR keyword is called to find the last non-blank character in the string. Since our subfile is only 50 characters long, we can assume that if a non-blank character is found in position 49 or 50, we need to move this word onto the next line. If we didn't, the word would likely break incorrectly. This is, of course, assuming that we never want a word to end in the last position of the last line.

Next, some simple logic is performed to find the beginning of the last word on that line (by locating the previous blank space), and that word is moved, character by character, to the next line by moving that word to another work variable. In addition, the characters that were moved are removed from the work array where they were first found. This ensures that the word is actually "moved" to the next line and that we don't end up with two versions of the same word on two lines.

The last thing we do, before allowing the user to continue entering text (and this all happens really fast!), is to retrieve the current cursor position from the CSRLOC DDS keyword XROW and XCOL fields. We'll use the values we retrieve from those fields to display the current page number of the subfile, as well as the current line of text the user is typing data into. This last part isn't absolutely required, but it's a nice touch. It allows the users to tell at a glance what page of data they are on.

As the user enters data or presses the Enter key to move to a new line, we track the position of the cursor. When the cursor reaches the eleventh line, we automatically scroll the subfile to the next page and reset the line count. This allows the users to perform heads-down data entry, as they don't have to remember to scroll to the next page.

When the user is ready to exit the utility, he will press the F5 function key to save his text. It is at this point that we read the subfile, load the text the user entered into the subfile into a work array, and then pass that data, along with the number of subfile lines that contain text, back to the calling program. The caller can then store this formatted text and the line count, in a database file, where it can be printed or displayed on another screen, or whatever he wants to do with it.

This utility can be used, as is, by any RPG program that needs the ability to allow free-form text to be entered. Simply replace the CL program I've given you here as an example with your own calling program. You can also increase the functionality of this utility, with just a little bit of work, so that you can support text insertion, deletion, and other common text-editing functionality. Have fun with it, and hopefully you will find it as useful in your applications as I have in my own.