Thu, Jun
3 New Articles

Web SPECIAL Delivery

  • Smaller Small Medium Big Bigger
  • Default Helvetica Segoe Georgia Times

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.



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


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

CGISTDIN RPGLE Read STDIN and format data


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.

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 ''<BR>O 'EXAMPLE1'<BR>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 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 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 >


DATEOUT 00010 >







X 00002 00 J

NUM2 00005 02 J
RESULT 00006 02 J >




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



Support MC Press Online

$0.00 Raised:

Book Reviews

Resource Center

  • SB Profound WC 5536 Have you been wondering about Node.js? Our free Node.js Webinar Series takes you from total beginner to creating a fully-functional IBM i Node.js business application. You can find Part 1 here. In Part 2 of our free Node.js Webinar Series, Brian May teaches you the different tooling options available for writing code, debugging, and using Git for version control. Brian will briefly discuss the different tools available, and demonstrate his preferred setup for Node development on IBM i or any platform. Attend this webinar to learn:

  • SB Profound WP 5539More than ever, there is a demand for IT to deliver innovation. Your IBM i has been an essential part of your business operations for years. However, your organization may struggle to maintain the current system and implement new projects. The thousands of customers we've worked with and surveyed state that expectations regarding the digital footprint and vision of the company are not aligned with the current IT environment.

  • SB HelpSystems ROBOT Generic IBM announced the E1080 servers using the latest Power10 processor in September 2021. The most powerful processor from IBM to date, Power10 is designed to handle the demands of doing business in today’s high-tech atmosphere, including running cloud applications, supporting big data, and managing AI workloads. But what does Power10 mean for your data center? In this recorded webinar, IBMers Dan Sundt and Dylan Boday join IBM Power Champion Tom Huntington for a discussion on why Power10 technology is the right strategic investment if you run IBM i, AIX, or Linux. In this action-packed hour, Tom will share trends from the IBM i and AIX user communities while Dan and Dylan dive into the tech specs for key hardware, including:

  • Magic MarkTRY the one package that solves all your document design and printing challenges on all your platforms. Produce bar code labels, electronic forms, ad hoc reports, and RFID tags – without programming! MarkMagic is the only document design and print solution that combines report writing, WYSIWYG label and forms design, and conditional printing in one integrated product. Make sure your data survives when catastrophe hits. Request your trial now!  Request Now.

  • SB HelpSystems ROBOT GenericForms of ransomware has been around for over 30 years, and with more and more organizations suffering attacks each year, it continues to endure. What has made ransomware such a durable threat and what is the best way to combat it? In order to prevent ransomware, organizations must first understand how it works.

  • SB HelpSystems ROBOT GenericIT security is a top priority for businesses around the world, but most IBM i pros don’t know where to begin—and most cybersecurity experts don’t know IBM i. In this session, Robin Tatam explores the business impact of lax IBM i security, the top vulnerabilities putting IBM i at risk, and the steps you can take to protect your organization. If you’re looking to avoid unexpected downtime or corrupted data, you don’t want to miss this session.

  • SB HelpSystems ROBOT GenericCan you trust all of your users all of the time? A typical end user receives 16 malicious emails each month, but only 17 percent of these phishing campaigns are reported to IT. Once an attack is underway, most organizations won’t discover the breach until six months later. A staggering amount of damage can occur in that time. Despite these risks, 93 percent of organizations are leaving their IBM i systems vulnerable to cybercrime. In this on-demand webinar, IBM i security experts Robin Tatam and Sandi Moore will reveal:

  • FORTRA Disaster protection is vital to every business. Yet, it often consists of patched together procedures that are prone to error. From automatic backups to data encryption to media management, Robot automates the routine (yet often complex) tasks of iSeries backup and recovery, saving you time and money and making the process safer and more reliable. Automate your backups with the Robot Backup and Recovery Solution. Key features include:

  • FORTRAManaging messages on your IBM i can be more than a full-time job if you have to do it manually. Messages need a response and resources must be monitored—often over multiple systems and across platforms. How can you be sure you won’t miss important system events? Automate your message center with the Robot Message Management Solution. Key features include:

  • FORTRAThe thought of printing, distributing, and storing iSeries reports manually may reduce you to tears. Paper and labor costs associated with report generation can spiral out of control. Mountains of paper threaten to swamp your files. Robot automates report bursting, distribution, bundling, and archiving, and offers secure, selective online report viewing. Manage your reports with the Robot Report Management Solution. Key features include:

  • FORTRAFor over 30 years, Robot has been a leader in systems management for IBM i. With batch job creation and scheduling at its core, the Robot Job Scheduling Solution reduces the opportunity for human error and helps you maintain service levels, automating even the biggest, most complex runbooks. Manage your job schedule with the Robot Job Scheduling Solution. Key features include:

  • LANSA Business users want new applications now. Market and regulatory pressures require faster application updates and delivery into production. Your IBM i developers may be approaching retirement, and you see no sure way to fill their positions with experienced developers. In addition, you may be caught between maintaining your existing applications and the uncertainty of moving to something new.

  • LANSAWhen it comes to creating your business applications, there are hundreds of coding platforms and programming languages to choose from. These options range from very complex traditional programming languages to Low-Code platforms where sometimes no traditional coding experience is needed. Download our whitepaper, The Power of Writing Code in a Low-Code Solution, and:

  • LANSASupply Chain is becoming increasingly complex and unpredictable. From raw materials for manufacturing to food supply chains, the journey from source to production to delivery to consumers is marred with inefficiencies, manual processes, shortages, recalls, counterfeits, and scandals. In this webinar, we discuss how:

  • The MC Resource Centers bring you the widest selection of white papers, trial software, and on-demand webcasts for you to choose from. >> Review the list of White Papers, Trial Software or On-Demand Webcast at the MC Press Resource Center. >> Add the items to yru Cart and complet he checkout process and submit

  • Profound Logic Have you been wondering about Node.js? Our free Node.js Webinar Series takes you from total beginner to creating a fully-functional IBM i Node.js business application.

  • SB Profound WC 5536Join us for this hour-long webcast that will explore:

  • Fortra IT managers hoping to find new IBM i talent are discovering that the pool of experienced RPG programmers and operators or administrators with intimate knowledge of the operating system and the applications that run on it is small. This begs the question: How will you manage the platform that supports such a big part of your business? This guide offers strategies and software suggestions to help you plan IT staffing and resources and smooth the transition after your AS/400 talent retires. Read on to learn: