Net.Data is designed to allow new language and database interfaces to be added in a 'pluggable' fashion. These language environments are accessed as service programs. The name of the service program is configured in the Net.Data initialization file and associated with a language environment name. Each language environment must support a standard set of interfaces defined by Net.Data.
Net.Data for OS/400 supports the following language environments:
The following sections describe the language environments listed above.
The REXX language environment can interpret internal REXX programs which are specified in a FUNCTION block of the Net.Data macro, or it can execute external REXX programs stored in a separate file. Some of the characteristics of the REXX language environments are:
A REXX program will access the values of a Net.Data macro table parameter as REXX stem variables. To a REXX program, the column headings for table T is T_N.i, and the field values are T_V.i.j.
Calls to external REXX programs are identified in a FUNCTION block by a statement of the form:
%EXEC{ REXX-file-name Yoptional parameters" %}
The following is a simple example of a macro (REXXM) with both an internal REXX program and a reference to an external REXX program:
%define a = "3"
%define b = "0"
%function(DTW_REXX) func1(IN inp1, OUT outp1){
%EXEC{ /QSYS.LIB/REXX.LIB/REXXSRC.FILE/TREXX.MBR %}
%}
%function(DTW_REXX) func2(IN inp1, OUT outp1){
outp1 = 2*inp1
%}
%HTML(REPORT){
@func1(a, b)
b=$(b)
@func2(a, b)
b=$(b)
%}
In the example, @func1 results in the REXX program TREXX.MBR being interpreted by the REXX interpreter, and @func2 results in the REXX interpreter interpreting the statement "outp1 = 2*inp1". In both cases, the REXX variable pool is set so that the REXX interpreter can access variables "a" and "b". After @func2 completes, "b" is set to "6" (assuming that the REXX program TREXX.MBR did not modify "a").
This is an example URL that references the macro, assuming that:
http://hostname/cgi-bin/db2www/WWW/macro/REXXM/report
If you chose to not create a Net.Data initialization file, the REXX language environment is enabled by default. However, if you created an initialization file, and you want to use the REXX language environment, the following configuration statement must be in the initialization file:
ENVIRONMENT(DTW_REXX) /QSYS.LIB/QTCP.LIB/QTMHREXX.SRVPGM ( )
The SQL language environment is used to execute SQL statements using DB2. Some of the characteristics of the SQL language environment include:
DTW_SQL_NAMING_MODE = SYSTEM_NAMING
You can also set DTW_SQL_NAMING_MODE to SQL_NAMING, which is the same as the default of SQL naming mode.
When a connection is made to a remote AS/400, the SQL Call Level Interface looks for a *SQLPKG object in library QGPL by the name of QSQCLIPKG. If it exists, it is used, but if it does not exist it is created. This SQL package contains all the rules by which the native SQL is accessed. Therefore, the first connection's attributes set the rules that all subsequent connections must follow. One of these attributes is naming mode. If you set the DTW_SQL_NAMING_MODE to conflict with the naming mode in an existing QGPL/QSQCLIPKG on a remote AS/400, the SQL statement in the Net.Data macro results in an SQLCODE of -5016. To avoid this situation, select a naming mode and stick with it. If the QGPL/QSQCLIPKG object exists that is in conflict with the naming mode you have chosen, delete it and issue the Net.Data request again. A new QGPL/QSQCLIPKG is created with the naming mode option you require.
When the SQL language environment establishes a connection to a remote system, it associates a user ID with the connection. If, on a subsequent Net.Data query, the user ID does not match those associated with the connection, the connection is ended and a new connection to the database is established (this only occurs if transaction scope is SINGLE). So if performance is a concern, Web macro writers should hard code or use the same user ID when issuing SQL statements to a remote database. For local database access, the user ID and password are ignored.
The following is a simple example of a macro (SQLM) that issues a single SQL command:
%define DATABASE="HOSTNAME"
%FUNCTION(DTW_SQL) sql1 (){
select * from custinfo.customer
%}
%HTML(REPORT){
@sql1()
%}
The URL that references the macro is similar to the example URL given for the REXX language environment, except the macro file name REXXM is replaced with SQLM.
If you chose to not create a Net.Data initialization file, the SQL language environment is enabled by default. However, if you created an initialization file, and you want to use the SQL language environment, the following configuration statement must be in the initialization file:
ENVIRONMENT(DTW_SQL) /QSYS.LIB/QTCP.LIB/QTMHSQL.SRVPGM
( IN DATABASE, LOGIN, PASSWORD, TRANSACTION_SCOPE, SHOWSQL, DTW_SET_TOTAL_ROWS,
DB_CASE, OUT DTWTABLE, SQL_CODE, TOTAL_ROWS )
The text of this environment statement must all be on one line in the initialization file. It is shown here divided between multiple lines for readability.
The SQL language environment parameters in the above configuration statement are passed to the language environment and are described below:
%DEFINE DATABASE="HOSTNAME"
%DEFINE{ LOGIN="MYUSERID"
PASSWORD="DB2WWW"
%}
%DEFINE TRANSACTION_SCOPE="SINGLE"
%DEFINE SHOWSQL="YES"
%DEFINE DB_CASE="UPPER"
Query completed with SQL code $(SQL_CODE).
The SYSTEM language environment supports calls to external programs identified in an EXEC statement in the FUNCTION block.
The SYSTEM language environment interprets the EXEC statement by passing the specified program name and parameters to the operating system for execution using the C language system() function call. This method does not allow Net.Data variables to be directly passed or retrieved to the executable statements as the REXX language environment does, so the SYSTEM language environment passes and retrieves variables in the following manner:
A SYSTEM language environment program will access the values of a Net.Data macro table parameter by their Net.Data name. The column headings for table T will be T_N_i, and the field values are T_V_i_j.
The SYSTEM language environment expects the executable to be a command or a program. The QTMHHTP1 user profile must have the proper authority to run the executable, in addition to any resources that the executable uses.
Below is a simple example of a macro (SYSM) that specifies a program as the executable, passing it one Net.Data parameter:
%define var1 = "OriginalValue"
%FUNCTION(DTW_SYSTEM) test(INOUT parm1){
%EXEC{ /QSYS.LIB/PGM.LIB/TSYS0001.PGM %}
%}
%HTML(REPORT){
<PRE>
Value of var1 before function call: $(var1)
@test(var1)
Value of var1 after function call: $(var1)
</PRE>
%}
The URL that references the macro is similar to the example URL given for the REXX language environment, except the macro file name REXXM is replaced with SYSM.
If you chose to not create a Net.Data initialization file, the SYSTEM language environment is enabled by default. However, if you created an initialization file, and you want to use the SYSTEM language environment, the following configuration statement must be in the initialization file:
ENVIRONMENT(DTW_SYSTEM) /QSYS.LIB/QTCP.LIB/QTMHSYS.SRVPGM ( )