In today’s e-business environment, most OS/400 shops are trying to determine where to begin with OS/400 Web site development. Generally, these shops are trying to conquer two challenges. The first challenge involves getting an HTTP Server for AS/400 up and running, so that you can serve Web pages to your visitors; the second challenge is how to make your Web server instances do something useful with OS/400 data.
If this scenario describes your situation, fear no more. In this article, I will explore a tremendous aid—provided free by IBM—to help you get the HTTP server running. Additionally, I will also help you build a quick database access script that will provide a good reason to keep the server up and running all the time. By the end of this article, you will know how to move quickly from zero to OS/400 Web applications using IBM’s HTTP Wizard and a simple Net.Data macro.
The Internet Setup Wizards to the Rescue
In response to the first challenge, the folks at the IBM lab in Rochester, Minnesota put together a cool set of wizards to help you quickly get an OS/400 system ready for the Web. There are two wizards: one to help with TCP/IP configuration and another for the HTTP server. Although they are primarily written in Java, both wizards run under Windows and are supported for OS/400 V4R4 and V4R5. The wizards also assist you with getting the WebSphere application server going, although it may be a good idea to gain some experience by getting something a little less complex up and running before you tackle WebSphere.
To that end, here’s my step-by-step procedure for using the HTTP Wizard to set up a working OS/400-based Web site with Net.Data macro capability.
1. Download the self-extracting file that contains the wizards. The Internet setup wizards are found at the Transmission Control Protocol/Internet Protocol (TCP/IP) for AS/400: Internet Setup Wizard Web site at www.iseries.ibm.com/ tcpip/iwizard. The file is large at 15 MB, so plan on an extended download if you only have a low-performance Internet connection available. I downloaded them over my modem just to see how long it would take, and the download took about 90 minutes. After the download is complete, continue with the installation. [Editor’s Note: These wizards are included with the Client Access Express for Windows (Express client) V4R5M0 product, as long as you have service pack 2 or above installed, and they will also be shipped with the new Express client V5R1M0 (currently in beta) when it become available later this year. Look for it in the AS/400
Operations Navigator tree. So, if you are running either of these products, you may already have the wizards and you can skip the download process and go directly to step 4.]
2. Install the two wizards by executing the downloaded file (when I was testing this article, the file name was AS400InternetSetupWizard). Upon installation, two icons are created in an AS/400 Internet setup folder: the HTTP Wizard and the Internet Setup Wizard. For the purposes of this article, I will assume that you already have TCP/IP configured on your iSeries or AS/400 system and that you can use it to access your OS/400 system from your Windows desktop system, so I will not explain the Internet Setup Wizard. Remember, a Web application can be just as useful inside your organization as outside, so a connection to the larger Internet is not an absolute requirement.
3. Open the readme file that was extracted during the installation step before you do anything else. Look at the PTF requirements for your version of OS/400. The Internet setup wizard won’t work at all unless at least some of the indicated PTFs are installed. Many of the noted program service requirements deal with WebSphere, and since you won’t be dealing with it in this example, the update task should be fairly simple.
4. Install the IBM HTTP Server for AS/400 product (5769-DG1). The server is installed by default with OS/400, but it may be worth checking to see if the option has been removed for one reason or another. You can check for its presence by bringing up option 10, Display Installed Licensed Programs, on the Work with Licensed Programs menu (GO LICPGM).
5. Order and install the HTTP server PTFs (at a minimum) that are indicated in step 3 of that product’s readme file. These PTFs are small enough to be downloaded electronically, either over your Electronic Customer Support (ECS) connection or through the iPTF Internet PTF delivery system (available in the Fixes and Updates section on the iSeries and AS/400 Technical Support Web site, http://as400service. rochester.ibm.com). For OS/400 V4R4, a Web server group PTF (SF99026) is called for and it is too large for electronic
transmission. However, I was able to successfully use the HTTP Wizard before installing the group PTF, so you may want to try it while you wait for the delivery of your PTF CD from IBM.
6. Launch the HTTP Wizard in the AS/400 Internet setup folder. Sign on to the system you wish to configure. Client access is not required for this step, only TCP/IP access to the system. The System: prompt can be answered either with the IP address, a domain name for the system, or a name assigned to the system in your local Hosts file. The user ID supplied must have *ALLOBJ and *IOSYSCFG special authority.
7. Select the OK button (this starts the wizard). It can take a bit of time for the logon to occur, and IBM does warn in the readme file that the Windows cursor may not always change to indicate the wizard is working, so please be patient. A progress dialog will keep you advised during this step.
8. Select Next when you see the dialog that introduces the wizard and the configuration option that is available on the server.
9. Create a one-word name for your Web server at the server description dialog. The Web server name has to be ten characters or less, and it shouldn’t contain blanks or special characters. In addition, some of the Midrange Computing editors report that the Web server name should ideally be all lowercase letters because they had trouble testing a configuration name with both uppercase and lowercase characters. The name you supply will be used as your server configuration name, and it will be used as the name of the jobs associated with
the server in the QHTTPSVR subsystem. The default name is webserver, but you have the opportunity to be creative. Select Next after deciding on a name.
10. Choose a TCP port. The default port for all HTTP servers is 80, but any available port number will do. Choose 80 if this is your first Web server configuration on the system, otherwise use a different value. The OS/400 Work with TCP/IP Network Status (NETSTAT) command with the *CNN option will display the system’s port numbers already in use; you can sort the NETSTAT screen by local port numbers to see if a given port is taken. (Remember to choose a value not already being used.) Port numbers above 3000 usually won’t interfere with other applications and are outside the range of well- known ports defined by the Internet Engineering Task Force (IETF). Choose Next after deciding on a port number.
11. Select Yes, require passwords for some Web pages and select Next again.
12. Define the location on the server for protected and unprotected static Web pages on the next two dialogs (Directory to Serve Files From and Select Directory to Password Protect). The suggested location for unprotected documents will be /www/
13. Click No (for our example) if you are presented with two screens asking for information about configuring your Web server configuration to use servlets and JavaServer Pages (JSP).
14. Select Yes, require passwords for all Net.Data macros.
15. Select the default AS/400 IFS directory for storing Net.Data macros. (I suggest using the default, which should be /www/
16. Choose the mechanism that will authenticate the users. Since protection was called for on the earlier options, you must decide what protection mechanism will be used to authenticate the users. The Web server supports using either an OS/400-based validation list or your OS/400 user accounts (user profiles). Using the OS/400 accounts is convenient, but care must be taken since passwords are sent over the network in the clear, and your OS/400 security could possibly be compromised. I recommend that OS/400 accounts only be used for Intranet applications, not applications delivered over the Internet. For this example though, choose the OS/400 account option.
17. Input your preferences for access log recording, sizing, and storing in the next few dialogs. Logs, like protection, are desirable for tracking your Web site activity, and the suggested defaults for size and location will be fine. Under the Advanced button, there are options that specify an expiration limit for Web site log files and a log file deletion option for deleting your oldest log files when the total log file size grows above a certain limit.
18. Review your wizard selections in the Web server summary dialog. You can use the back button to return to any of the previous dialogs if a change is required. Additionally, you can save the summary to an HTML-formatted file on your local hard drive, which is a good idea for future reference. (Figure 1 displays a summary listing from a configuration done on my system.)
19. Select Finish on the summary dialog to configure your OS/400 system and get it up and running.
Figure 2 shows you the Welcome to Your New Web site message you will receive once you finish using the HTTP Wizard. The newly created Web server instance will start on your OS/400 server, a browser session will be started on your Windows desktop, and, as shown in Figure 2, the pregenerated Welcome page for your new OS/400-based Web server will be displayed in your browser window. Congratulations, you’ve just completely configured a Web server with scripting capability! Be sure to bookmark the URL that was used to display this instance (complete with port number, if you specified an IP port other than 80) so that you can return to this page. IBM does note that sometimes the browser session will open before the server is completely started. If you get an error message from your Web browser during this step, wait a few seconds and try connecting again.
As noted on the Welcome page, you can now change the configuration of the Web server by using the OS/400 administrative server instance on port 2001. Note that the administrative server (*ADMIN) must be started in OS/400 before you can use it to graphically configure your new Web site. To start the *Admin server, use the OS/400 Start TCP/IP Server (STRTCPSVR) command as follows:
STRTCPSVR SERVER(*HTTP) HTTPSVR(*ADMIN)
To end the administrative server instance, use the End TCP/IP Server (ENDTCPSVR) command with the same parameters:
ENDTCPSVR SERVER(*HTTP) HTTPSVR(*ADMIN)
This server can also be started and stopped by using the AS/400 Operations Navigator program.
You can also configure your new server by using the OS/400 green-screen Work with HTTP Configuration (WRKHTTPCFG) command with the new Web server configuration name in the Configuration name parameter:
WRKHTTPCFG CFG(
As I noted earlier, port 80 is the default for Web serving, so the Web browser does not require you to specify a port number while it is in use. When using other port numbers, like those used by the administrative server, the port number, prefaced with a colon (:), must be appended to the end of the server address or domain name. The HTTP Server for AS/400 Webmaster’s Guide V4R4, available at the IBM V4R4 Publications Web site at http://publib.boulder.ibm.com/html/as400/online/v4r4eng.htm, contains the documentation for all of the server options.
At this point, you can create one or more static Web pages using the editor of your choice (e.g., Microsoft FrontPage, Netscape Composer) and place the pages either in the protected or public AS/400 IFS directory noted on the summary listing. If you create a file named index.html and place it in the public directory, that file will become the default Welcome page for your new Web server instance. The Welcome page also contains a link to a demonstration of a protected page. Selecting the link causes the browser to prompt for a user name and password before the page is displayed. Since you chose to use the OS/400 user directory during the configuration of the server, any enabled OS/400 user profile with appropriate authority can be used. Remember that the password flows in the clear between the Web browser and the server, so care should be taken when connecting to a public network.
Now for Something Entirely Useful
The Welcome page that the HTTP Wizard generated includes a link to a simple Net.Data macro. The macro doesn’t do anything except display a static page, certainly not Net.Data’s greatest strength. Net.Data’s power lies in its ability to build dynamic Web pages from DB2 for OS/400 (DB2/400) database tables with only a minimum of development effort. However, since demonstration is always better than discussion, I will show you an easy macro you can set up after automatically creating your Web site to get started with Net.Data.
Every iSeries and AS/400 system maintains a set of database tables in the QSYS2 library that contain information about the database. When developing Web applications, I often find myself using the OS/400 Display File Field Description (DSPFFD) command, or I find myself querying the QSYS2/ SYSCOLUMNS table to determine the schema of a particular DB2/400 table. To make this task a bit easier, I’ve constructed a simple Net.Data macro that asks for a library/table name and lists the columns contained in the table. This macro uses some of Net.Data’s built-in features to simplify the programming task. Figure 3 contains the downloadable Net.Data script that mimics DSPFFD. It contains two pages: one to input a library and file name and the other to output a page showing the table columns in the desired table.
Download the script source file from the Midrange Network Expert downloadable code Web site at www.midrangecomputing. com/mne/code.cfm, copy it into the Net.Data macro directory noted in the summary listing, call it up by using the URL http://
Remember that you chose to password-protect Net.Data scripts when you created this server instance in the HTTP Wizard. This selection causes the Web browser to prompt for a user ID and password the first time any script in the server instance is called. The Web browser does cache the signon, so you are prompted only once after you start your browser.
A full discussion of the Net.Data language is beyond the scope of this article, but I will point out a few highlights of the script:
• %DEFINE statement—This statement at the beginning of the file simply commands the default report mechanism to output an HTML table instead of a text table. (The HTML table looks much better.)
• SQL statement—Contained in the Net.Data function, the SQL statement is straightforward, and the values supplied in the request are inserted into appropriate spots in the WHERE clause. SYSCOLUMNS stores library and table name values in uppercase, so the SQL UCASE function is used to force the names to uppercase before the search. Note: The Net.Data default is to use the dotted SQL naming conventions for the library and file name. The function does not contain a %REPORT block, a detail that makes the function produce a default HTML report.
• %MESSAGE block—This block is optional and it could have been left out. However, the syntax is simple and error handling is a little cleaner with it there. Without the block, a somewhat cryptic Net.Data error is displayed instead of the simple explanatory text in the script.
• %HTML block—These blocks in the script contain the pages you see. The first is a simple form that asks for a library name and a file name. Net.Data assumes any text in a script that doesn’t begin the line with either the percent (%) symbol or the at (@) symbol is HTML and simply outputs the script line to the Web browser. (Obviously, there is a lot of room for creative improvement in my example HTML.)
• Second %HTML block—This block simply repeats the values supplied in the form and executes the SQL function. Net.Data’s default report capability takes care of the balance of the page.
The last part of your URL used to access the page—after the last forward slash (/)—is the same as the name following the %HTML statement in the script. This is the mechanism Net.Data uses to select the appropriate page from the script source file (this is similar to having a number of function names in an ILE service program).The action statement in the HTML form tag, which is in the first HTML block, shows how the query result page is accessed.
In my getfields function, I’ve chosen to output only a few of the available fields in the SYSCOLUMNS table. Obviously, there are more available, and the ones I have defined may not be the most useful for you. To make the tool more useful for you, a simple change in the SELECT clause of the SQL statement will adjust which fields are presented and in what order they are presented.
• SYSCOLUMNS table—This table is only one of a series of tables in QSYS2 that describe the OS/400 DB2/400 database. Some of the other tables describe how they are indexed, how they are related, and how they are organized in the system libraries. Spending a little time expanding this simple script could make for an extensive database administration and examination tool.
• The Net.Data getfields SQL function—This function can contain any valid SQL statement including complex subqueries, joins, and updates. Given that fact, any data in your collection is a good candidate for Web access.
I’ve yet to encounter a problem with the HTTP configuration wizard, though I’ve run it a number of times against a number of different systems. It is an extremely simple and powerful way to create an OS/400 Web server instance with the most desirable and necessary options enabled. But, in this era of e-business, static Web pages are of limited use both inside and outside our organizations. Beyond getting the server going, the Net.Data scripting tool provides you with a quick and simple way to publish and update the valuable data you’ve collected in your DB2/400 database.
References and Related Materials
AS/400 Net.Data home page Web site: www.iseries.ibm.com/ netdata
Net.Data Administration and Programming Guide for OS/400 Web site: www-
4.ibm.com/software/data/net.data/docs/ noframes/400/dtwa2m02.htm
Net.Data Reference Web site: www.iseries.ibm.com/products/ netdata/docs/manuals/dtwr1m02.htm
“The HTTP Server for AS/400 Webmaster’s Guide V4R4” (This reference is available at the IBM V4R4 Publications Web site: http://publib.boulder.ibm.com/html/as400/ online/v4r4eng.htm
Transmission Control Protocol/Internet Protocol (TCP/IP) for AS/400: Internet Setup Wizard Web site: www.iseries.ibm. com/tcpip/iwizard.
URL: http://10.1.12.201/ (Note: You can also use any host name you have mapped to
this IP address in a DNS.)
URL for private files http://10.1.12.201/private/
Web server root /www/webserver/docs/public/
Protected directory /www/webserver/docs/private/
Net.Data macro directory /www/webserver/macros/
Server instance name webserver
Configuration name webserver
Password protection Basic authentication
Net.Data macros protected Yes
Welcome page index.html
IP port 80
Access Log Yes
Access Log Directory /www/webserver/logs/
Access Log Format Extended
Access Log Daily Size 2 MB
Remove Old Logs Never
Figure 1: You will see a detailed summary listing of your server instance configuration after completing the OS/400 system configuration with the Internet wizard.
Figure 2: After using the HTTP Wizard, the new Web server instance is started on your server, a browser session is started on your desktop, and the pregenerated welcome page displays.
%{ Instant scripting - Display all the fields in a UDB table.
Randy Dufault
%}
%define { DATABASE = "*LOCAL"
DTW_HTML_TABLE = "YES"
%}
%{ This function uses the DTW_SQL language environment to access the database.
The output from the query will be displayed using Net.Data's default report format. %}
%FUNCTION (DTW_SQL) getfields() {
SELECT sys_cname, coltype, length, scale, labeltext
FROM qsys2.syscolumns
WHERE sys_tname = UCASE('$(table)') and sys_dname = UCASE('$(library)')
%MESSAGE {
100 : "No columns found" : continue
default : "SQL error $(RETURN_CODE) occurred" : continue
%}
%}
%{HTML sections are the pages of the site - kind of nice that they can all be in one file %}
%{ The entry form. The performance of the query is much better if the library name is supplied. %}
%HTML(getfields) {Display table fields