Net.Data provides a number of language environments, although some platforms do not support all environments. Table 1 lists the IBM-supplied language environments. To determine whether a language environment is supported on your platform, see the appendix of Net.Data Reference Guide.
REPORT and MESSAGE blocks are allowed in all FUNCTION blocks. These blocks are processed by Net.Data, not the language environment.
The RETURN_CODE variable is set by Net.Data to the function return value on every function call to a language environment. You can check this value to determine if a function call completed successfully or failed. Net.Data uses the RETURN_CODE value to process any local or global MESSAGE blocks specified for a function. For compatibility with DB2 WWW Connection, SQL_CODE also is set to the same value.
This table shows the language environments that Net.Data supplies.
ENVIRONMENT statements in the initialization file are also used for Net.Data
built-in functions on some platforms. See your Net.Data README file or Program
Directory for details about the language environment statements your platform
uses.
Table 1. Net.Data Language Environments
| Language Environment | Environment Statement | Description |
|---|---|---|
| Java Applet | DTW_APPLET | The Java applet language environment lets you use Java applets in your Net.Data applications. To generate an applet tag, you must provide the applet tag's qualifiers and the applet's parameter list. |
| Default C | DTW_DEFAULT |
The initialization file on some platforms includes an ENVIRONMENT statement
that is required for the Net.Data built-in functions. See Net.Data
Reference
Guide for more information about using the built-in functions.
|
| Flat File Interface | DTW_FFI |
The flat file interface (FFI) is available on some platforms to let you use
flat files (or plain-text files) as your data source. Some platforms that
support FFI use an ENVIRONMENT statement in the initialization file. See
Net.Data Programming Guide for more information about using FFI.
|
| Java Application | DTW_JAVAPPS | Net.Data supports your existing Java applications with the Java language environment. |
| ODBC | DTW_ODBC | The ODBC** language environment executes SQL statements through an ODBC interface for access to multiple database management systems. |
| Oracle | DTW_ORA | The Oracle** language environment lets you communicate directly with your Oracle data. |
| PERL | DTW_PERL | The PERL language environment interprets internal PERL scripts that are specified in a FUNCTION block of the Net.Data macro, or it executes external PERL scripts stored in separate files. |
| REXX | DTW_REXX | The REXX language environment interprets internal REXX programs that are specified in a FUNCTION block of the Net.Data macro, or it can execute external REXX programs stored in a separate file. |
| SQL | DTW_SQL | The SQL language environment executes SQL statements through DB2. The results of the SQL statement can be returned in a table variable. |
| Sybase** | DTW_SYB | The Sybase** language environment lets you communicate directly with your Sybase data. |
| System | DTW_SYSTEM |
The System language environment supports calls to external programs that
are identified in an EXEC statement in the FUNCTION block. The System language
environment interprets the EXEC statement by passing the program name
parameters to the operating system for execution.
|
| Web registry | DTW_WEBREG |
The Net.Data Web registry is available on some platforms and provides
persistent storage for application-related data. Some platforms that support
the Web registry use an ENVIRONMENT statement in the initialization file. See
Net.Data Programming Guide for more information about using the Web registry.
|
Each language environment requires an ENVIRONMENT statement in the initialization file and a shared library or dll file in the server's /lib or /dll directory. We recommend making a backup of your initialization file before making changes.
The Java applet language environment lets you use standard Java applets in your Net.Data applications.
To generate an applet tag, you specify the applet tag's qualifiers (code, codebase, width, height in this example) and the applet's parameter list.
The following sections describe the syntax of the function call that generates the applet tag and the syntax for the applet tag qualifiers and parameters. An example of using the Java applet backend is ***.
The function call to invoke a Java applet has this syntax:
@DTWA_AppletName(parameter1, parameter2, ..., parameterN)
The DTWA_ prefix identifies the function call to generate the applet tag. AppletName is the name of the applet for which a tag is generated. This function call is typically made in the HTML section.
Because HTML tags change over time, Net.Data has a flexible, yet powerful, method for setting values. You can specify applet tag qualifiers anywhere in your Net.Data macro. All variables that have the form AppletName.qualifier are substituted into the applet tag as qualifiers. An example of defining an applet qualifier is shown here:
%define AppletName.Qualifier = "value"
The actual assignment need not be in a DEFINE section. You can set the value with the DTW_ASSIGN function or set it automatically in an SQL section. If you do not define a variable forAppletName.code variable, a default code parameter is added to the applet tag. The value of the code parameter is AppletName.class, where AppletName is the name of your applet.
The parameter list is set when you call the applet in Net.Data. You can pass
A PARAM tag with the name DTW_NUMBER_OF_TABLES is generated every time. The value is the number of table variables used in the function. If no table variables are specified in the function call, this tag is generated:
<param name = "DTW_NUMBER_OF_TABLES" value = "0" >
The DTW_APPLET_ALTTEXT variable can be used to insert HTML between the last PARAM tag and the end APPLET tag. The HTML text this variable contains is displayed on browsers that do not support the APPLET tag.
You can use regular Net.Data variables as parameters. For example, if you specify a variable on a DTWA_AppletName function call, one PARAM tag is generated that has the same name and value as the variable.
One or more table variables can be used as parameters also. If you specify a Net.Data table variable on a DTWA_AppletName function call, several additional PARAM tags are generated. First, a PARAM tag is generated for the table, for example:
<param name = 'DTW_TABLE_i_NAME' value = "tname" >
The variable i is the number of the table and tname is the name of the table.
Next, PARAM tags are generated to specify the number of rows and columns of the table, for example:
<param name = 'DTW_tname_NUMBER_OF_ROWS' value = "rows" > <param name = 'DTW_tname_NUMBER_OF_COLUMNS' value = "cols" >
The name of the table is tname, rows is the number of rows in the table, and cols is the number of columns in the table. This pair of tags is generated for each unique table specified in the function call.
Next, a PARAM tag is generated for each column in the table, for example:
<param name = 'DTW_tname_COLUMN_NAME_j' value = "cname" >
The table name is tname, j is the column number, and cname is the name of the column in the table.
Lastly, PARAM tags are generated that contain the values in each row:
<param name = 'DTW_tname_cname_VALUE_k' value = "val" >
The table name is tname, cname is the column name, k is the row number, and val is the value that matches the value in the corresponding row and column.
You can pass a table column as a parameter on a function call. A table column parameter has this form:
@DTWA_AppletName(DTW_COLUMN( x )Table)
Where x is the name or number of the column in the table.
The same parameters are passed for column parameters as for tables and the DTW_tname_NUMBER_OF_COLUMNS parameter is always 1. Only parameter tags specific to the column are generated, not the other columns in the table.
Suppose the following is specified in a macro file:
%define{
DATABASE = "celdial"
DTW_APPLET_ALTTEXT = "<P>Sorry, your browser is not Java-enabled."
DTW_HTML_TABLE = "yes"
DTW_SAVE_TABLE_IN = "MyTable"
MyGraph.codebase = "'MyMachine.ibm.com"
MyGraph.height = "200"
MyGraph.width = "400"
MyTitle = "This is my Title"
%}
%SQL(A){
select age, count(age)
as ages from guests
where age >= 35
group by age
%}
%HTML_REPORT{
%EXEC_SQL(A)
@DTWA_MyGraph( MyTitle, DTW_COLUMN(ages) MyTable )
%}
In the example Net.Data macro, these lines in the define section generate the first line of the applet tag:
MyGraph.codebase = "'MyMachine.ibm.com" MyGraph.height = "200" MyGraph.width = "400"
The applet contains these qualifiers:
<applet code = 'MyGraph.class' codebase = 'MyMachine.ibm.com' width = '400' height = '200' >
The result of the SQL query in the SQL section of the Net.Data macro file are returned in the result table, MyTable, which was set in the define section by the line DTW_SAVE_TABLE_IN = MyTable. The call to the applet in the macro @DTWA_MyGraph( MyTitle, DTW_COLUMN(ages) MyTable ) generates the complete applet tag containing the information about the result table such as the number of columns, the number of rows returned, and the result rows. There is one parameter tag generated for each cell in the result table as shown in the following line:
param name = 'DTW_MyTable_ages_VALUE_1' value = "4">
The parameter name DTW_MyTable_ages_VALUE_1 refers to the table cell (row 1, column 'ages') in the table MyTable, which has a value of 4. The keyword DTW_COLUMN in the call to the applet specifies that you are interested only in the column ages of the resulting table, MyTable, shown here:
@DTWA_MyGraph( MyTitle, DTW_COLUMN(ages) MyTable )
A complete applet tag that is generated for the example looks like this:
<applet code = 'MyGraph.class' codebase = 'MyMachine.ibm.com' width = '400' height = '200' > <param name = 'MyTitle' value = "This is my Title" > <param name = 'DTW_NUMBER_OF_TABLES' value = "1" > <param name = 'DTW_TABLE_1_NAME' value = "MyTable" > <param name = 'DTW_MyTable_NUMBER_OF_ROWS' value = "5" > <param name = 'DTW_MyTable_NUMBER_OF_COLUMNS' value = "1" > <param name = 'DTW_MyTable_COLUMN_NAME_1' value = "ages" > <param name = 'DTW_MyTable_ages_VALUE_1' value = "4"> <param name = 'DTW_MyTable_ages_VALUE_2' value = "1"> <param name = 'DTW_MyTable_ages_VALUE_3' value = "1" > <param name = 'DTW_MyTable_ages_VALUE_4' value = "1" > <param name = 'DTW_MyTable_ages_VALUE_5' value = "1" > <P>Sorry, your browser is not Java-enabled.<BR> </applet>
We recommend that you subclass your applets from the DTW_Applet class because of its useful interfaces that help process the APPLET tag. Net.Data provides these interfaces:
An example of an applet class which is sub-classed from the DTW_Applet class using these interfaces is shown in this example:
import java.io.*;
import java.applet.Applet;
public class myDriver extends DTW_Applet
{
public void init()
{
super.init();
if (GetNumberOfTables() > 0)
{
String [] tables = GetTableNames();
printTables(tables);
}
}
private void printTables(String[] tables)
{
String table_name;
for (int i = 0; i < tables.length; i++)
{
table_name = tables[i];
printTable(table_name);
}
}
private void printTable(String table_name)
{
int nrows = GetNumberOfRows(table_name);
int ncols = GetNumberOfColumns(table_name);
System.out.println("Table: " + table_name + " has " + ncols + " columns and " +
nrows + " rows.");
String [] col_names = GetColumnNames(table_name);
System.out.println("---------------------------------------------------------");
for (int i = 0; i < ncols; i++)
System.out.print(" " + col_names[i] + " ");
System.out.println("\n--------------------------------------------------------");
String [][] mytable = GetTable(table_name);
for (int j = 0; j < nrows; j++)
{
for (int i = 0; i < ncols; i++)
System.out.print(" " + mytable[i][j] + " ");
System.out.println("\n");
}
}
}
Net.Data supports your existing Java applications with the Java language environment.
Net.Data has growing Java Database Connectivity (JDBC**) support; this version supports Java applets and Java methods (or applications) to access DB2 through JDBC API.
Details on JDBC are available from these sites:
http://www.software.ibm.com/data/db2/jdbc/
http://splash.javasoft.com/jdbc/
Writing a JDBC application or applet is very similar to writing a C application using DB2 CLI or ODBC to access a database. The primary difference between applications and applets is that an application may require special software to communicate with DB2, for example, DB2 Client Application Enabler. The applet depends on a Java-enabled Web browser, and requires no DB2 code installed on the client.
Your system requires some configuration before using JDBC. These considerations are discussed at DB2 JDBC Application and Applet Support:
http://www.software.ibm.com/data/db2/jdbc/db2java.html
To use JDBC from Java applets, start DB2's JDBC applet server on your Web server. To use JDBC from Java methods:
The Open Database Connectivity (ODBC) language environment executes SQL statements through an ODBC interface. ODBC is based on the X/Open SQL CAE specification, which lets a single application access many database management systems.
To use the ODBC language environment, you must have an ODBC driver and a driver manager. Your ODBC driver documentation describes how to install and configure your ODBC environment.
Sending SQL statements in an ODBC environment is similar to other Net.Data functions. This example is a Net.Data macro that sends multiple SQL statements to an Oracle** database. Platforms that use the DATABASE variable must specify the same database as the data source in the ODBC.INI file.
%DEFINE {
DATABASE="qeora7"
SHOWSQL="YES"
table="int_null"
LOGIN="netdata1"
PASSWORD="ibmdb2"
%}
%function(dtw_odbc) oracle1() {
create table int_null (int1 int, int2 int)
%}
%function(dtw_odbc) oracle2() {
insert into $(table) (int1) values (111)
%}
%function(DTW_ODBC) oracle3() {
insert into $(table) (int2) values (222)
%}
%function(dtw_odbc) oracle4() {
select * from $(table)
%}
%function(DTW_ODBC) oracle5() {
drop table $(table)
%}
%HTML(REPORT) {
@oracle1()
@oracle2()
@oracle3()
@oracle4()
%}
The Oracle language environment lets you communicate directly with your Oracle data. You must have Oracle's SQL*Net installed on the server. For more information, see:
http://www.oracle.com/products/networking/html/stnd_sqlnet.html
Stored procedures are not supported through this language environment. The DATABASE variable is not needed to access Oracle databases.
With the Oracle language environment defined in the initialization file and SQL*Net running, you are set to put your data out on the Web. Make calls to the Oracle language environment with functions like this:
%FUNCTION(DTW_ORA) STL1() {
insert into $(table) (int1,int2) values (111,NULL)
%}
The PERL language environment can interpret inline PERL scripts that you specify in a FUNCTION block of the Net.Data macro, or it can process external PERL scripts stored in separate files on the server. Calls to external PERL scripts are identified in a FUNCTION block by an EXEC statement, for example:
%EXEC{ perl-script-name [optional parameters] %}
The PERL language environment cannot directly pass or retrieve Net.Data variables, so they are made available to PERL scripts in this manner:
The following Net.Data Net.Data macro example shows how it is done.
%FUNCTION(DTW_PERL) today() RETURNS(result) {
$date = `date`;
chop $date;
open(DTW, "> $ENV{DTWPIPE}") || die "Could not open: $!";
print DTW "result = \"$date\"\n";
%}
%HTML(INPUT) {
@today()
%}
This same function can be written as in the next example, if the PERL script were in an external file called today.prl:
%FUNCTION(DTW_PERL) today() RETURNS(result) {
%EXEC { today.prl %}
%}
A PERL language environment program accesses the values of a table parameter by their Net.Data name. The column headings for table T are T_N_i, and the field values are T_V_i_j.
REPORT and MESSAGE blocks are permitted as in any FUNCTION section. They are processed by Net.Data and not the language environment. A PERL program can, however, write text to the standard output stream and directly manipulate the output HTML form.
The REXX language environment can interpret inline REXX programs that are specified in a FUNCTION block of the Net.Data macro, or it can execute external REXX programs stored in separate files. Calls to external REXX programs are identified in a FUNCTION block by a statement, for example:
%EXEC{ REXX-program-file-name [optional parameters] %}
The REXX language environment uses the RexxStart() API to tell the REXX interpreter to execute the specified file, then passes the parameters following the file name to the program as if they were entered on the command line. To the REXX program, all of the parameters are received as ARG[1].
Variable substitution is performed only on the executable-statements section of the FUNCTION block. Parameters, however, are made accessible to the REXX program whether the program is defined internally in a FUNCTION block or externally in a separate file. The REXX language environment uses the REXX language processors' RexxVariablePool() function to share Net.Data variables with the REXX program. This allows the REXX program to directly manipulate the Net.Data variables identified in the parameter list.
A REXX program accesses the values of a table parameter as REXX stem variables. To a REXX program, the column headings for table T are T_N.i and the field values are T_V.i.j.
The SQL language environment is used to execute SQL statements through DB2. The results of the SQL statement can be returned in the Net.Data default table or in a table specified by you.
Net.Data supports any SQL statement you authorize. You can connect to one database for each HTML section when invoking Net.Data as a cgi application and must specify the database name with the DATABASE variable (except with OS/390). If your DB2 database is on the same machine as the Web server, no additional setup is required. Otherwise, depending on the platform you use, you can access remote databases by using Client Application Enabler (CAE) or use Database Connection Services (DDCS) to get all the transaction support DB2 supports. You may also be able to use DataJoiner to access other databases. Using DataJoiner lets you use two-phase commit with databases that support it.
For platforms that use a bind file, the initialization file must specify the BIND_FILE variable, which looks like this:
BIND_FILE ./DTWSQL.BND;
The Sybase language environment lets you communicate directly with your Sybase data. Sybase's Open Client CONNECT installed on the server. For details, see:
http://www.sybase.com/products/entcon/opencc.html
The Sybase language environment does not support large objects, such as images and audio. Stored procedures are supported only for procedures without a SELECT statement.
You make calls to the Sybase language environment with functions like this:
%function(DTW_SYB) STL1() {
insert into $(table) (int1,int2) values (111,NULL)
%}
The system language environment supports calls to external programs identified in an EXEC statement in the FUNCTION block.
The language environment interprets the EXEC statement by passing the program name and parameters to the operating system for processing using the C language system() function call. This method does not allow Net.Data variables to be directly passed to or retrieved by the external program, as the REXX language environment does, so the variables are handled this way:
A system language environment program accesses the values of a table parameter by the Net.Data name. The column headings for table T are T_N_i, and the field values are T_V_i_j.