Net.Data--Now!

Web Languages
Typography
  • Smaller Small Medium Big Bigger
  • Default Helvetica Segoe Georgia Times

 

 

Are you looking for ways that your company can take advantage of the Internet, reduce costs, improve customer service, and increase market share? Do you have limited resources, people, money, and time? Do you have salespeople and customer service representatives working from home or in the field whom you need to support via the Internet? The AS/400 offers many methods of implementing solutions to these e-business problems. You see the well-publicized offerings such as Lotus Domino and Java via WebSphere. Both are excellent technologies and have a definite place within our AS/400 community. Both, however, share a common problem: They are new technologies with a significant learning curve and costs associated with building and deploying applications.

 

In today’s world of cyber-warfare, your company needs to deploy Internet-based, transaction-oriented applications today or else face loss of market share to your competitors. The IS organization needs to respond rapidly, deploy applications in days (not months or years), and be able to quickly modify these applications to meet business conditions that change constantly.

 

 

You Already Have the Answer—Net.Data

 

 

Since V4R2, IBM has shipped all of the tools you need with OS/400. All you need is the IBM HTTP Server for AS/400 and Net.Data, which are both shipped as part of 5769-DG1 (the IBM HTTP Server for AS/400 package). If you are running an older release of OS/400, you will find Net.Data packaged with the TCP/IP product (57xx-TC1). Look for the DB2WWW program in the QTCP library. Net.Data was first released under V3R2 (CISC) and V3R7 (RISC).

 

Net.Data is the glue that binds HTML, your programs, and your data together into an e-business application. Anyone can learn to write Net.Data macros and be proficient in about two weeks or less; a basic understanding of computers and programming is all that is required. I have even taught Net.Data to nontechnical business analysts and programmers alike.

 

Net.Data is a macro language that calls programs, runs SQL, invokes SQL stored procedures, and outputs dynamic HTML pages. To use Net.Data, you just need to learn HTML and a little JavaScript (Netscape’s browser-based scripting language, not to be confused with Java). Net.Data macros are stored on the host as plain text and are

 


 

interpreted by the system. This means that you can write some macro code, run it on your browser, modify it instantly, and run it again.

 

Net.Data can call programs written in any language that will run on the AS/400. It also allows you to embed SQL statements directly within a Net.Data macro and build applications without additional programs. Net.Data produces high-performance, commercial-quality business applications; employs state-of-the-art caching techniques; and is optimized for the AS/400. If you are concerned with multiple platforms and an “open systems” solution, Net.Data is available from IBM to run on Windows NT, the S/390, UNIX (not just AIX), and Linux.

 

 

So Get It Up and Running!

 

 

The first step toward using Net.Data is to set up your environment. You will need to decide where you want to store the Net.Data macros that you create. Net.Data macros are text files; they can be stored as EBCDIC members of source physical files in a library or can be stored as ASCII text files in the AS/400 Integrated File System (AS/400 IFS). I strongly suggest using AS/400 IFS subdirectories; they offer ease of use and a performance advantage. AS/400 IFS subdirectories also allow you to use PC-based editors and tools to create and maintain your macros.

 

Create a library to contain Net.Data’s initialization file (INI) and a “stub” program that calls IBM’s DB2WWW program. (In this example, the library will be called NDTST.) Then, edit the authorities for the library. Unless you change the default user profiles for the IBM HTTP Server for AS/400, the IBM user profile QTMHHTP1 will need *USE authority.

 

Create a CL ILE program that contains one statement:

 

CALL QHTTPSVR/DB2WWW

 

Compile the program (which I will call NDTST in this example) as a CL ILE program, being sure to specify the activation group compile parameter as *CALLER. Then, copy the program to the newly created NDTST library.

 

Create the Net.Data INI file. Use the Create Source Physical File (CRTSRCPF) command and set the record length to 512 bytes. The file must be named INI, and it requires one member named DB2WWW. Again, check the authorities; QTMHHTP1 must have at least *USE authority for the program object.

 

You are getting closer. This process is tedious, but it occurs only once. You must now set up the AS/400 IFS to handle your Web server and store your macros. Use the Create Directory (CRTDIR) command to create a root directory named something like /WEBSITES. You can then use Operations Navigator, Windows Explorer on your PC, or the command-line 5250 interface to create subdirectories where you will store your Net.Data macros, include files, HTML, and other Web-based objects.

 

If you have or plan to have more than one Web site, I suggest that you create a root- level directory under which to store all of the resources for your Web sites. Under /WEBSITES, I create a server root directory for each HTTP server instance that I am going to run. In my example, I have created a server root called /CUSTOMER. You might have one for vendors, employees, etc. You may also wish to create one for integration testing and one for quality assurance testing (e.g., /CUSTITG and /CUSTQAC). Under the /WEBSITES/CUSTOMER directory, create subdirectories named /MACRO and /INCLUDES. You may even wish to create a /LOGS subdirectory and configure the HTTP server to store its log files there.

 

Now issue a Change Current Directory (CHGCURDIR) command, specifying “/” as its only parameter, on the 5250 command line to set the current directory to the AS/400 IFS root. Do a Work with Links (WRKLNK) command, and you should see the IBM- provided directories in the AS/400 IFS root and the /WEBSITES directory that you created.

 


 

Be sure that the HTTP user profile QTMHHTTP has at least *RX authority to each of the subdirectories. Also make sure that QTMHHTP1 has *RX authority to the /MACRO and /INCLUDE subdirectories. (Objects created in these subdirectories should inherit the authorities of the parent directory.) Visit the directory tree one more time and set *PUBLIC to *EXCLUDE. I strongly recommend that no library or directory on a server machine allow public access to anything; use authorization lists to allow developers access to the locations they need to access.

 

Now edit the Net.Data INI file and put in the values that will control your Net.Data environment.

 

Perhaps the best and easiest way to edit this file is to use Operations Navigator. You can select Database, add the library that contains the INI file, select the library, and “OPEN” the file. You can then edit the file directly within Operations Navigator.

 

Figure 1 illustrates a Net.Data INI file that I have used for several years, adding entries to it as IBM has made them available. Line 1 tells Net.Data where to locate its macro files; notice that I have provided the fully qualified path from the AS/400 IFS root. Line 2 tells Net.Data where to look for Net.Data include files. (More on those later.) Since Net.Data can call any program on the machine, the statement on line 3 lets Net.Data find libraries containing objects that it may execute; notice that you can specify multiple libraries and separate them with a semicolon. Line 5 sets the commitment control option for Net.Data; READ_UNCOMMITTED is equivalent to compiling a program with the *CHG option. You will want the line 6 option set to YES during development and NO when you are running a production server; this option allows Net.Data to display SQL statements on your HTML pages for diagnostic purposes. Finally, set line 7 to the IP address or domain name of your Simple Mail Transfer Protocol (SMTP) server so you can use Net.Data’s powerful DTW_SENDMAIL built-in function.

 

Save the file, and you are almost there. Configure and start an instance of the IBM HTTP Server for AS/400. You should follow the quick-start instructions in the Webmaster’s Guide for IBM HTTP Server for AS/400; you can find this guide at www.as400.ibm.com/tstudio/ http/docs/doc.htm. After you get your Web server started and running, you will need to use the server administration screens or the Work with HTTP Configuration (WRKHTTPCFG) command to customize the server configuration for Net.Data.

 

Figure 2 provides the significant excerpts from an HTTP server configuration file illustrating the MAP, EXEC, and PASS directives required to enable Net.Data. PASS allows your HTTP server to access objects stored in the AS/400 IFS directory; you should store your “welcome,” or index, page (index.htm or index.html) in the directory specified on the right-hand side of the directive (/WEBSITES/CUSTOMER/*).

 

Net.Data’s main program is a Common Gateway Interface (CGI) program, and all CGI programs require that an EXEC directive be specified. Take note of the special notation used to specify paths to QSYS library system objects; the asterisk (*) allows the server to execute any object residing in the NDTST library.

 

The final step is to add the MAP directive illustrated in Figure 2. A MAP directive creates an alias for a server directory path. The MAP directive in Figure 2 creates a fictitious directory path /cgi-bin/ db2www/* and “maps” it (i.e., creates an alias for it) to the real path /QSYS.LIB/NDTST.LIB/NDTST.PGM/*. Notice the trailing /*; this allows you to pass parameters to NDTST.PGM.

 

You will use the alias /cgi-bin/db2www when you run a macro from your browser, but, before I explain that, stop and start your HTTP server instance to implement these new server directives. You are going to create a macro called helloworld.mac, which you can execute directly from your browser by typing www.myserver.com/cgibin/db2www/helloworld. mac/main. Notice that /cgi-bin/db2www is used in the URL to point to the macro but hide its real location. (I use such MAP directives to make life a bit tougher for hackers

 


 

if they should somehow penetrate my security and gain access to my file system, which is extremely unlikely.)

 

 

The Tools of the Trade

 

 

You can use SEU and create both Net.Data macros and include files in source physical file members (if you are a masochist), but the easiest way is to use Client Access and NetServer and access files in the AS/400 IFS directly with a PC text editor. You can use Windows notepad.exe (which is not very satisfactory, since it has no line numbers), a word processor (if you remember to save your files as plain ASCII text), or a good free or shareware editor that you can find on the Web. Better On-line Solutions’ SiteBoss/400 is a dedicated Net.Data editor; it is a bit expensive but guides you through Net.Data syntax and helps you write SQL. There is also a product available called EditPad. To obtain it, you have to send the author a postcard at www.jgsoft.com/contact.html, but it’s free otherwise. My personal favorite, which costs only about $50, is UltraEdit32; you can find more on this product at www.ultraedit.com under Editors or Utilities.

 

 

So Let’s Do Something Already!

 

 

This obligatory Hello World macro will introduce you to some basic concepts and hopefully get you started on your way toward building sophisticated, interactive, Web- based systems. Figure 3 (page 71) illustrates the source code for the macro. As you can see, there is no point to writing this macro other than to illustrate some basic Net.Data macro concepts. There is nothing in the macro that could not be done in plain HTML. You will notice that most of the lines in this macro are pure HTML statements; Net.Data uses language syntax very similar to C or C++.

 

Line 1 is a comment; it begins with a %{ tag and is terminated by a %} tag. Many Net.Data constructs begin with a curly brace ({) and are terminated by a percent sign and curly brace (%}). Blocks of code delimited by braces must be terminated, or errors will occur.

 

Lines 3 through 6 introduce a DEFINE block. The DEFINE block is implemented with the keyword %DEFINE. The curly brace indicates the beginning of the data being defined, and the %} tag on line 6 terminates the DEFINE block. DEFINE blocks are used to declare variables and assign values to them. This DEFINE block declares two variables, ND and world. Line 4 declares the variable ND and assigns it the value “Net.Data”; line 5 declares the variable world and assigns it the value “World.” Net.Data employs both local and global variables. Variables defined within a %DEFINE statement or %DEFINE { ... %} block are created as global variables and are available throughout the macro. Local variables are defined within a function and exist only within the function.

 

Line 8 introduces an HTML section. (Lines 8 through 21 and lines 23 through 36 are HTML sections.) Data stored within an HTML section is written to a special system file called STDOUT. The contents of STDOUT are then transmitted by the HTTP server to the user’s browser as HTML and displayed by the browser. An HTML section is an entry point to the macro; it is where processing begins (similar to the first line in the C-specs of an RPG program). A macro may have many HTML sections. Each HTML section can be used as the entry point of the macro. An HTML section has a name; the HTML section defined beginning on line 8 is named “main.” In addition, the HTML section is a block construct; notice that its contents follow the curly brace and end just prior to the %} tag on line 21. This macro can be invoked by typing the following URL on your browser’s address line: www.mywebsite.com/cgi-bin/db2www/helloworld.mac/main. Notice that the HTML section where the macro is to begin processing is included after helloworld.mac in the URL. My use of the word main is a convention that I picked up from the C language to represent the initial entry point in a program, but you can use any name that makes sense to you and your application. I suggest that you build a set of standards as you gain familiarity

 


 

with the language; it really helps when debugging macro errors. (Yes, you will have errors.)

 

The only significant code in the HTML section main is line 14, where you will see the notation $(ND) and $(world). The $() construct instructs Net.Data to replace the variable name with the contents of the variable. For example, consider this statement on line 14:

 

Welcome to $(ND)’s $(world)

 

If you examine this statement, you will see that Net.Data produces the following

 

output:

 

 

Welcome to Net.Data’s World

 

 

Remember that, back on line 4, you assigned the variable ND a value of “Net.Data” and that, on line 5, you assigned world a value of “World.” This is how variable output is combined with text or HTML statements to produce output. The only other significant part of this macro is the HTML

 


 

Notice that this HTML dynamic link refers to the HTML section named red instead of main. When the link is clicked, the macro helloworld.mac will be invoked and processing will begin at the HTML(red) HTML section.

 

Figure 4 shows the browser output of the Hello World macro.

 

 

Where Do You Go from Here?

 

 

I hope that I have clearly explained some of the basic concepts of Net.Data and helped you get set up and running. Net.Data is very easy; don’t make it hard. Net.Data is also introduced and explained step by step in my book Getting Down to e-business with AS/400, available from Midrange Computing.

 

You can also visit IBM's Net.Data Web site at www.as400. ibm.com/netdata, where you can find FAQs, code samples, PTFs, and a forum where you can participate in discussions with IBM's Net.Data developers and other Net.Data users.

 

 

References and Related Materials

 

 

• Better On-line Solutions SiteBoss/400 Web site: www.siteboss.com
• IBM AS/400 Net.Data Homepage: www.as400.ibm.com/netdata
• Net.Data Cross-platform home page: www-4.ibm.com/software/data/net.data/
• IGNITe/400 Web site: www.ignite400.org

 

1.00 0 MACRO_PATH /webserver/test/Macro
2.00 0 INCLUDE_PATH /webserver/test/Include
3.00 0 EXEC_PATH /QSYS.LIB;/QSYS.LIB/CGITST.LIB;/QSYS.LIB/CGITST.LIB/REXXCGI.FILE
4.00 0
5.00 0 DTW_SQL_ISOLATION DTW_SQL_READ_UNCOMMITTED
6.00 0 DTW_SHOWSQL=YES
7.00 0 DTW_SMTP_SERVER 141.11.20.58
8.00 0 DTW_PAD_PGM_PARMS = YES
9.00 0 DTW_MACRO_CACHE_SIZE = 16

 

Figure 1: Net.Data’s INI configuration file sets the environment for all Net.Data scripts.

 


 

Map /cgi-bin/db2www/* /QSYS.LIB/NDTST.LIB/NDTST.PGM/*
Exec /QSYS.LIB/NDTST.LIB/*
Pass /* /websites/customer/* The obligatory Hello World Macro

 

1. %{ Macro: bcbk_hello.mac - A simple hello world macro %}
2.

 

3. %DEFINE { %{ This is a define block. It defines two variables %}
4. ND = "Net.Data"
5. world = "World"
6. %}

 

7.

 

8. %HTML(main) { %{ Initial Entry point. Displays the text in Blue %}
9.
10.
11. Net.Data Sample Macros -- Welcome to Net.Data's World
12.
13.14.

Welcome to $(ND)'s $(world)


15.

Click here for:
16.
17. RED


18.


19.


20.
21. %}

 

 

22.

 

23. %HTML(red) { %{ Secondary Entry point Displays the text in Red %}
24.
25.
26. Net.Data Sample Macros -- Welcome to Net.Data's World
27.
28.29.

Welcome to $(ND)'s $(world)


30.

Click here for:
31.
32. BLUE


33.


34.


35.
36. %}

 

 

Figure 2: The HTTP configuration file needs to have MAP and EXEC directives specific to the DB2WWW Net.Data engine.

 

Figure 3: The obligatory Hello World macro can be used as a template for developing more sophisticated Net.Data applications.

 


 

 

Net._Data--Now_07-00.png 400x290

 

 

Figure 4: The simple Hello World macro gives a view of the Net.Data world through a Web browser.

 


 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

BLOG COMMENTS POWERED BY DISQUS