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

Size: px

Start display at page:

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

Jemimah Ramsey
5 years ago
Views:

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.

1 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"

2 %} %function(dtw_sql) RUNSQL() { %} select * from qiws.qcustcdt %html(input) { <html> <head> <title>net.data test macro</title> </head> <body> <center> <h1>hello from </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: The Work with HTTP Configuration (WRKHTTPCFG) command. This uses a primitive line-at-a-time editor which lets you directly enter HTTP Server configuration directives. This is a good choice if you know exactly what

3 directives you need and the syntax, but a poor choice if this is your first attempt at HTTP Server configuration. The browser-based administration and configuration program. This technique is described in this article. Although the browser-based program generates a configuration file for you, with correct directives and syntax, its drawbacks are that is slow and it may take a while to become familiar with the location of its configuration options. 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: 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.

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.

5 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: A Server Instance is started and controlled by the AS/400 commands Start TCP/IP Server (STRTCPSVR) and End TCP/IP Server (ENDTCPSVR). An Instance is based on a Configuration. You can have any number of Server Instances active simultaneously, each with different Web serving characteristics and capabilities. A Configuration is the set of HTTP Server directives that are used to assign certain characteristics to your Web server. Although there is normally a oneto-one correspondence between a Configuration and a Server Instance, it is possible to use the same Configuration in multiple Server Instances (although you would have to override some of the Server Instance parameters, such as the port used, when you start the Instance). 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.

6 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.

7 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: 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 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 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.

8 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.

9 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.

10 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: Library NDTEST. You will create that library in a later step and create a copy of the Net.Data system program in it. Directory NDTEST. You will create that directory in a later step and store the Net.Data macro in it.

11 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: Action: Map URL template: /netdata/* (enter in lower-case) Replacement file path: /QSYS.LIB/NDTEST.LIB/DB2WWW.PGM/ndtest/* (enter case as shown) Action: Exec 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:

12 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.

13 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.

14 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 library to contain the DB2WWW Net.Data program. Create a directory in the Integrated File System (IFS) for your Net.Data macro. Enter and save the Net.Data macro to the directory. Attempt to launch the macro in your browser. 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.

15 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: If you are on V4R2 or previous, use the CRTDUPOBJ command to copy QTCP/DB2WWW to your library. If you are on V4R3 or later, use the CRTDUPOBJ command to copy QHTTPSVR/DB2WWW to your library. 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: Serving macros from source files takes about twice as much time as serving from an IFS directory. That is because the text in the source file must be translated from EBCDIC to ASCII as it is served. You have access to better tools (editors) to create and maintain files in the IFS. SEU is a very poor source code editor for a free-format language like Net.Data. Even Windows NotePad is a better editor than SEU for Net.Data. 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

16 use ndm (for Net.Data macro ). There are several ways you can save the macro file, depending upon your resources: You can FTP the file from your PC to the directory. If you have IBM Client Access for Windows 95/NT (version V3R2M0 or earlier), you can locate the directory in the Windows Network Neighborhood and save it that way. If you have IBM Client Access Express, you need to start AS/400 NetServer and create a share to the NDTEST directory. You can then save to the share. 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: Your Web server Instance is configured and started (use the Work with Subsystem Jobs (WRKSBSJOB) for subsystem QHTTPSVR to verify that server instance NDTEST is started). You have program DB2WWW in library NDTEST. User profile *PUBLIC or QTMHHTP1 is authorized to program NDTEST/DB2WWW. You have macro Hello.ndm in directory NDTEST. Use profile *PUBLIC or QTMHHTP1 have at least Read authorization to file Hello.ndm. Enter the following URL into your browser (adjust the port number, if required): 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).

17 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 Copyright 2003, Craig Pelkie. All Rights Reserved No part of this presentation or the accompanying computer source code may be reproduced or distributed in any form or by any means, or stored in a database or data retrieval system, without the prior written permission of Craig Pelkie, who is the author of the presentation and the computer source code. All computer source code distributed with this presentation, either on diskettes, CD- ROM, or available for downloading from sources such as the Internet is Copyright 2003 Craig Pelkie, All Rights Reserved. The source code is for use in computer programs that you develop for internal use within your company, or for use within programs that you develop for the use of your clients, when such programs are compiled and distributed in an executable computer program such that no part of the source code is readily visible without the aid of a computer program disassembler. No part of the computer source code distributed with this presentation shall be reproduced in source code format, either printed or in electronic format, by you or by others who you allow to have access to the source code. You shall not cause the source code to be stored on any information retrieval system, such as computer Bulletin Board Systems or the Internet. You shall not develop any written articles, books, seminar materials, or other presentations that include the source code provided on the diskettes accompanying this manual or within the manual itself. For any questions regarding your rights and responsibilities using the computer source code distributed with this presentation, contact Craig Pelkie, Rochester Initiative, who is the owner of the source code. LIMITATION OF LIABILITY AND DISCLAIMER OF WARRANTY No representation is made that any of the programs, computer source code, commands, or configurations described and depicted in this manual and on the computer source code accompanying this presentation are error-free and suitable for any application that you may develop. Craig Pelkie makes no warranty of any kind, expressed or implied, including the warranties of merchantability or fitness for a particular purpose, with regard to the information, examples, and computer source code presented in this presentation and on the accompanying diskettes. Everything provided in this manual and on the accompanying diskettes is provided as is. Craig Pelkie shall not be liable in any event for incidental or consequential damages or any other claims, pursuant to your use of any of the techniques presented in this presentation, or your use of the computer source code in programs that you develop, even if Craig Pelkie has been advised of the possibility of such damages. You are responsible for testing any and all programs, configurations, commands, and procedures presented in this manual prior to using the programs, configurations, commands, and procedures with important user data. You must ensure that adequate and sufficient backup of important user data is available, in the event that recovery of the important user data is required.

Using the VisualAge for Java WebSphere Test Environment

Using the VisualAge for Java WebSphere Test Environment By Craig Pelkie Many iseries 400 shops are starting to move their development efforts to web enablement using WebSphere Application Server (WAS).