Wrapping Free Form Text

Note: The code accompanying this article is available for download here.

One common integration problem encountered by those building client/server or Web-based interfaces to a legacy green-screen application is mapping a free form text field into a fixed width field. This tip presents a code segment I wrote to solve this problem.

For example, say you have the following DDS defined legacy table called ORDCOMT that is designed to store the comments for a customer order:

In the legacy application, a customer service representative enters the customer’s comments line by line in a green screen where the entry fields are limited to 25 characters. Now you bolt a Web front end on your legacy order entry system, but there is a small problem–who in the Web world wants to enter order comments 25 characters at a time? No one. Typically, Web-based front ends allow the user to type their comment(s) in one large free form box.

Enter the “WrapText” RPG subprocedure (code is available at the beginning of article). The prototype for the subprocedure is as follows:

D	WrapText	PR	12288 
D	UnfText		8192	Varying Const Options(*VarSize)
D	LineLen		5 	0 Const
D	LineBreak		10	Varying Const Options(*NoPass)

“WrapText” will receive up to 8K of unformatted text and “wrap” it into multiple lines based on a specified line length. If the free form text allows embedded line break codes (such as carriage return and line feed), the new line indicator can be passed as an optional parameter. The utility will generate new lines automatically when it encounters a line break code.

The utility returns a fixed length text field (12K) containing pseudo-lines formatted at the specified line length. The calling program will need to process this text field either by overlaying an array of the appropriate element size on the returned data or by parsing the data manually.

For example, if variable “FmtText” holds the result of the “WrapText” procedure for a line length of 25 characters, you could extract line two from the variable as follows:

Line2=%Subst(FmtText:26:25);

Or in general, extract any line using variables:

(LineNo=line to extract, LineLen=length of line):
AnyLine=%Subst(FmtText:(LineNo-1)*LineLen+1:LineLen);

As an added goodie, I created an SQL table function wrapper, (subprocedure WrapText_TF), that allows “WrapText” to be used by SQL (see code at the beginning of this article for the required CREATE FUNCTION statement to use WRAPTEXT with SQL).

For example, the following query converts free text into a tabular format, with each wrapped line being assigned its own row:

Select * 
From Table(WrapText( 
'The quick brown fox jumps over the lazy dog',25,'')) A

The result set returned is as follows:

LINENO	LINETEXT 
1	The quick brown fox jumps 
2	over the lazy dog 

Wrapping at 15 characters per line instead of 25, the results are adjusted accordingly:

LINENO 	LINETEXT
1	The quick brown
2	fox jumps over 
3	the lazy dog 

For one more example, the following sample free form comment has an embedded carriage return and line feed (EBCDIC X’0D25′) that causes an additional break to be inserted:

Select * 
From Table(WrapText( 
'The quick brown fox jumps over'||x'0D25'||'the lazy dog',25,
x'0D25')) A 

The above query returns the following (including a forced new line after the word “over”):

LINENO	LINETEXT
1	The quick brown fox jumps
2	over 
3	the lazy dog 

This table function can ease the conversion of free form text into the ORDCOMT DB2 table mentioned above as follows:

Insert Into OrdComt
Select :OrdId, LineNo*10 As Seq, LineText
From Table(WrapText(:Comment,25,X'0D25')) Comments

As a final thought, this utility has other uses. I’ve used it to display free form comments from a database table on the good old fixed width green screen. I’ve also used this utility to wrap computer generated SQL statements into a more readable format (just a warning, this utility is not smart enough to consider constants with embedded spaces as a single “word,” so the wrapping may not occur correctly.) A little imagination can find many uses.

Michael Sansoterra is a programmer/analyst for i3 Business Solutions, an IT services firm based in Grand Rapids, Michigan. You can email him at the IT Jungle contact page.

                     Post this story to del.icio.us
               Post this story to Digg
    Post this story to Slashdot