If you’re an RPG programmer, you can use your existing skills to develop dynamic Web pages. In this article, I will describe a method that is fast and easy, doesn’t require expert knowledge of HTML, and even allows you to use PC HTML editors like Microsoft FrontPage and Macromedia’s DreamWeaver. At the heart of this method is the RPG SPECIAL device.

What’s So SPECIAL?

The SPECIAL device directs file output to an external program and not to a file object, as is normally the case. This has great implications for Web development, as it separates logic from presentation. Think of the report programs and interactive programs you write. You could edit all numeric fields in the calculation specs and concatenate long lines of output, but it’s easier to let the system do that work for you by coding output specs or printer and display files. The same is true for Web programs.

I have written two programs that you can use with the SPECIAL device: WEBOUTPUT and WEBOUTFIL. Figure 1 lists these two programs along with other programs and commands that make up a CGI toolkit for RPG programmers. These objects, along with a few other supporting objects and four example CGI programs, are stored in a library called MCWEBCGI, which you can download at www.midrangecomputing.com/mc.

Both WEBOUTPUT and WEBOUTFIL receive data from the SPECIAL file and send it to the Web. They differ in that WEBOUTPUT is designed for use with output specs, while WEBOUTFIL uses HTML stored in source members. Using these programs lets you focus the calculation specifications of your program on doing what you want to do in the application, not on the Web output process. Because of space constraints, I can’t explain the internals of WEBOUTPUT and WEBOUTFIL here, but I can explain how you can use them to generate Web pages.

The downloadable code for this article is source code only. Use the Create Library (CRTLIB) command to create a library called MCWEBCGI, and place the source code into it. Add MCWEBCGI to your library list, then compile and call program TOOLCMPL to compile the CGI programs. Next, compile and call EXMPCMPL to create the four examples.

In order to use the tools in MCWEBCGI or run the example programs, add the directives in Figure 2 to your HTTP server configuration and restart the server. The Map directive tells the server how to interpret the URL you enter on your browser. The left side of the Map directive is the pattern, and the right side is the replacement value. The asterisk
(*) is the wildcard symbol. For example, if you type the URL http://yoursystem/MCWEBCGI/EXAMPLE1, the map directive adds the .PGM suffix. The Exec directive tells the server where to find the program you want to run. In this case, when a browser requests a program from directory mcwebcgi, OS/400 will run the program from library MCWEBCGI in the QSYS.LIB file system.

Hard-coded Output Specifications

EXAMPLE1, part of which is shown in Figure 3, is a simple program that displays the date and time. TIME is placed in a time stamp field and then moved to a time field and a date field. An EXCEPT is done to WebOut (the SPECIAL device file), sending all of the hard-coded HTML to the WEBOUTPUT program. Here is how EXAMPLE1 and WEBOUTPUT interact:

1. Point your browser to http://yoursystem/ MCWEBCGI/EXAMPLE1, where yoursystem is the domain name or IP address of your iSeries (AS/400) machine.

2. The HTTP server calls the program.

3. EXAMPLE1 sends output via the SPECIAL device to the WEBOUTPUT program.

4. The WEBOUTPUT program sends the information to the HTTP server.

5. The HTTP server sends the data to your browser.

Receiving Input from a Page and Using Repetitive Detail Output

Just as there are APIs to get data to a Web page, there are also APIs to receive input from a Web page. I have wrapped some of these input-related APIs into the CGISTDIN program. The CGISTDIN program retrieves any input fields from your page and formats them according to the field descriptions in a file you specify. The EXAMPLE2 program reads a Web page that has one input field called NUM2. Here is the HTML for this field:

The field NUM2 is defined as a signed numeric five positions long with two decimal places. The definition is in a physical file called EXAMPLE2.

The CGISTDIN technique requires you to have a file that defines the fields you expect to receive from your page. They do not have to be specified in the same order as they appear on the page. The file is only used as a template for input data and never contains any data. I generally give this file the same name as the program and put it in the same library as the program object.

You will need to have the file present at compile time, so check the library list before you compile. This may seem a great deal of work, but I find it much easier than parsing the input in the program.

Figure 4 (page 74) contains snippets of code that show how to use CGISTDIN. Call CGISTDIN in the *INZSR subroutine. Provide the name of the file that will be used to format the Web input and the name of the library that the file lives in. When your program starts, CGISTDIN is called and returns the formatted Web data to the field BuffIn.

But notice that BuffIn is another name for the data in data structure STDIN, which is externally described by the format file. Therefore, the data structure is overlaid with the data returned from CGISTDIN, and presto! The Web data is present in your program!

Using an External HTML File

Examples 1 and 2 use program WEBOUTPUT to send hard-coded HTML to a Web browser. Examples 3 and 4 use program WEBOUTFIL to send HTML from a source member to a browser.

Using WEBOUTFIL separates logic from presentation, much like using a display or print file. Further, it allows the page to be designed and modified with PC HTML editors such as FrontPage and DreamWeaver.

When EXAMPLE3 sends data to WEBOUTFIL, it also sends the name, library, and format of the HTML file to WEBOUTFIL. WEBOUTFIL retrieves the HTML statements, merges them with the program data, and sends it all along to the Web.

To keep things easy, I put the HTML source in a source file named QHTMLSRC, which has a record length of 162. This long record length helps avoid some problems with FrontPage, because FrontPage can create some very long lines of HTML.

Figure 5 (page 74) shows source code for program EXAMPLE3. Notice that WEBOUTFIL has a PLIST called SPCL associated with it. SPCL has four parameters (library, file, member, and format). The library, file, and member are hard-coded, and the format parameter is set before each write.

Figure 6 has the HTML source EXAMPLE3. It looks much like regular HTML, but there are new tags such as and . These tags describe how data is inserted into the Web page. WEBOUTFIL uses these tags to describe the data received from EXAMPLE3 but does not send them to the Web.

There are strict rules for the use of special tags. The foremost rule is that the tags are fixed-format and must start in position 1 of the HTML source line in which they appear. You can find complete rules in member DIRECTIVES of file MCWEBCGI/README.

The SPECIAL device in EXAMPLE3 uses an externally defined file, also named EXAMPLE3, which is generated from the HTML source by a utility called MVQSYSIFS.

In EXAMPLE2, I had to create DDS and compile it to create a format for input. In EXAMPLE3, all of the specifications are already in the HTML source. MVQSYSIFS converts these specifications into DDS and creates the file for me. The file is generated as a display file, simply because display files support multiple formats.

Note that in the HTML source, I also defined a format called INPUT to serve as the overlay for input data. Putting the definition for INPUT in the HTML source saves the additional effort of coding and compiling separate DDS for the input overlay.

Remember, MVQSYSIFS creates the externally described file. It is not used during the execution of a CGI program. If you change anything in the

How the External Editor and the MVQSYSIFS Utility Fit In

PC HTML editors use ASCII data in PC files. WEBOUTFIL uses EBCDIC data in AS/400 source physical files. How do I get the PC editor to work on AS/400 source physical files? I don’t. MVQSYSIFS does more than file generation. Namely, MVQSYSIFS can move source file members to AS/400 IFS files and back again.

You must create an AS/400 IFS directory to act as a workspace. I call this directory WEBWORK. In order to access this directory from the PC, I set up NetServer and mapped the WEBWORK AS/400 directory to a PC drive.

I used FrontPage to generate the HTML source for EXAMPLE4, as FrontPage is very common (and inexpensive). FrontPage is a great starter editor, because it tries to do a lot of things for you. But because it tries to do a lot of things for you, FrontPage can be difficult to use. The biggest problem is FrontPage’s desire to press lines together, thus removing the left justification required by WEBOUTFIL. There is a way around this.

FrontPage has a feature to insert false HTML tags. Here are the keystrokes:

1. Click Insert.
2. Click FrontPage Component.
3. Click Insert HTML.
4. Click OK.

A box will pop up for you to key in. Press Enter once before and after the special tags you key in. This will preserve the left justification.

When you switch to the HTML source view in FrontPage, you will see that the generated code is not very pretty, but remember what you gained: no manual HTML to code.

I saved the page as EXAMPLE4.HTM to the NetServer-mapped AS/400 drive (WEBWORK). Then I went to the “green” world and ran MVQSYSIFS to move the file from AS/400 IFS to QSYS and also compile the output file for the program. Remember that the AS/400 IFS version is not used during execution of your program. The AS/400 IFS version is used only to facilitate working with an external PC HTML editor.

If you look at the HTML source I generated with FrontPage, you’ll see that it did not contain the HTML/TEXT statement. This content information must be at the top of the HTML source. FrontPage does not understand that this should go at the top and consistently moves it into the body. To get around this problem, I wrote a small CL program called CONTENT. I call this program in the *INZSR subroutine to get the content information to the browser.

So, if you need to make a simple change to the HTML source, you can do it with SEU. But for a more extensive change, you can move the source back to the AS/400 IFS with MVQSYSIFS, make your change with a PC HTML editor, and then move the source back again to a source physical file with MVQSYSIFS.

Possible Enhancements

I was under pressure to stop playing and start producing, so I didn’t incorporate a number of enhancements. The main enhancement I see would be to use APIs to read the HTML source directly from the AS/400 IFS. This would remove the requirement for left justification and fixed format spacing on the special tags. Please feel free to rip it up and add this and any other functions you think of (and please keep me posted).

My intent with these techniques was to create an easy way for RPG programmers to generate Web pages without the need for Java, Java Server Pages (JSPs), or WebSphere knowledge. Java, JSPs, and WebSphere do many things you cannot do with these techniques, so don’t stop learning the new stuff. In the meantime, install the MCWEBCGI toolkit and study and run the four example programs. Then you’ll be able to use WEBOUTPUT and WEBOUTFIL with the SPECIAL device to get your pages on the Web with a minimum of effort.

MEMBER TYPE DESCRIPTION

TOOLCMPL CLP Create the CGI tools in MCWEBCGI

CONTENT CLP Insert HTML/TEXT statement at top of HTML source

CRTWOF CMD Create DDS from HTML

MVQSYSIFS CMD Copy files between a library and AS/400 IFS

CGISTDIN RPGLE Read STDIN and format data

CGISTDOUT RPGLE Write to STDOUT

WEBOUTFIL RPGLE Write to a Web browser from a source file

WEBOUTPUT RPGLE Write to a Web browser from output specs

Figure 1: The CGI toolkit consists of objects that wrap IBM’s APIs.

Map /MCWEBCGI/* /MCWEBCGI/*.PGM
Exec /mcwebcgi/* /QSYS.LIB/MCWEBCGI.LIB/*

Figure 2: Use these directives to make the HTTP server find your CGI programs.

FWebOut o f 500 special pgmname('MCWEBCGI/WEBOUTPUT')

D TimeStamp s Z
D TimeOut s T
D DateOut s D datfmt(*USA)

C time TimeStamp
C move TimeStamp TimeOut
C move TimeStamp DateOut
C except Head

OWebOut e Head
O 'content-type: text/html'
O X'15'
O X'15'
OWebOut e Head
O ''
O X'15'
O ''
O X'15'
O ''
O X'15'
O ''
O X'15'
OWebOut e Head
O '
'
O X'15'
O 'The time is '
O TimeOut
O X'15'
O '
'
O X'15'
O 'The date is '
O DateOut
O X'15'

Figure 3: Coding HTML in output specs is acceptable for small applications.

D StdIn e ds extname(example2:input)
D BuffIn 1 1024

C *inzsr begsr

* Clear any numerics in the input overlay structure

* to prevent decimal data error if no input
C clear num2

* Do STDIN to get screen input
C call 'CGISTDIN'
C parm 'EXAMPLE2' FilNam 10
C parm 'MCWEBCGI' LibNam 10
C parm BuffIn

Figure 4: The CGISTDIN program makes easy work of retrieving input values.

FEXAMPLE3 o e special pgmname('MCWEBCGI/WEBOUTFIL')
F plist(spcl)

DContentDta s 100 inz('content-type: text/html')

D StdIn e ds extname(example3:input)
D BuffIn 1 1024

D TimeStamp s Z
D TimeWrk s t
D DateWrk s d datfmt(*USA)

C eval OutFmt = 'HEADER'
C write Header
C exsr do_Tables
C eval OutFmt = 'FOOTER'
C write Footer
C eval *inlr = *on

* Do the mult tables
C do_Tables begsr
C eval OutFmt = 'DETAIL'
C eval X = 1
C dou X > 10
C eval result = X * num2
C write Detail
C eval X = X + 1
C enddo
C endsr

C *inzsr begsr

* Output content
C call 'CONTENT'
C parm ContentDta

* Clear any numerics in the input overlay structure
* to prevent decimal data error if no input
C clear num2

* Do STDIN to get screen input
C call 'CGISTDIN'
C parm 'EXAMPLE3' FilNam 10
C parm 'MCWEBCGI' LibNam 10
C parm BuffIn

* Setup date and time for header
C time TimeStamp
C move TimeStamp TimeWrk
C move TimeWrk TimeOut
C move TimeStamp DateWrk
C move DateWrk DateOut

C spcl plist
C parm 'MCWEBCGI' OutLib 10
C parm 'QHTMLSRC' OutFil 10
C parm 'EXAMPLE3' OutMbr 10
C parm OutFmt 10

C endsr

Figure 5: The best way to write RPG CGI programs is to put HTML source in separate source members.


NUM2 00005 02 >

-->


TIMEOUT 00008
DATEOUT 00010 >

-->




WEB SPECIAL DELIVERY VIA WEBOUTFIL

EXAMPLE3 

 

MULTIPLY BY

X 00002 00 J

NUM2 00005 02 J
RESULT 00006 02 J >

-->





TIMES

IS

Figure 6: A few nonstandard HTML tags can save you a lot of work.

Also Read

RPG Academy - Database Modernization: Entity Relationship Diagrams

RPG Academy - Database Modernization: A Bit of Database Theory

Talking About Modernization Isn’t Good Enough