How to Get AS/400 Net.Data Up and Running

By Craig Pelkie

If you have any interest in AS/400 Web enablement techniques, you’ve probably heard about Net.Data for the AS/400. Net.Data is a described as a macro language, to distinguish it from a compiled language, such as RPG or COBOL. Net.Data macros consist of Net.Data language statements, and usually some HTML and SQL statements. After coding the Net.Data macro, you invoke it from your browser, at which point the macro is interpreted by the AS/400 Net.Data macro processor and the results rendered in your browser.

Figure 1 shows a sample query run against an AS/400 database file. Figure 2 shows the complete Net.Data code required to produce the query. The purpose of this article is to show you, step by step, what you need to configure on your AS/400 system so that you can run the sample query. Once you successfully run the query, you can use it as a base for additional Net.Data macros to produce results against your own database files.

Figure 1: The sample output from the Net.Data macro.

%{---------------------------------------------------------------%}

%{ Net.Data macro Hello.ndm                                      %}

%{---------------------------------------------------------------%}

 

%define{

 

    DATABASE = "*LOCAL"

    DTW_HTML_TABLE = "YES"

    SHOWSQL = "YES"

 

%}

 

%function(DTW_SQL) RUNSQL() {

 

    select * from qiws.qcustcdt

 

%}

 

%html(INPUT) {

 

    <html>

        <head>

            <title>Net.Data test macro</title>

         </head>

 

        <body>

            <center>

                <h1>Hello from Net.Data!</h1>

                @RUNSQL()

            </center>

        </body>

 

    </html>

%}

Figure 2: The sample Net.Data macro.

HTTP Server Configuration

Although learning the Net.Data language itself may take some time and experimentation, perhaps the most frustrating aspect of working with Net.Data is that you need to configure IBM HTTP Server for AS/400 successfully before you get started. Unfortunately, the “how-to” of configuring HTTP Server is often glossed over, the assumption being that configuration is no big deal. My own experience, and my experience of helping several AS/400 shops get started with Web enablement projects, shows that inability to configure HTTP Server is one of the main problems when getting started. So rather than assume that you already know exactly what you need to do to configure IBM HTTP Server for AS/400 for use with Net.Data, I will show you what you need to do to create a simple but functional HTTP Server configuration. You cannot use AS/400 Net.Data unless you have a working HTTP Sever configuration.

My directions are targeted at AS/400’s that are at V4R3 or V4R4. Although Net.Data runs on OS/400 releases back to V3R2, the HTTP Server configuration program underwent a massive change in V4R3. The instructions and figures show a V4R3 configuration.

Starting the Configuration

Before starting the configuration process, verify that your user profile has *IOSYSCFG (I/O System Configuration) authorization. If it does not, you will need access to an AS/400 user profile that has that level of authorization.

There are two techniques you can use to configure IBM HTTP Server for AS/400:

I assume that you have a working TCP/IP configuration on your AS/400, and that you have access to a browser that can connect to your AS/400. The browser can be run from a PC, Network Station, or any other platform. The browser must support JavaScript to use the administration and configuration program.

You must start the Administration instance of IBM HTTP Server for AS/400 before working with the administration and configuration program. You start that instance by entering the following AS/400 command at an AS/400 command line:

STRTCPSVR SERVER(*HTTP) HTTPSVR(*ADMIN)

You then start the administration and configuration program by entering a URL like this:

http://as400_ipaddress:2001

where as400_ipaddress is the IP address or TCP/IP host name of your AS/400 system, and 2001 is the port number associated with the Administration instance. If you are just getting started with TCP/IP, I suggest you enter the IP address rather than the AS/400 host name. That way, the browser will be able to connect, even if the host name cannot be resolved to the IP address (by a HOSTS table on a PC or a DNS server).

Figure 3 shows the initial page of the Administration program. Depending upon the AS/400 Licensed Program Products you have installed, you may see more items on the page (for example, Firewall for AS/400). Click the IBM HTTP Server for AS/400 link to go to the next page. On that page, click the Configuration and Administration link, which takes you to the page shown in Figure 4.

Figure 3: The AS/400 Tasks page is the opening page of the browser-based administration and configuration program.

Figure 4: Select the Configurations link to start a new HTTP Sever configuration.

Instances and Configurations

You configure IBM HTTP Server for AS/400 by selecting links in the left-side navigation frame, as shown in Figure 4. At this point, you need to understand the terminology used with HTTP Server:

In this article, I show how to create a Configuration that will support Net.Data and then create a Server Instance that uses that Configuration. After creating both the Configuration and the Instance, I start the Instance, and then create and run the Net.Data macro.

Creating the Configuration

To create a Configuration, click the Configuration link, as shown in Figure 4. The navigation frame expands to show options that are available for working with Configurations, as shown in Figure 5.

Although IBM HTTP Server ships with a default Configuration named CONFIG, you should create a new Configuration for your test. Click the Create Configuration link shown in Figure 5. The program displays the Create Configuration page, shown in Figure 6. Enter NDTEST as the name of the configuration, and select the option to create an empty configuration. Click Apply to create the empty configuration. The program responds with a message that is displayed near the top of the Web page, indicating that the Configuration was created.

Figure 5: Select the Create Configuration option in the navigation frame.

Figure 6: Enter the name of the new configuration.

Assign a Port

Because you might already have Web server Configurations and Instances in use on your AS/400 system, you should assign a unique TCP/IP port number to your new Configuration. By default, Web servers use TCP/IP port 80. For example, you sometimes see a URL specified like this:

http://some_URL:80

Because the default port is 80, it is usually omitted from the URL. You have already seen an example of an application that uses a different port: the browser-based administration and configuration program uses port 2001. When you use a port other than the default port, you need to enter the port number as part of the URL. By entering the port number, you are connected to a specific Web server Instance.

To assign a unique port number to your Configuration, go back to the navigation frame. First, you must verify that your Configuration name is now displayed in the drop-down list box of Configurations (see Figure 7). If the name NDTEST is not displayed, click the down-arrow on the list-box and select that name. You should always verify that the Configuration name you need is shown in the list-box before clicking any of the links in the navigation frame.

Figure 7: Select the Basic link in the navigation frame.

Click the Basic link to go to the Basic page, shown in Figure 8. Although there are many options on that page, you should only set the Default port option. For my test, I used port 8081. Although you can use almost any port number within the range 1024 to 65535, it is “traditional” to use ports in the 80xx range for HTTP server testing. For example, you might use port 8080, which is easy to remember when you enter the URL. I chose 8081 because I was already using 8080 for another Configuration. If you do not want to use a port in the 80xx range, you should use the AS/400 Work with Service Table Entries (WRKSRVTBLE) command to check for port numbers that are already in use on your AS/400 system, then select a port number that is not used. You should not select a port in the range 0 to 1023, since those port numbers are considered to be “reserved” for well-known TCP/IP functions.

After entering the port number, click the Apply button. The port number is now part of your Configuration.

Figure 8: Specify the port number to use in the configuration

Request Processing

Go back to the navigation frame and click the Request Processing link. The link expands to show options used for request processing. Click the Methods link, shown in Figure 9, to display the Methods page (Figure 10). (Note: although this page looks quite different in the V4R4 version, you will set the same options as shown in Figure 10).

Figure 9: Select the Methods link in the Request Processing section of the navigation frame.

For HTTP Server, “methods” are used to indicate the types of services that the Web server will provide. By default, several methods are already enabled, meaning that clients (usually browsers) can make requests of the HTTP Server that will be serviced by one of the selected methods. Net.Data uses the POST method to send data from forms to the Web server. By default, that method is not enabled, so you need to click it to enable it for your Configuration. Leave the other methods set as they are, then click the Apply button.

Figure 10: You need to check the POST method for Net.Data.

Request Routing

You now have to enter request routing directives, which are among the most difficult HTTP Server directives to enter correctly. If you get your Web server Instance up and running and cannot get anything served through it, chances are that the request routing directives are incorrect.

That being said, I only use two request routing directives for my sample Net.Data configuration. The purpose of those directives is to indicate to the Web server where resources are located on your AS/400 system. There are two locations that are used in the sample:

In the navigation frame, click the Request routing link to display the Request routing Web page (Figure 11). You should carefully study the input options before entering anything, since this page works differently from the previous pages. When you enter request routing directives, you enter one at a time, clicking the Apply button after each entry. When you click Apply, the entry is shown in the list of entries. Figure 11 shows the two request routing directives at the bottom of the list, after the examples. The order of request routing directives is very important, since HTTP Server processes an incoming request with the first request routing directive that matches the request criteria. For this sample, you only need to get the Map directive before the Exec directive, but when you create a more extensive list of request routing directives, you need to carefully verify that the directives are in the correct order.

Figure 11: Enter the Map and Exec directives on the Request routing page.

You need to enter the following two directives:

URL template: /netdata/* (enter in lower-case)

Replacement file path: /QSYS.LIB/NDTEST.LIB/DB2WWW.PGM/ndtest/* (enter case as shown)

URL template: /QSYS.LIB/NDTEST.LIB/*

The Map directive is used to “map” an incoming URL to specific resources in the AS/400 system. In this example, you enter a URL like this:

http://as400_ip:8081/netdata/Hello.ndm/input

The embedded netdata is expanded to the longer replacement fie path string, meaning that you don’t have to type an excessively lengthy URL. The replacement file path is used to identify both the name of the program to be executed (DB2WWW in library NDTEST, which you will soon create), and the path to the Hello.ndm Net.Data macro (the directory ndtest, which you will also create).

The Exec directive is used to indicate that incoming requests are allowed to start programs in the NDTEST library. You need to be very careful when you configure HTTP Server so that you do not allow programs to be started in libraries other than those that contain only programs that you want started from a browser. In this case, the program that will be started is the DB2WWW program supplied by IBM, which processes Net.Data macros.

Be sure that the Map and Exec directives are correct. You are now done with the NDTEST configuration.

Create a Server Instance

You now need to create a Server Instance, based on your Configuration. After creating the Instance, you will start the Instance and use it for testing a Net.Data macro.

Click the Server Instances link in the navigation frame. The link expands to show options for working with Instances (Figure 12). Select the Create server instance link to display the Create server instance Web page (Figure 13).

Enter the name of the Server instance as NDTEST, then select the NDTEST configuration from the drop-down list-box. Click the Create button. You now have a Web server Instance that you can start with the STRTCPSVR command, that will respond to incoming requests on the port that you specified. Enter the command as follows:

STRTCPSVR SERVER(*HTTP) HTTPSVR(NDTEST)

If you need to make changes to your server Configuration, you should end the server instance (with ENDTCPSVR), make the changes, the restart the Instance with STRTCPSVR. Although there is a Restart option for Web server Instances, there are some options that are not put into effect on a restart. Because ending and then starting the server Instance will always put changes into effect, you might find it advisable to use the end/start technique, rather than spend any time investigating the nuances of restart.

Figure 12: Click the Create server instance link in the Server Instances section of the navigation frame.

Figure 13: Enter the name of the server instance.

Net.Data Configuration

You can now configure and test a Net.Data macro. Compared to HTTP Server configuration, Net.Data configuration is simpler. The steps you will follow are:

Create a Library for DB2WWW

Although you might suppose by looking at the Net.Data source code in Figure 2 that the code is a stand-alone program, the source code is in fact input to another program. It just so happens that the input to the program is used to produce a Web page as output. I point this out because it will help you visualize what happens when you run a Net.Data macro.

The program that accepts and processes the Net.Data macro as input is named DB2WWW. This name is from IBM’s initial Web-enablement product, which was named DB2WWW. Although that name was indicative of its purpose (WWW enablement for the DB2 database series), the name was not very catchy, whereas Net.Data has a more “with-it” look and feel.

Regardless, IBM ships the DB2WWW program with the AS/400. On AS/400 systems at V4R2 and prior, the program is located in library QTCP. On V4R3 and later systems, the program is in QTCP, QSYSCGI and QHTTPSVR. Regardless of which version of OS/400 you are using, the preferred technique for using this program is to create a library, then use the Create Duplicate Object (CRTDUPOBJ) command to create a copy of the program in your library. The reason for this is because you will allow your Web server Instance to execute the program in your library, rather than in the product library. If you allowed your Instance to execute programs in the product library, you create a potentially larger security exposure, since there are many more programs in the product library. By copying the program to your library, you limit the number of programs that a hacker can access on your system through the Web.

For this example, create a library named NDTEST, then copy DB2WWW as follows:

For V4R3 or later, you need to be sure to copy the right version of the program, since PTFs only update the version in QHTTPSVR.

You should verify that user profile *PUBLIC or QTMHHTP1 are authorized to program DB2WWW. Use the Edit Object Authority (EDTOBJAUT) command to check the authorization to NDTEST/DB2WWW. You need to grant *USE authority to either or both of those user profiles (user profile QTMHHTP1 is used by HTTP Server for programs that it starts).

Create Directory NDTEST

You now need to create a directory in the IFS to contain your Net.Data macro. Although it is possible to create and run Net.Data macros from source files in the library file system, there are two reasons why you should not use source files:

Use the Create Directory (CRTDIR) command to create the directory:

CRTDIR DIR('/NDTEST')

Enter the Net.Data Macro

You can now enter the source code for the Net.Data macro, as shown in Figure 2. If you do not have any other PC editor, use Windows Notepad. (Note: because you will be entering a lot of HTML code in Net.Data macros, you may want to investigate any of the widely available HTML editors available. Generally, you want a simple source code editor, not something like FrontPage that adds a lot of its own source code.)

You now need to save the Net.Data macro to the NDTEST directory, as Hello.ndm. Although the file name extension is not significant to Net.Data, the convention is to use ndm (for “Net.Data macro”). There are several ways you can save the macro file, depending upon your resources:

Each of those methods assumes that you have some level of proficiency with connecting to the AS/400 IFS from your PC. If you get really stuck, you can use the Data Transfer program in Client Access (or other products) to transfer the source file from your PC to a source file, then use the Copy To Stream File (CPYTOSTMF) command on the AS/400 to copy from the source file to the IFS.

If you are not familiar with working with the IFS, I suggest that you spend whatever time it takes to become adept with working with it. You will find, as you develop Net.Data macros, that you need to quickly get into a macro, make changes, then test. The time you invest in learning how to work efficiently with the IFS from your PC will be repaid as soon as you start developing “real” macros (that is, macros that have bugs that need to be fixed).

You should check the authorization to the Net.Data macro after you save it to the directory. You can use either the AS/400 command Work with Object Links (WRKLNK) and drill-down to the Net.Data macro file, or use AS/400 Operations Navigator (File Systems, Integrated File System branch) to review and set authorization to the macro file. You need to authorize *PUBLIC or QTMHHTP1 to at least Read (*R) authority.

Test the Macro

You are now at a point where you can test the macro. Review this checklist to make sure everything is ready:

Enter the following URL into your browser (adjust the port number, if required):

http://as400_ip:8081/netdata/Hello.ndm/input

If everything is configured correctly, you should see a Web page similar to Figure 1 in your browser. If you get that page, congratulations. You are now in a position where you can start altering the sample macro to work with some of your data. For example, the first change you can make is to change the SQL SELECT statement so that it selects from one of your files (if the file has a lot of records, you may want to include a WHERE clause to limit the number of records that will be returned).

However, you may get an error message of some sort in your browser. At this point, you need to review each of the steps described above to try to determine the source of the error. You can also find more information about working with Net.Data on IBM’s Net.Data Web site at http://www.as400.ibm.com/netdata.

Craig Pelkie is President of Bits & Bytes Programming, Inc., based in Southern California. Craig has worked extensively with IBM Rochester over the past year and a half, has coauthored four Redbooks and helped develop course material for IBM HTTP Server for AS/400. He is the author and primary instructor for the IBM Learning Services course, “Using Net.Data with the AS/400 System” (course code S6178). Craig is available for consultation and AS/400 Web-enablement programming assignments, and may be contacted at craig@web400.com.