管理与编程指南


调用请求的类型

无论您用何种方式调用 Net.Data,都可以指定两种类型的请求。

宏请求
指定 Net.Data 应执行指定的宏。

直接请求
指定 Net.Data 应执行 SQL 语句、存储过程或函数。

想要编写单个 SQL 查询或调用单个函数(例如 DB2 存储过程、REXX 程序 或 Perl 函数)的 Web 开发者可以向数据库发出直接请求了。直接请求中没有任何需要 Net.Data 宏 的复杂的 Net.Data 应用逻辑,因此可以绕过 Net.Data 宏处理器。为了改进性能,直接请求参数 被传递到适当的语言环境进行处理。

图 18说明了宏请求和直接请求之间 的区别。宏请求总是在请求的 URL 中指定一个宏,还可以使用表单数据。直接请求则不 在 URL 中指定宏文件,但仍然可以使用表单数据。

图 18. 宏请求与直接请求


宏请求与直接请求

调用 Net.Data 的 语法取决于 Net.Data 的配置以及请求的类型。对于宏和直接请求,都是使用 URL 来 调用 Net.Data 的。URL 可以由用户直接输入,也可以作为 HTML 链接或 HTML 表编码到 HTML 页面中。Web 服务器使用 CGI、FastCGI 或其中一个 Web 服务器 API 来调用 Net.Data。

对于宏请求,在 URL 中指定 Net.Data 宏的名称以及要在 Net.Data 宏内部执行 的 HTML 块的名称。对于直接请求,在 URL 中指定 Net.Data 语言环境的名称、SQL 语句或函数的名称、 以及任何附加的必需参数值。您可以使用 Net.Data 定义的语法来指定这些值。

如果正从 CGI 迁移至 APAPI 或 FastCGI, 可能需要注意某些 RESS 语言环境问题。参见REXX 语言环境以获取详情。

以下章节更为详细地描述了这些调用请求:

尽管这些示例指出了使用 CGI 调用 Net.Data 时要使用的语法, 但这些概念适用于所有那些用于调用 Net.Data 的接口。对于各种接口类型所必需的精确语法, 请参考针对该内容的章节。

使用宏(宏请求)调用 Net.Data

客户机浏览器通过发送 URL 格式的请求来调用 Net.Data。本节将告诉您如何通过在 URL 请求中指定一个宏来调用 Net.Data。

发送给 Net.Data 的请求具有以下格式。

http://server/Net.Data_invocation_path/filename/block[?name=val&...]

参数:

server
指定 Web 服务器的名称和路径。如果是本地服务器,则可以忽略服务器名称而使用相关的 URL。

Net.Data_invocation_path
Net.Data 可执行文件、小服务程序类、DLL 或共享程序库的路径和文件名。例如,/cgi-bin/db2www/

filename
指定 Net.Data 宏文件的名称。Net.Data 搜索并试图用 MACRO_PATH 初始化路径变量 中定义的路径语句来与这个文件名匹配。参见MACRO_PATH以获取详情。

block
在引用的 Net.Data 宏中指定 HTML 块的名称。

?name=val&...
指定一个或多个传送给 Net.Data 的可选参数。

您直接在浏览器中指定此 URL。也可以在 HTML 链接中指定它,或使用表单来构建它,如下所示:

参数:

method
指定与表单配合使用的 HTML 方法。

URL
指定用于运行 Net.Data 宏的 URL,其中的参数已经在上面描述过了。

示例

以下示例演示了调用 Net.Data 的不同方式。

示例 1:使用 HTML 链接调用 Net.Data:

<a href="http://server/cgi-bin/db2www/myMacro.dtw/report">
.
.
.
</a>
 

示例 2: 使用表单来调用 Net.Data

<form method="post"
 action="http://server/cgi-bin/db2www/myMacro.dtw/report">
.
.
.
</form>

以下章节描述了 HTML 链接和表单,以及有关如何使用链接和表单来调用 Net.Data 的详情:

HTML 链接

如果要创作一个 Web 页面,可以创建一个 HTML 链接,而这个链接将执行一个 HTML 块。当浏览器前 的用户单击被定义为 HTML 链接的文本或图象时,Net.Data 就将执行宏中的 HTML 块。

要创建一个 HTML 链接,可使用 HTML <a> 标记。确定希望用作指向 Net.Data 宏的超链接 的文本或图形,然后在两端加上 <a> 和 </a> 标记。在 <a> 标记的 HREF 属性中, 指定宏和 HTML 块。

以下示例显示了这样一个链接:当用户在 Web 页面上选择文本 "List all monitors" 时, 这个链接将使得一个 SQL 查询开始执行。

<a href="http://server/netdata-cgi/db2www/listA.d2w/report?hdware=mon">
List all monitors</a>

单击调用称为 listA.dtw 的宏的链接,它有一个名为 "report" 的 HTML 块,如下例所示:

%DEFINE DATABASE="MNS97"
 
 %FUNCTION(DTW_SQL) myQuery(){
SELECT MODNO, COST, DESCRIP FROM EQPTABLE
WHERE TYPE='$(hdware)'
%REPORT{
<h3>Here is the list you requested</h3>
%ROW{
<hr />
$(N1): $(V1), $(N2): $(V2)
<p>$(N3): $(V3)</p>
%}
%}
%}
 
%HTML (Report){
  @myQuery()
%}

查询将返回一个包含型号、成本和 EQPTABLE 表中对每个监控器描述的描述信息的表。SQL 语句中的值 hdware 是从 URL 输入中获得的。有关 ROW 块中所使用的变量的详细描述, 参见 Net.Data Reference

HTML 表单

您可以使用 HTML 表单来动态地定制 Net.Data 宏的执行。这些表允许用户提供输入值, 而这些值将影响宏的执行和 Net.Data 构建的 Web 页面的内容。

以下示例构建在HTML 链接中监控器列表的示例上,它使得浏览器前的用户可以 使用一个简单的 HTML 表单来选择要求显示信息的产品类型。

<h1>Hardware Query Form</h1>
< hr>
<form method="post" action="/cgi-bin/db2www/listA.dtw/report">
<p>What type of hardware do you want to see?</p>
<ul>
<li><input type="radio" name="hdware" value="mon" checked /> Monitors</li>
<li><input type="radio" name="hdware" value="pnt" /> Pointing devices</li>
<li><input type="radio" name="hdware" value="prt" /> Printers</li>
<li><input type="radio" name="hdware" value="scn" /> Scanners</li>
</ul>
 
<input type="submit" value="submit" />
</form>
 

当浏览器前的用户作出了他们的选择并单击“提交”按钮之后,Web 服务器将处理 调用 Net.Data 的 FORM 标记的 ACTION 参数。然后 Net.Data 执行宏 listA.dtw,它具有一个称为 "report" 的 HTML 块,如上所示。

%DEFINE DATABASE="MNS97"
 
 %FUNCTION(DTW_SQL) myQuery(){
SELECT MODNO, COST, DESCRIP FROM EQPTABLE
WHERE TYPE='$(hdware)'
%REPORT{
<h3>Here is the list you requested</h3>
%ROW{
<hr />
$(N1): $(V1), $(N2): $(V2)
<p>$(N3): $(V3)</p>
%}
%}
%}
 
%HTML (Report){
  @myQuery()
%}

在上述示例中,SQL 语句中 hdware 的值是从 HTML 表单输入中获得的。有关 ROW 块中所使用的变量的详细描述, 参见 Net.Data Reference

FILE 输入类型是经过 Net.Data 的特殊处理的一种输入类型。借助此输入类型, 用户可以将文件上载至服务器,以便由服务器上的 Net.Data 或任何其他应用程序进行进一步的处理。

Net.Data 不对已上载的文件执行任何转换,该文件被视为二进制数据。上载的文件存储在由 DTW_UPLOAD_DIR 指定的目录中,并被赋予唯一的名称,此名称是使用下列规则确定的:

语法:

MacroFileName + '.' + FormVarName + '.' + UniqueIdentifier + '.' + FormFileName

MacroFileName
处理请求的宏的名称(表单中调用的宏)。仅使用文件名,不使用整个路径。

FormVarName
用来在表单中标识该文件的变量的名称。

UniqueIdentifier
用来确保唯一性的字符串。

示例:

首先,在 Net.Data 初始化文件中设置 DTW_UPLOAD_DIR:

DTW_UPLOAD_DIR /tmp/uploads

然后构造一个调用宏的表单,并且至少使用一个类型为文件的输入标记。

<form method="post" enctype="multipart/form-data"
      action="/netdatadev/form.dtw/report">
Name:  <input type="text" name="name" /><br />
Zip code:  <input type="text" name="zipno" /><br />
Resume:  <input type="file" name="resume" /><br />
  <input type="submit" />
</form>

如果用户要提交该表单,并指定文件 myresume.txt,则在服务器上生成的文件将具有类似如下的名称:

/tmp/uploads/form.dtw.resume.20010108112341275-6245-021.myresume.txt

不使用宏对 Net.Data 进行调用(直接请求)

本节将告诉您如何使用直接请求来调用 Net.Data。在使用直接请求时, 不要在 URL 中指定宏的名称。相反,可以使用 Net.Data 定义的语法来指定 Net.Data 语言环境、 要执行的 SQL 语句或程序、以及 URL 中所需的任何附加参数值。参见DTW_DIRECT_REQUEST:启用直接请求变量,以学习如何启用和禁用直接请求。

SQL 语句或程序以及其他指定的参数都被直接传递到指定的语言环境进行处理。直接请求可以改进性能,因为 Net.Data 不需要读取和处理宏。SQL、ODBC、Oracle、 Java、 System、Perl 和 REXX 这些 Net.Data 提供的语言环境支持直接请求,您可以使用 URL、HTML 表或链接来调用 Net.Data。

直接请求通过传递 URL 或表单数据的查询字符串中的参数来调用 Net.Data。以下示例说明了可以指定直接请求的上下文。

<a href="http://server/cgi-bin/db2www/?direct_request">any text</a>

其中 direct_request 代表 直接请求的语法。例如,以下 HTML 链接中包含直接请求:

<a href="http://server/cgi-bin/db2www/?LANGENV=DTW_PERL&FUNC=my_perl(hi)">
  any text</a>

直接请求的语法

使用直接请求调用 Net.Data 的语法中可以包含一个对数据库语言环境或非数据库语言环境的调用。

语法

>>-?--+--------------------------------------------------------------+-- ----+-| Database language environment call |-----+->
      |                .-HTML--.                                     |       '-| Non-database language environment call |-'
      '-DTW_DOCUMENT=--+-XML---+---&--+---------------------------+--'
                                      '-STYLESHEET=--filename--&--'
 
>--------------------------------------------------------------><
 
Database language environment call
 
    .-------------------------------.
    V                               |
|------+-------------------------+--+--LANGENV =---------------->
       '-| Form data entry |--&--'
 
                          .-------------------------------.
                          V                               |
>-------dblangenv----&-------+-------------------------+--+----->
                             '-| Form data entry |--&--'
 
>-----+-SQL=--sql_stmt-------------------------------------+---->
      '-FUNC=--stored_proc_name--(--| Parameter list |--)--'
 
      .-------------------------------.
      V                               |
>--------+-------------------------+--+-------------------------|
         '-&--| Form data entry |--'
 
Form data entry
 
|---DATABASE----+-----------------------+--=---VALUE------------|
                +-DB_CASE---------------+
                +-DTW_HTML_TABLE--------+
                +-LOGIN-----------------+
                +-PASSWORD--------------+
                +-RPT_MAX_ROWS----------+
                +-SHOWSQL---------------+
                +-START_ROW_NUM---------+
                '-user_defined_variable-'
 
Parameter list
 
    .-,-------------------------------------------------------------.
    V                                                               |
|-----+-IN--parm_type--+-parm_value--------+---------------------+--+->
      |                '-"--parm_value--"--'                     |
      +-OUT--parm_type--+-parm_name--+---------------------------+
      |                 '-parm_name--'                           |
      '-INOUT--parm_type--+-parm_name--+---+-parm_value--------+-'
                          '-parm_name--'   '-"--parm_value--"--'
 
>---------------------------------------------------------------|
 
Non-database language environment call
 
|---LANGENV=------lang_env----&---FUNC--=--program_name--------->
 
        .-,-----------------------.
        V                         |
>----(-----+-------------------+--+---)-------------------------|
           '-"--parm_value--"--'
 

参数

DTW_DOCUMENT
指定 Net.Data 应作为输出返回的文档类型。 允许的值是 XML 或 HTML。此参数是可选的,若未指定,则假设为 HTML。

DTW_STYLESHEET
指定显示 XML 时,Net.Data 应使用的样式表。 此参数是可选的,且只当 DTW_DOCUMENT=XML 时才有意义。

stylesheet
指定服务器上样式表的文件名。

Database language environment call
向 Net.Data 指定一个调用数据库语言环境的直接请求。

Form data entry
允许您指定 SQL 变量设置或请求简单的 HTML 格式的参数。参见 Net.Data 参考以了解这些变量的详情。

DATABASE
指定 Net.Data 应将 SQL 请求传递到哪个数据库。此参数是必需的。

DB_CASE
指定 SQL 语句的大小写情况(大写或小写)。

DTW_HTML_TABLE
指定 Net.Data 应返回一个 HTML 表还是应返回一个预格式化的文本表。

DTW_DOCUMENT
指定 Net.Data 应将结果显示成 XML 还是 HTML。允许的值 是 XML 或 HTML。未指定此关键字时,HTML 是缺省值。

LOGIN
指定数据库用户标识。

PASSWORD
指定数据库口令。

RPT_MAX_ROWS
指定一个函数应当在它的报告中返回的最大行数。

SHOWSQL
指定 Net.Data 是应当隐藏还是显示要执行的 SQL 语句。

START_ROW_NUM
指定一个函数应该在哪一行开始它的报告。

user_defined_variable
传递给 Net.Data 的变量,并提供必需的信息或实现 Net.Data 的行为。用户定义的变量 是您为应用程序定义的。

VALUE
指定 Net.Data 变量的值。

LANGENV
为 SQL 语句或存储过程调用指定目标语言环境。如果该语言环境 是数据库语言环境,则必须指定数据库名称。

dblangenv
数据库语言环境的名称:
  • DTW_SQL
  • DTW_ODBC
  • DTW_ORA

SQL
表示直接请求指定了在线 SQL 语句的执行。

sql_stmt
指定一个字符串,其中包含任何可以使用动态 SQL 来执行的有效的 SQL 语句。

FUNC
表示直接请求指定了一个存储过程的执行。

stored_proc_name
指定任何有效的 DB2 存储过程名。

parm_type
为 DB2 存储过程指定任何有效的参数类型。

parm_name
指定任何有效的参数名。

parm_value
为 DB2 存储过程指定任何有效的参数值。

IN
指定 Net.Data 应当使用该参数将输入数据传递到存储过程。

INOUT
指定 Net.Data 应当使用该参数将输入数据传递到存储过程并返回来自语言环境的输出数据。

OUT
指定语言环境应当使用该参数返回来自存储过程的输出数据。

非数据库语言环境调用
向 Net.Data 指定一个调用非数据库语言环境的直接请求。

LANGENV
为函数的执行指定目标语言环境。

lang_env
指定非数据库语言环境的名称:
  • DTW_PERL
  • DTW_REXX
  • DTW_SYSTEM

FUNC
表示直接请求指定了一个程序的执行。

program_name
指定程序,其中包含要执行的函数。

parm_value
为函数指定任何有效的参数值。

直接请求示例

以下示例显示了可以在使用直接请求方法时调用 Net.Data 的不同方式。

HTML 链接

以下示例使用直接请求通过链接来调用 Net.Data。

示例 1:一个调用 Perl 语言环境并调用 Net.Data 初始化文件中 EXEC 路径 语句内的 Perl 脚本的链接。

<a href="http://server/cgi-bin/db2www/?LANGENV=DTW_PERL&FUNC=my_perl(hi)">
  any text</a>

示例 2:一个调用 Perl 语言环境的链接,同前例,但它传递的字符串中 具有双引号和空格字符的 URL 编码值。

<a href="http://server/cgi-bin/db2www/?LANGENV=DTW_PERL&FUNC=my_perl
     (%22Hello+World%22)">any text</a>

例 3一个将执行 SQL 查询(使用 SQL 语言环境)的 URL

<a href="http://server/cgi-bin/db2www/?LANGENV=DTW_SQL&DATABASE=CELDIAL
 &SQL=select+*+from+customer">any text</a>

示例 4:一个调用 REXX 语言环境、调用 REXX 程序并将参数传递到程序的 URL

<a href="http://server/cgi-bin/db2www/?LANGENV=DTW_REXX&FUNC=myexec.cmd(parm1,parm2)"
     >any text</a>

示例 5:一个调用存储过程并将参数传递到 SQL 语言环境的 URL

<a href="http://server/cgi-bin/db2www/?LANGENV=DTW_SQL&FUNC=MY_STORED_PROC
   (IN+CHAR(30)+Salaries)&DATABASE=CELDIAL">any text</a>
提示:您必须在 URL 内对某些字符编码,例如空格和双引号。在此例中, 参数值中的双引号字符和空格必须分别编码成 %22 和 + 字符。如果此链接是从宏生成的,可以使用内置函数 DTW_URLESCSEQ 来对 URL 中必须编码的文本进行编码。有关 DTW_URLESCSEQ 函数的详情, 参见 Net.Data 参考中的描述。

HTML 表

以下示例使用直接请求通过表来调用 Net.Data。

示例:一个将执行 SQL 查询(使用 SQL 语言环境)的 HTML 表单, 它还连接到 CELDIAL 数据库并查询一个表

<form method="post"
 action="http://server/cgi-bin/db2www/">
<input type=hidden name="LANGENV" value="dtw_sql" />
<input type=hidden name="database" value="celdial" />
 <input type=hidden name="SQL"
       value="select * from table1 where col1=$(inputname)" />
Enter Customer name:
<input type=text name="inputname" value="john" />
<input type=submit />
</form>


[ 页的顶部 | 上一页 | 下一页 | 目录 | 索引 ]