This section tells you how to perform the basic steps necessary to get Net.Data up and running. The steps are:
If you are having problems getting Net.Data to handle requests after following the steps in this section, see "Problem Analysis" for problem determination tips.
Step 1--Copy the Net.Data Program Object to a CGI-BIN Library
The Net.Data program object that needs to be copied to a CGI-BIN library is DB2WWW, located in the QTCP library. Copy the program object using the Create Duplicate Object (CRTDUPOBJ) command.
The DB2WWW program object's object authority for *PUBLIC users is set to *EXCLUDE. Change the DB2WWW program object in the CGI-BIN directory so that the user profile that CGI programs run under has access to the program object. You can do this by changing the program object's authority for *PUBLIC users to *USE, or by specifically giving the user profile access to the DB2WWW program object.
In V3R2 and V3R7, Internet Connection for AS/400 runs CGI programs only under the QTMHHTP1 user profile.
Step 2--Add Net.Data Directives to the HTTP Configuration File
Use option 1 (Add) or option 13 (Insert) of the Work with HTTP Configuration (WRKHTTPCFG) command to do the following:
If they are not already there, add the Enable GET Y1" and Enable POST Y2" directives to the section of the configuration file where you enable methods. With the directives in the file, your display is similar to that shown in Figure 1:
+--------------------------------------------------------------------------------
Work with HTTP Configuration
System: SYSNAM01
Type options, press Enter.
1=Add 2=Change 3=Copy 4=Remove 5=Display 13=Insert
Sequence
Opt Number Entry
00010 # * * * * * * * * * * * * * * * * * * * * * * * * * * #
00020 # HTTP CONFIGURATION FOR NET.DATA TESTING #
00030 # #
00040 HostName sysnam01.location.company.com
00050 Port 80
00060 #-----------------------------------------------------
00070 # Methods Enabled
00080 #
00090 Enable GET Y1"
00100 Enable POST Y2"
00110 #
00120 #-----------------------------------------------------
More...
F3=Exit F5=Refresh F6=Print List F12=Cancel F17=Top F18=Bottom
F19=Edit Sequence
+--------------------------------------------------------------------------------
Figure 1. Work with HTTP Configuration (WRKHTTPCFG) -- Display 1
Add the Map and Exec statements shown in Figure 2. This display shows the directives after they have been added.
+--------------------------------------------------------------------------------
Work with HTTP Configuration
System: SYSNAM01
Type options, press Enter.
1=Add 2=Change 3=Copy 4=Remove 5=Display 13=Insert
Sequence
Opt Number Entry
00130 #-----------------------------------------------------
00140 # Mapping/Pass Rules + Executables
00150 #
00160Y1" Map /cgi-bin/db2www/* /QSYS.LIB/CGI.LIB/DB2WWW.PGM/*
00170Y1" Map /CGI-BIN/DB2WWW/* /QSYS.LIB/CGI.LIB/DB2WWW.PGM/*
00180 #
00190 #
00200Y2" Exec /QSYS.LIB/CGI.LIB/*
00210 Pass /WWW/html/*
00220 #-----------------------------------------------------
More...
F3=Exit F5=Refresh F6=Print List F12=Cancel F17=Top F18=Bottom
F19=Edit Sequence
+--------------------------------------------------------------------------------
Figure 2. Work with HTTP Configuration (WRKHTTPCFG) -- Display 2
The Map directives Y1" map entries in the form "/cgi-bin/db2www/*" to the library where the Net.Data program resides on your system. (The asterisk (*) at the end of the string refers to anything that follows the string.) Both upper- and lower-case map statements are included, because the directives are case sensitive. In this example, both Map statements map to the same location.
The Exec directive Y2" enables the HTTP server to execute any CGI programs in the CGI library. Specify the library where the program resides (not the program itself) on the directive. To prevent other *PGM objects in the CGI library from being executed, exclude *PUBLIC and QTMHHTP1 from object access.
You must restart the HTTP server for changes to the configuration file to take effect using STRTCPSVR CL command as follows:
STRTCPSVR *HTTP RESTART(*HTTP)
Note that Pass directives are not used by Net.Data. If you want to simplify your URL, then use the MACRO_PATH statement in an Net.Data initialization file. See next step.
Step 3--Create the Net.Data Initialization File
The creation of the Net.Data initialization file is optional. The benefit of using an initialization file is shorter URLs and shorter references to programs and include files within your Web macro files. However, you are required to have an initialization file if you decide to create your own language environment.
If an initialization file is not created, then Net.Data runs as if an initialization file with only the supported language environment statements (see "Supported Language Environments") in the file had been configured. All macro, include, and executable references need to be fully qualified.
If an initialization file is created, and then updated, you do not need to end or restart the HTTP server in order for the changes to take effect. Net.Data reads the initialization file once, during the initial invocation by an HTTP server job. The configuration data is saved so that on subsequent Net.Data invocations, Net.Data does not have to read the initialization file. However, if a change is made to the initialization file, Net.Data detects the change to the initialization file and reads the initialization file again.
Use the Create Source Physical File (CRTSRCPF) command to create the initialization file. Since the text of configuration statements must all be on one line, it is a good idea to create the initialization file with a record length of 240. The file must be created in the library where the DB2WWW program object resides. The file name must be "INI." The member name must be "DB2WWW". Use the Source Entry Utility (SEU) to add configuration statements to the file.
A sample initialization file is shown in Figure 3. The text of each individual configuration statement must all be on one line. (An ENVIRONMENT statement is shown on several lines for readability.) Note there is a total of 6 configuration statements (excluding blank lines) in the Net.Data initialization file below. Also note that the ENVIRONMENT statements are not needed if you are planning on not using any language environments in your Web macros. Nor do you have to specify any of the path configuration statements.
+----------------------------------------------------------------------- MACRO_PATH /WWW/MACRO;/QSYS.LIB/WWW.LIB/MACRO.FILE INCLUDE_PATH /WWW/MACRO;/QSYS.LIB/WWW.LIB/MACRO.FILE EXEC_PATH /QSYS.LIB;/QSYS.LIB/WWW.LIB ENVIRONMENT(DTW_REXX) /QSYS.LIB//QTCP.LIB/QTMHREXX.SRVPGM ( ) ENVIRONMENT(DTW_SQL) /QSYS.LIB/QTCP.LIB/QTMHSQL.SRVPGM (IN DATABASE, LOGIN, PASSWORD, TRANSACTION_SCOPE, SHOWSQL, DB_CASE, DTW_SET_TOTAL_ROWS, OUT DTWTABLE, SQL_CODE, TOTAL_ROWS ) ENVIRONMENT(DTW_SYSTEM) /QSYS.LIB/QTCP.LIB/QTMHSYS.SRVPGM ( ) +----------------------------------------------------------------------- Figure 3. Contents of Net.Data Initialization (INI) File
Step 4--Create Net.Data Web Macros
Before creating a Web macro, you need to decide which file system your Web macros will reside in. It does not matter to Net.Data whether the Web macros are stored in a UNIX-like file system, such as QOpenSys, or whether it is stored in the library file system (QSYS.LIB). You may even want to store Web macros in multiple file systems.
Depending on the file system you choose to store your Web macros, you will need to create a directory or library. Here are some examples:
CRTDIR DIR('/WWW')
CRTDIR DIR('/WWW/macro')
CRTLIB LIB(WWW) CRTSRCPF FILE(WWW/MACRO) RCDLEN(240)
Once you have created the directory or library, you now need to create a Web macro and copy it to the directory or library. You can use source entry utility to create a source physical file member on your AS/400 system. You can copy the member to a file system (e.g. "root") directory from the source physical file member using the Copy To Stream File (CPYTOSTMF) CL command. For example, assume that we created the source physical file member, MACSAMP, in library WWW, source physical file MACRO, and the member contained the following text:
%HTML(HelloWorld) {
<P>Hello World
%}
If we wanted to copy the member to directory /WWW/macro in the "root" file system, then we would need to use CPYTOSTMF as follows:
CPYTOSTMF FROMMBR('/qsys.lib/www.lib/macro.file/MACSAMP.mbr')
TOSTMF('/WWW/macro/MACSAMP') STMFOPT(*REPLACE) ENDLINFMT(*LF)
Step 5--Grant User Profile Authority to Objects
The user profile that CGI programs run under must have the proper access to any objects that are referenced in a Web macro and to the macro that a URL references.
In V3R2 and V3R7, Internet Connection for AS/400 ran CGI programs only under the QTMHHTP1 user profile.
Depending on the file system in which you choose to store your Web macros, you will need to authorize the user profile that the Net.Data CGI program is run under to the Web macro. Here are some examples that give the QTMHHTP1 user profile authority:
CHGAUT OBJ('/WWW') USER(QTMHHTP1) DTAAUT(*RX)
CHGAUT OBJ('/WWW/macro') USER(QTMHHTP1) DTAAUT(*RX)
CHGAUT OBJ('/WWW/macro/*') USER(QTMHHTP1) DTAAUT(*RX)
GRTOBJAUT OBJ(WWW) OBJTYPE(*LIB) USER(QTMHHTP1) AUT(*USE) GRTOBJAUT OBJ(WWW/MACRO) OBJTYPE(*FILE) USER(QTMHHTP1) AUT(*USE)
You can also use the CHGAUT CL command to give authority to objects in the QSYS.LIB file system as follows:
CHGAUT OBJ('/QSYS.LIB/WWW.LIB') USER(QTMHHTP1) DTAAUT(*RX)
CHGAUT OBJ('/QSYS.LIB/WWW.LIB/MACRO.FILE') USER(QTMHHTP1) DTAAUT(*RX)
Language environment-specific authority considerations are documented in each language environment section in "Supported Language Environments".
Step 6--Invoke Net.Data Web Macros
Net.Data for the OS/400 can only be invoked as a common gateway interface (CGI) program. Net.Data can be invoked from on of the following methods:
<A HREF="http://{<I>web-server}/cgi-bin/db2www/{macro-file}/
{HTML-block}ÿ?name=val&...ÿ">any text</A>
<FORM METHOD={method} ACTION=http://{web-server}/cgi-bin/db2www/
{macro-file}/{HTML-block}ÿ?name=val&...ÿ>any text</FORM>
http://{<I>web-server}/cgi-bin/db2www/{<I>macro-file}/{<I>HTML-block}
ÿ<I>?name=val&...ÿ
Table 76. Macro Invocation Elements
| method | You can specify either get or post, which are specified in HTML 2.0. Using the get method is discouraged because of its limitations. |
| web-server | This is the name of the Web server as defined by the system administrator. For example, www.imb.com. If the macro exists locally, you only need the relative URL, omitting http://www.ibm.com/. |
| macro-file | This is the name of the Web macro as defined by the Net.Data application developer. What you specify here is directly tied to whether or not your have a Net.Data initialization file with the MACRO_PATH statement specified. If MACRO_PATH is not specifed, then you will need to specify the fully qualified path name to the Web macro. For example, macro-file would be /QSYS.LIB/WWW.LIB/MACRO.FILE/MACSAMP.MBR if MACRO_PATH was not specified in the initialization file. However, if the initialization file had a MACRO_PATH statement, then macro-file would be MACSAMP.MBR. |
| HTML-block | This is the name of the HTML block in the Web macro you are invoking. |
| ?name=val& | These are optional parameters that can be passed in your applications. For example, you can pass the user ID so it doesn't have to be entered multiple times or you can pass the name of a Web macro that calls another macro so you can back out. |
The URL (assuming no MACRO_PATH statement) needed to invoke the sample macro created previously would be:
http://server/cgi-bin/db2www/WWW/MACRO/MACSAMP/HelloWorld
http://server/cgi-bin/db2www/QSYS.LIB/WWW.LIB/MACRO.FILE/MACSAMP.MBR/HelloWorld