All three of the examples presented here follow the same model: The RPG IV procedures take one varying-length character parameter and return a varying-length character value. Within the procedure, there's a loop over each character of the input. The character is changed if necessary and is then appended to the result.
All three examples demonstrate modifying some text that will be used as input to some other program, an increasingly common programming technique these days. These filters are necessary to ensure that the text is valid input to the other program.
At the end of this tip, I've included two files (Figures 1 and 2). File FILTERS includes the procedures and instructions for use. File TESTFILTS demonstrates how to use the filters.
The first procedure, "QUOTE()", should be used when dynamically constructing SQL queries. For example, you might want to build a query where some value is included in the query as a character literal. Not only are apostrophes needed at the beginning and end, but since apostrophes delimit literals, something must be done with apostrophes within the value. To have a syntactically correct literal, apostrophes within the literal must be doubled. Procedure "QUOTE()" does just that.
The second procedure, "ESCAPE_HTML()", is needed for applications that create HTML documents. Like the apostrophe within SQL literals, certain characters have special meaning within HTML documents. In particular, the less-than and greater-than characters (< and >) bracket HTML tags. When an HTML browser encounters a <, it assumes it has reached an HTML tag. Any text between the < and the > is treated as an HTML tag and is not presented to the user. If you insert text from a database into an HTML document without escaping the special characters, some important text may be invisible to the client. Likewise, the ampersand (&) signals the start of an HTML character entity, so that character needs special treatment too. The solution is to convert the characters <, >, and & to the appropriate character entities:
< = <
> = >
& = &
The final example illustrates a common situation in CGI programming. CGI programs often dynamically build URLs. For example, "http://www.mysite.ca/req?userid=hans&pw=glorp." But notice again that some characters have special meanings within the URL. The question mark (?) identifies the beginning of the parameters. The ampersand (&) separates individual parameters. And the equals sign (=) separates the parameter name from the parameter value. In addition, spaces are not allowed within the string. If you construct a query string with one of the special characters within the text of a parameter, a CGI program may justifiably end up confused. So what do we do if we want one of these special characters within a URL parameter value?
The solution is to convert any "non-safe" character to a hex code prefixed by a percent sign (%), yet another character with special meaning! You've probably seen URLs containing lots of funny characters like %25 or %5E. Procedure ENCODE_QUERY() converts the "non-safe" characters to their appropriate hex value suitable for use in a CGI query string.
These days, when more and more programs construct text intended to be processed by some other program, it is vitally important to build that text in a form that's acceptable to the other program. At best, the program will just abend, and the bug will become obvious to the programmer before the application is made public. Worse, incorrect text could be displayed to clients. At the extreme, errors in constructing URLs could potentially open a server to hacking.
Figure 1: The Procedures and Instructions for Use
Figure 2: How to Use the Filters