Connect Your Data to the Web with Net.Data

by John E. Peterson

Creating Web pages is easy. The hard part is keeping them up-to-date, especially when they contain live data from a database or other repository. The DB2 WWW Connection, now called Net.Data, provides Web macros that make it easy to connect your DB2 data to the Web, often with little or no programming. And it's available on both OS/2 and AIX!

On your Volume 11 CDs, we're introducing an enhanced Beta version of Net.Data, that enables you to connect even more data to your Web pages. In addition to DB2 data, Net.Data provides the ability to include data from many new sources such as REXX programs and ODBC databases. It also provides a new "include" capability that makes your Web macros easier to maintain, along with many other new features.

What Are Web Macros?
A Web macro starts with the simplicity of HTML pages and adds the capability of inserting live data into them, making it possible to build useful database applications for the Web with little or no programming.

A typical Web macro consists of two HTML sections (an input and a report section), an SQL section, and replacement variables that pass data between sections. The input HTML section normally contains an HTML  definition that allows the user to enter data; the output HTML section contains HTML that presents the results of the operation that is to be performed; and the SQL section contains an SQL statement that is executed by the HTML report section. The data that is entered by the user into the HTML input section is substituted into the SQL statement prior to its execution, and the results of the SQL operation are included in the HTML report section.

The HTML  definition usually points to another invocation of Net Data, often specifying the execution of the HTML report section of the current macro, thus chaining operations together A complete database inquiry and update application can be created by putting a pointer to another macro in the HTML report section This process is best shown by an illustration:



Imagine that you have data in a database (for example, a company telephone directory), and you want to create an application that allows employees to query and perhaps even update the database from Web browsers attached to an intranet. Assuming that you already have the database established, you can easily create the enquiry application by creating a single Web macro of the type illustrated.

An attractive feature of Web macros is their simplicity and familiarity. They are composed of standard HTML (limited only by what your target browser will accept), standard SQL, and a small number of macro directives. HTML is quite easy to learn and use, and SQL is also widely understood, so you'll be on familiar ground.

Instructions to the macro processor are of several types:
 * Replacement variables, indicated by $(varname)
 * Macro directives, which always begin with %keyword or by %{ directive %}
 * Function invocations (new), indicated by function_name

Replacement Variables
Replacement variables are a key feature of Web macros. They are symbolic names for text strings that are not known at the time the Web macro is written, but are given values during the processing of the macro. One way they can be given a value is as a result of the execution of an SQL statement or the execution of a function. They may also be assigned values by an explicit assignment statement, or if they are of a certain pre-defined set, they are assigned a value by the macro processor as a result of its operation.

Macro Directives
Macro directives are always prefixed with a % and are used to delimit sections of a macro, such as %HTML, %SQL, and %DEFINE.

Function Invocations
Function invocations are a new feature in Net.Data that allow you to execute a previously defined function. Functions may be defined by the programmer, or they may be one of a library provided by IBM. The new function library contains a large selection of useful operations that simplify the task of writing a macro. A function invocation causes a piece of code to be executed at the point at which it is encountered. Macro replacement variables may be passed to and from a function as input and/or output parameters. Alternately, the function may generate HTML dynamically, and it will be inserted into the output stream at the point at which the function was encountered.

The Web Macro Processor
Web macros are interpreted by the Web macro processor, which is actually a Common Gateway Interface (CGI-BIN) program that runs on the server system. When invoked via a URL from a browser, the Web macro processor takes a Web macro as its input and produces HTML as its output. The resulting HTML is sent back to the browser. During the processing of a macro, all HTML from the specified section (either input or report) are sent to the browser as-is. However, if any macro instructions are encountered (such as replacement variables or execution directives), the macro processor will process them and include any resulting text in the HTML output stream.

A typical URL for invoking a Web macro is http://server.domain.com/cgi-bin/db2www/macroname/input  where
 * server domain com is the name of the server
 * cgi-bin is typically the location on the server that contains cgi-bin programs
 * db2www is the name of the macro processor
 * macroname is the name of the macro to be run
 * input is the section of the macro to be run

Web Macro Details
Now let's examine an example macro in more detail. The actual macro contains all of the following code fragments in a single file. If you've already been using it, you may notice that the new version has introduced some syntax changes to better support the new function, but Net.Data is upwardly compatible.

The first section of a macro is usually a %define section that contains definitions for replacement variables In this example, we define two variables named DATABASE and table; the contents of these variables can then be substituted into HTML or SQL by using $(DATABASE) or $(table). Besides explicit definition as shown here, there are two other ways that variables are defined in macros by fields named in HTML statements, and by fields that are pre-defined by the macro processor itself. We'll see examples of these in later macro sections.  %define { DATABASE= CELDIAL table = swprods %}  Next we'll define an %HTML section to obtain some input, and we ll name this section input. This section is a complete HTML screen definition, delimited by %HTML(section_name){...%} Note that unlike a normal HTML file, a macro can contain multiple HTML screens in one file. Typically this % HTML section contains an HTML definition that will ask the user a question and solicit input. An HTML form contains an action parameter that specifies a CGI program on the server that should handle the user's input. Normally you would have to write a CGI program yourself to handle this input. But the Net.Data macro processor can do this for you; so it is specified on the action parameter along with the macro name and macro section (which, in this case, will be another %HTML section named report).

Here we also have an example of the second type of variable definition. Within the HTML form, there is an input field named SEARCH. The macro processor will automatically define a variable with this name, and it will place the input data entered by the user into this variable for later use (typically in the SQL section).  %HTML(input){  Example - Query Input  Query of $(table) - Input Enter search string   <INPUT TYPE= submit > <INPUT TYPE= reset > </FORM> </BODY> </HTML> %} </PRE> The results of executing the input section of our example macro are shown in the following illustration.



Next we have a function definition for SQL (this was called the %SQL section in the previous version of Net.Data) and its subsections. We'll name this section query. The first element is an SQL statement, which may contain replacement variables that will be filled in by the macro processor prior to the execution of the statement. In this case, we are substituting the replacement variable $ (SEARCH), which was input by the user on the %HTML(input) screen. Valid SQL statement types include SELECT, INSERT, DELETE, and UPDATE.

Next is the %REPORT subsection, which itself contains three subsections the report header (typically an HTML  tag). The %ROW subsection is repeated once for each row of data that is returned by the SQL statement and contains HTML tags and macro replacement variables for formatting each returned row. Following the %REPORT subsection is the %MESSAGE subsection, which is invoked in case the SQL statement resulted in an error.

This subsection shows the third way that replacement variables are defined Special variables that are automatically defined by the macro processor itself. In this case, the special variables $(V1) and $(V2) contain the data items from the first and second columns respectively in the query, which are the values of the control number and name columns. The %ROW section is repeated once for each row returned by the query and will contain the column values for each row of the resulting table. Numerous other pre-defined variables are also available, such as $(N1) and $(N2) that contain the column names.

Unlike the HTML sections, this SQL function is not invoked by a URL; it is invoked by an function statement (or by %EXEC_SQL in the previous syntax, which is still valid) in an %HTML section.  %FUNCTION(SQL) query { select controlnumber, name from $(table) where name like ‘%$(SEARCH)% %REPORT{ %} %MESSAGE{ 100 No Matching Entries Exist for ‘$(SEARCH)’ö CONTINUE %} %} </PRE> Finally, there is an %HTML section to display the results. We'll name this section report. Like the other %HTML section, this section is also a complete piece of HTML. The main job of this section will be to invoke the SQL function (using query) to do a database operation using the data that was entered in the %HTML input section and then display the results.  %HTML (report){ <HTML> Example - Query Results</TITLE> <BODY> Query of $(table) - Results</H1> <P>Your search for $(SEARCH) resulted in the following query <a href="/cgi-bin/db2www/xmp.d2w/input">Query again</a> </BODY> </HTML> %} </PRE> The results of displaying the report section of the sample macro are shown in the following illustration.



What s New in Net Data
IBM is extending Net.Data to most popular platforms, making it a portable technology. As previously mentioned, IBM has released Version 1 of the Net.Data for OS/2, AIX, AS/400, and Windows NT. Versions also are planned for OS/390, HP-UX, and Sun Solaris.

Besides widening the base of supported platforms, IBM is increasing the capabilities of Web macros. Some of the new capabilities in Net.Data include. To support these new functions, Net.Data uses a new, more generalized syntax for some items. The syntax used by the previous version is still supported for compatibility, however.
 * New data sources: Besides data from DB2 SQL, you will be able to use data from ODBC data sources, REXX programs, Perl programs, Java applets, C and C++ programs, and more. A new framework design allows you to provide your own data sources as DLLs.
 * Multiple named HTML sections: Macros can have any number of HTML sections, each with their own name. You can now package a whole application in a single macro if you want.
 * Functions (and function library): Pieces of code can be pre-defined and named for invocation within a macro to perform frequently needed operations. Programmers can define new functions and/or use from a large set of IBM-supplied functions.
 * Include files: With the new %INCLUDE directive, common sections of macros can be saved in separate files and included in multiple macros, simplifying maintenance. This capability is particularly useful for common headers and footers.
 * Conditional logic: If-Then-Else processing allows variables to be tested and parts of a macro to be selectively processed based on the results.
 * Higher performance: High-performance server API's can be used to run the macro processor, providing improved performance compared to the CGI-BIN interface. Live data connection speeds processing by maintaining a connection to the database.

The Beta Version Preview
To give you a preview of these new capabilities, we have included an early Beta version of Net.Data for OS/2 and AIX in the Internet Tools category of this volume of DevCon For OS/2, the Beta version includes the Net.Data macro processor, documentation of the new function, demonstration applications, sample code, and an online tutorial. In the demonstrations, most of the screens contain a button labeled View Macro Source that allows you to see how the macro is constructed. Please keep in mind that this Beta code is not the final code - it has bugs left, it does not contain all of the features we re planning for the final version, and some of the function and interfaces might change. The generally available version of the product will be part of the next Cross-Platform Developer Kit (XPDK) for Database Server (See the side bar for details on the XPDK)

For More Information
The latest information about the Net.Data can be found at http://www.software.ibm.com/data/db2/netdata.html. This site is updated frequently with news about the product, including updated Beta versions, and it allows you to download Beta and shipped versions of the product for all platforms.