If you are getting tired of writing reports that simply print out on paper, use the techniques here to “wow” your customers, your boss, and your peers. The subprocedures provided in this article will allow you to build quick and simple dynamic HTML pages using data from your AS/400.
It seems that everywhere we turn these days, we see Web addresses. We see them on the news, on commercials, in magazines, and even on department store shopping bags. People are using the Web to provide information, sell products, and provide customer support. Over the past few years, Web pages have been changing for the better. Whereas they once contained static information that never changed unless the Webmaster of the site modified the pages and uploaded them to the server, we are now more often seeing pages that change dynamically. If you have ordered products over the Web, chances are you have run across a tracking number of some sort. This tracking number is used by the carrier to, simply put, “track” your item as it journeys toward you. Accessing this information is usually possible from the carrier’s site. All you need to do is go to the carrier’s Web site, enter the tracking number, and the up-to-date information is right there in front of you, changing as it happens.
You may have asked yourself, “How do they do that?” Obviously, someone isn’t changing HTML code as the shipping status changes and then uploading the new information. These companies are using live data that their carriers collect as a package leaves one point and arrives at another. Their pages are being built dynamically. In other words, a program is reading information from a database and using that data to build the Web page. These programs are called Common Gateway Interface (CGI) programs. CGI programs run on a Web server and interact dynamically with user input. They can be written in C, Perl, Java, Visual Basic, and, more important to us, RPG or COBOL.
In V3R2 CISC and V3R7 RISC, IBM gave the AS/400 the ability to create dynamic Web pages. This ability is available through APIs that are similar to those used in non- AS/400 systems. Because system APIs are used, this means that you can use your favorite AS/400 language, such as RPG or COBOL, to produce dynamic Web pages. The APIs available allow you to write HTML code to a browser or to read data that was inputted by the user. Most of us have seen examples of the latter. We go to a vendor’s Web page to
download the latest beta version of its software. Before we are allowed to download, we are required to enter our name, address, phone number, and any other information the vendor feels is worth gathering. Once we have entered this information, we are allowed to download the beta.
The essence of doing business on the Web relies on displaying and gathering information. In this article, I explain the basic APIs used in the process and give examples of how to use them. The first example is a very simple one that writes information to a Web page. The second allows users to input information, which, in turn, is used to display data pertinent to their input. If you are new to CGI programming, I suggest you read the article “Writing Your First RPG CGI Data Entry Program,” MC, January 1998, before working with these examples. Now, let’s get down to business.
Writing Data to a Browser
The first and most essential system API for CGI programming is QtmhWrStout. You use this API to write standard output to a browser. The QtmhWrStout API requires three parameters and is really the simplest to use of the APIs explained in this article. The first parameter is a data variable of varying length that contains the code you wish to write to a browser. The second parameter is used to tell the system how long the first parameter is. The third parameter is a standard error parameter that appears with most APIs.
You will notice, however, that, rather than directly use this and the other system APIs required for CGI programming, I have put the interface to them in a format that I feel is much friendlier. Instead of calling the API each time, I have created a service program that contains subprocedures that subsequently call the APIs. Figure 1 shows the protoypes for the F.USDVEH service program. The use of my service program makes the coding and maintenance of your CGI programs much easier. For the AS/400’s QtmhWrStout system API, F.USDVEH’s corresponding subprocedure is named #WrtStout. The source and compile instructions for these subprocedures and sample programs can be downloaded from Midrange Computing’s Web site at www.midrangecomputing.com/mc/99/04.
To show a simple example of how to use the F.USDVEH service program, specifically the #WrtStout subprocedure, I have created a small program called HTML01RG, the pseudocode for which is shown in Figure 2. HTML01RG simply displays the text “Click Here for Midrange Computing Magazine.” The example RPG CGI program also makes the text a hyperlink to Midrange Computing’s home page. You will notice in the pseudocode of Figure 2 that, instead of calling the #WrtStout procedure directly with the literal text as a parameter, I am first filling in a variable named WrtDta with the HTML text and then calling the #WrtStout subprocedure using this variable as the parameter. The main reason I use this method is so that, while debugging, I can see the value that I will be writing to standard output. Although using this method may seem trivial for this example, when you are writing more complicated HTML output, you will find this method easier to debug because you can view the variable before it is passed into the subprocedure.
To execute the HTML01RG program and display this first example, you first need to set up your HTTP configuration. (For more information on configuring your AS/400 as a Web server, see “HTTP on the AS/400,” MC, April 1998, or the HTTP Server for AS/400 Webmaster’s Guide V4R3.) Then, point your favorite browser to youras400/cgibin/HTML01RG, replacing youras400 with the IP address or name of your AS/400. This instructs the Web server on your AS/400 to execute the program HTML01RG. Because this program writes to standard output, you will see the text “Click Here for Midrange Computing Magazine!!!” as a hyperlink to Midrange Computing’s home page. Use your browser’s View Source option to see exactly what the HTML code looks like.
Reading Query String Data from a Browser
We have seen how to write data to a browser, but how do we read information from a browser? The first step is to understand the two ways that a CGI program can read information from a browser.
The first and most common way is to read the data in from the Query String environment variable. More plainly, this means that if any parameters are included in the URL after the name of the CGI program, we want to read these into our program for use. Examine the following example URL:
http://youras400/cgi-bin/CGIPGM?CITY=MINNEAPOLIS&STATE=MN
The first portion of the URL contains the address and directory to find the CGI program, in this case named simply CGIPGM. After the CGI program name, we see the question mark (?). This tells us that a set of Query String environment variables follow. In this example, two variables are included: city and state. The text STATE=MN tells the program that the value of the variable named CITY is to contain the value MINNEAPOLIS. The ampersand (&) operator is used for subsequent parameters, and, for this example, it is STATE with a value of MN for Minnesota. If you’ve ever paid close attention to the URL of a site that has been produced as the result of a search operation, you may see something similar and recognize this format.
The CGI program must use the QtmhGetEnv API to read this information. The QtmhGetEnv API can be used to retrieve many different environment variables, but, for this example, we are concerned only with the Query String variable. When using this API by itself, six variables are required. These variables and their explanations can be found in the HTTP Server for AS/400 Webmaster’s Guide.
Again, to make access to and use of the API easier, I have placed it in a subprocedure of the F.USDVEH service program. I named this subprocedure #GetEnvQS for Get Environment Variable Query String. Because this subprocedure is used only to retrieve the Query String Environment variable, it reduces the number of parameters needed from six to only the first two variables, as you can see in the prototype in Figure 1. Since the first parameter is an output variable and the second can be figured using the %size builtin function, both of these parameters are used as output parameters by the subprocedure and do not require values before the call.
Once the data is read in using the #GetEnvQS subprocedure, you must parse the data into a readable format by your CGI program. You can do this by hand or by using the QrmhCvtDB API. Again, this API has been made into a subprocedure named #CvtDB (the prototype of which is at the bottom of Figure 1). The #CvtDB subprocedure takes the Query String data as parameter one, the string length as parameter two, and parses the string into the fields of a data structure, the address of which is provided in parameter three. The data structure for this example contains two fields: CITY and STATE. The #CvtDB subprocedure calls QrmhCvtDB, passing the complete string that follows the question mark in the URL. When the QrmhCvtDB API sees a variable named CITY in the query string and a variable also named CITY in the data structure provided, it knows exactly where to put the value of the CITY variable. And when QrmhCvtDB sees the STATE string variable...well, you get the point. (See the HTTP Server for AS/400 Webmaster’s Guide for a further explanation of this API.)
Reading Standard Input from a Browser
The second way to read data from a browser is to read from standard input. This type of data exists in the form of actual fields that the user fills in on the browser and then clicks on a submit-type button. An example of this would be when a site asks you to fill in your email address and press the submit button. When you do, a CGI program that is linked to the submit button is executed, which, in turn, reads the information you have just entered.
The example provided for this article is a simple used-vehicle locator that allows us to search a database for used cars and motorcycles. This sample contains an HTML page (VSEARCH.HTM shown in Figure 3), a service program containing the APIs needed to read from and write to a browser (F.USDVEH), and the main processing RPG program
(DYNH01RG, the pseudo-code of which is shown in Figure 4). The database file used to read information is named USDVEHPF.
After you load the HTML document VSEARCH.HTM on your browser, you will see that there are two choices, a Car Search and a Motorcycle Search as shown in Figure 5. Each link calls the same program but with different parameters. The Car Search hyperlink uses the “type=AUTO” parameter, and the Motorcycle Search hyperlink uses the “type=MOTO” parameter. This Query String data is passed into our CGI program, DYNH01RG, and used to load either car or motorcycle data.
Let’s assume we choose to view a list of used motorcycles. We click on the motorcycle link, and the CGI program DYNH01RG is called. The output for the program can be seen in Figure 6. The first thing the program does in the initialization subroutine (*INZSR in Figure 4, Label B) is to read in the environment variables using the $GetEnv subroutine of the F.USDVEH service program. As you recall, these are the variables included after the question mark sign (?) of the URL. In this case, the Query String environment variable passed into our CGI program would be “type=MOTO”. If we look at the variable RcvRec in debug after the $GetEnv subroutine has completed, we see the “type=MOTO” string in the RcvRec variable. The next thing that is done is that the $CvtDB subroutine is executed to place the data into a data structure. In this case, the value MOTO is placed in the field name TYPE. When control is returned to the DYNH01RG program, I place this field in a variable named InType so that I do not lose this value when any other processing is done. The next step *INZSR performs is to read in the standard input data. During first-time processing, there is no standard input data. Subsequent calls to DYNH01RG will have standard input data to process, which I will cover later.
If you examine the main portion of DYNH01RG’s pseudocode in Label A of Figure 4, you will see that three general steps are performed by subroutines. First, we write the header information; second, we write the main data; and, finally, we write the footer information. The $Header and $Footer subroutines (Labels C and D) are similar to the subroutines from the first example and are fairly simple, so we will focus on the $Main subroutine (Label E). The $Main subroutine is again broken up into the following three steps:
1. Subroutine $Select (Label F). This subroutine writes the HTML code that allows users to select a specific make of vehicle to further narrow their search. It fills a SELECT field with the makes available from the database for the type of vehicle selected along with a submit-type button in a form. The program executed when this button is pressed is DYNH01RG, the same as before, only this time the data from this field read in as standard input and placed in the RcvDS data structure.
2. Subroutine $MainHead (Label G). This subroutine simply prints the headings for the data. Notice the use of the TABLE HTML keyword to align the data in an eye- pleasing format.
3. Subroutine $MainDet (Label H). This subroutine reads through the USDVEHPF file and builds the listing for the vehicle data selected. There are different cases for the selection of all makes or the selection of a specific make.
The first time the DYNH01RG program was called, you will recall that no standard input was read. If we were to choose a make from the list (for example, “YAMAHA”) and click the Use Selected Values button, DYNH01RG would be called again, only this time the value “MAKE=YAMAHA” would be passed in as standard input, which would then be converted (with *INZSR’s call to $ReadStdIn) to be used as selection criteria for display.
Learn to Walk Before You Run
The techniques provided in this article can help you to use the AS/400 as a productive dynamic Web server. But if you are unfamiliar with the basic HTML syntax, you may want to start there. I learned HTML the hard way. When I saw a page I liked, I would use my browser’s View Source option and find the particular area of code that I was
looking for. In some cases, with very complex Web pages, this was like finding a needle in a haystack.
I have some suggestions on how to get started if you are unfamiliar with HTML. My first suggestion is to find an HTML tutorial online. There are plenty of them out there on the Web that take you step by step through the Web page building process. My second suggestion is to use a WYSIWYG HTML tool. Such a tool allows you to “draw” an HTML page. Microsoft FrontPage and Netscape both provide tools to do this. After you have built a sample of what you want to see, look at the source. After you are familiar with HTML, you can use my method of scanning source from the Web to see how some of the tricks are done. Finally, I highly suggest that you familiarize yourself with both HTTP Server for AS/400 Webmaster’s Guide and the Web Programming Guide, which can be found online. Good luck, and happy CGIing!
References
“HTTP on the AS/400,” MC, April 1998 HTTP Server for AS/400 Webmaster’s Guide V4R3 (GC41-5434-03, CD-ROM QB3AEO03)
Web Programming Guide V4R3 (GC41-5435-02, CD-ROM QB3AEQ02) “Writing Your First RPG CGI Data Entry Program,” MC, January 1998
D #WrStout PR
D PR_WrStout
1024 VALUE
D #GetEnvQS
PR
D PR_EnvRec
256
D PR_EnvLen
9B 0
D #GetEnvRM
PR
D PR_EnvRec
256
D PR_EnvLen
9B 0
D #GetEnvCL
PR
D PR_EnvRec
256
D PR_EnvLen
9B 0
D #RdStin
PR
D PR_RcvRec
256
D PR_RcvLen
9B 0
D #CvtDB
PR
D PR_RcvRec
256
D PR_RcvLen
9B 0
D PR_RcvDS@
*
Figure 1: The complex interfaces of OS/400’s system APIs are easier to use if you simplify them with a service program.
HTTPHeader = 'Content-type: text/html'
NewLine = X'15'
WrtDta = 1024 characters
exec sub $Header
exec sub $Main
exec sub $Footer
begin subroutine $Header
WrtDta = %trim(HTTPHeader) + NewLine + NewLine
call proc #WrStout(WrtDta)
WrtDta = '' + NewLine
call proc #WrStout(WrtDta)
end subroutine
begin subroutine $Main
WrtDta = 'http://www.midrangecomputing.com">' +
'Click Here for Midrange Computing Magazine!!!' +
NewLine
call proc #WrStout(WrtDta)
end subroutine
begin subroutine $Footer
WrtDta = '' + NewLine
call proc #WrStout(WrtDta)
end subroutine
Figure 2: This basic CGI program writes HTML tags that contain application information to standard output.
Brad's Used Vehicle Search
Select a Listing
http://DomainName/cgi-bin/DYNH01RG?type=AUTO">
Car Search
http://DomainName/cgi-bin/DYNH01RG?type=MOTO">
Motorcycle Search
Figure 3: All CGI applications have an HTML file with an HREF tag that specifies the location of a CGI program.
EnvDS@ = pointer to HTML environment variables
DS@ = generic pointer
RcvDS@ = pointer to HTML form variable data
EnvDS = data structure that describes environment data
RcvDS = data structure that descrives HTML form data
USDVEHPF = Used Car database file
exec sub $Header
exec sub $Main
exec sub $Footer
begin subroutine *INZSR
exec sub $GetEnv
exec sub $CvtDB
EnvDS@ = DS@
InType = QTYPE
exec sub $ReadStdIn
exec sub $CvtDB
RcvDS@ = DS@
end subroutine
begin subroutine $Header
WrtDta = %trim(HTTPHeader) + NewLine + '' + NewLine
call proc #WrStout(WrtDta)
if (InType = 'AUTO')
TypeText = 'Car'
else if (InType = 'MOTO')
TypeText = 'Motorcycle'
WrtDta = '
NewLine '
' + %trim(TypeText) + 'Used Vehicle List' +
'
'
' + NewLine + '' + NewLine +
'
'Home
call proc #WrStout(WrtDta)
end subroutine
begin subroutine $Footer
WrtDta = '' + NewLine
call proc #WrStout(WrtDta)
end subroutine begin subroutine $Main
exec sub $Select
exec sub $MainHead
exec sub $MainDet
end subroutine
begin subroutine $Select
WrtDta = '
' + NewLine + '' + NewLine
call proc #WrStout(WrtDta)
open file USDVEHPF
WrtDta = ''' + NewLine +'
| Make: |
NewLine + '
WrtDta = '
'SUBMIT VALUE="Use Selected Values">' +'' + NewLine +
'
' + NewLine
call proc #WrStout(WrtDta)
end subroutine
begin subroutine $MainHead
WrtDta = '
' + NewLine + '' + NewLine
call proc #WrStout(WrtDta)
end subroutine
| Make | Year'+ ' |
Description | Milage | ' + 'Price |
E
F
A
B
C
G
D
begin subroutine $MainDet
if (SMAKE = ' ')
SMAKE = 'ALL'
if (SMAKE = 'ALL')
position file USDVEHPF by key(InType)
else
position file USDVEHPF by key(TypMakKey)
read file USDVEHPF by key(InType)
do until EOF
if (SMAKE <> 'ALL') and (MAKE <> SMAKE)
exit loop
WrtDta = '' + MAKE + '' + YEAR + ''+
DESC + '' + MILAGE + '' + PRICE + ''
call proc #WrStout(WrtDta)
read file USDVEHPF by key(InType)
close file USDVEHPF
WrtDta = '' + NewLine
call proc #WrStout(WrtDta)
end subroutine
begin subroutine $GetEnv
call proc #GetEnvQS(RcvRec:RcvLen)
end subroutine
begin subroutine $ReadStdIn
call proc #GetEnvCL(RcvRec:RcvLen)
RcvLen = #CtoN(RcvRec)
if (RcvLen > %size(RcvRec))
RcvLen = %size(RcvRec)
call proc #RdStin(RcvRec:RcvLen)
end subroutine
begin subroutine $CvtDB
call proc #CvtDB(RcvRec:RcvLen:DS@)
end subroutine
Figure 4: Interactive applications can now be extended to the Internet by using CGI and your language of choice.
Figure 6: Browser output of HTML that a CGI RPG program generates can be compared to 5250 subfiles.
 |
More 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.
TRY 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.
Forms 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.
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:
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.
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:
LATEST COMMENTS
MC Press Online