3.1 Oracle Web Agent如何工作

1. 用户从浏览器提交一个URL。

用户以下列方法之一提交URL：

• 通过从HTML页面上选择一个链接

• 在其浏览器的打开URL框中指定一个URL

• 提交HTML表格

此动作触发了一个与URL相关的GET或POST请求方法操作。请求方法使用HTTP协议
传给了Web Listener。

2. Web Listener 启动了 Web Agent.

Web Listener判断此URL是否与Oracle Web Agent有关（通过抽取URL的/owa部
分），并调用Web Agent。为与CGI标准兼容，Web Listener使几个环境变量对
Web Agent有效.

3. Web Agent连接到Oracle7 Server.

为连接到Oracle7 Server，Web Agent要求一些诸如连接到哪个服务器，使用什
么用户名和口令等信息。这些信息作为Web Agent的一部分，存储在位于OWS管理
目录下的文件owa.cfg 中。Web Agent通过解析环境变量SCRIPT_NAME来决定使用
哪个服务，环境变量SCRIPT_NAME是由Web Listener根据CGI 1.1说明书设定的。
Web Listener从URL中/owa 前面的路径段推出这个环境变量的值。例如，如果
/ows-bin/hr/owa是URL的前边部分，那么hr就是要使用的服务。

有关如何设置Web Agent service的进一步的内容, 请见本章后面的"Web Agent
Service"一节.

4. PL/SQL 过程被调用

连接到数据库后，Web Agent调用相应的PL/SQL过程，其名字通过解析环境变量
PATH_INFO获得。

如果PL/SQL过程要求参数，这些参数已经由Web Listener通过环境变量
QUERY_STRING或标准输入（这依赖于请求方法是"GET"还是"POST"）传给了Web
Agent。Web Agent将把这些参数传给PL/SQL过程。

有关PATH_INFO, SCRIPT_NAME,和QUERY_STRING 以及Oracle Web Agent如何使用
他们的内容, 请见本章后面的"Web Agent如何使用CGI环境变量"一节.

5. PL/SQL过程执行， 生成 HTML 文档.

在Developer's Toolkit的帮助下，PL/SQL过程从Oracle7数据库中提取出数据并
在PL/SQL表中生成了HTML文档。

有关Developer's Toolkit的内容请见第四章"Oracle WebServer Developer's Toolkit."

6. Web Agent将生成的HTML文档传给Oracle Web Listener.

如果PL/SQL过程成功结束，Web Agent将从PL/SQL表里取出生成的HTML文档，并
把它发送到标准输出，那里是Web Listener期望CGI应用把他们的输出发送到的
地方。

如果PL/SQL过程返回错误，Web Agent则把程序定义的出错页面发送到标准输出。

有关如何处理错误的内容请见"Oracle Web Agent Error Handling"一节。

7. Web Listener把 HTML文档发送回原发出请求的浏览器

Web Listener使用HTTP将HTML文档发还浏览器。浏览器并不知道请求的文档是
在飞行中生成的，把它象任何其他HTML一样显示在屏幕上。

Web Agent服务 Service

　 公司A想让他们存储在Oracle7数据库中的数据可以被公众通过Oracle Web Listener
访问。然而公司内不同部门对数据库以用户名为分割的不同部分(模式)有访问权限。
所以，人力资源部和财务部使用不同的用户名/口令组合来登录数据库。如果他们都想
用使用Oracle Web Agent的CGI应用访问他们的数据，Web Agent需要使用正确的用户
名/口令来登录数据库。采用这种方案，含有配置信息的owa.cfg文件中包含两个服务，
HR 服务和AP服务。每个服务有相关的用户名/口令，ORACLE_HOME参数，和ORACLE_SID
参数。当一个来自浏览器的请求到来时，Web Listener从URL中抽取出服务名并读取
owa.cfg文件找出将使用的参数。

　 为连接到Oracle7服务器，Web Agent需要在Web Agent服务中指明以下信息：　

• username 用户名

• password 口令

• ORACLE_HOME

• ORACLE_SID (仅对本地数据库)

• SQL*Net V2 Service Name or Connect String (仅对远程数据库)

　　 下面是一个owa.cfg文件中Web Agent服务项的例子，每个参数有相应的解释。
　

　Developer's T#

(
owa_service = es
(
owa_user = www_es
)
(
owa_password = tiger　
)
(
oracle_home = /opt/oracle7
)
(
oracle_sid = esprod
)
(
owa_err_page = /es_err.html
)
(
owa_valid_ports = 8000 8888
)
(
owa_log_dir = /opt/oracle7/ows/log
)
(
owa_nls_lang = AMERICAN_AMERICA.US7ASCII
)
)

　

owa_user

Web Agent连接数据库用的数据库用户名。
　

owa_password

Web Agent连接数据库用的数据库口令。
　

oracle_home

Oracle7代码树在文件系统中的位置。它应该是Web Agent服务连接到的数据库的
ORACLE_HOME，除非Web Agent设置为通过SQL*NET连接到一个远程数据库。这种情况
下，指定Web Agent所在的ORACLE_HOME。Web Agent总是安装在ORACLE_HOME目录或
其子目录下。
　

oracle_sid

将连接到的数据库的系统ID名。连接到远程数据库时，不要使用。

　

owa_err_page

Web Agent调用的PL/SQL过程发生错误时，Web Agent返回的HTML文档的路径。这是个
实际路径，而非Web Listener配置中的那种虚拟路径。

owa_valid_ports
　 Web Agent将服务的有效的Web Listener网络端口。

　

owa_log_dir

Oracle Web Agent写出错文件的目录。出错文件的名字为service_name.err。

owa_nls_lang
　 Web Agent连接的Oracle7数据库的NLS_LANG。若不指定，Web Agent管理程序当服
务执行时寻找数据库的NLS_LANG。
　

Web Agent如何使用CGI环境变量

　 下面是一个典型的URL如何被与CGI 1.1说明书兼容的Web Listener解析的例子。

http://www.nhl.com:8080/ows-bin/nhl/owa/hockey.pass?person=Gretzky

1. 子串 http://www.nhl.com:8080 表明Web浏览器要用HTTP协议连接到www.nhl.com
主机的端口8080上。

2. 当运行在www.nhl.com上的Oracle Web Listener接收到请求，子串/ows-bin/nhl/owa 表明要求Web Listener去执行Web Agent而不是返回一个静态HTML
文件。

3. 调用Web Agent后, Web Listener把/ows-bin/nhl/owa作为环境变量SCRIPT_NAME
传给Web Agent。URL的其他部分以这种方式传给Web Agent：子串/hockey_pass作为
PATH_INFO，子串"person=Gretzky"作为QUERY_STRING，传递给Web Agent。

4. Web Agent从SCRIPT_NAME中解析出服务名nhl.
• 注意：如果Web Agent不能处理传来的服务名, 缺省为owa_default_service.

5. Web Agent解析PATH_INFO来决定hockey_pass为登录Oracle7后调用的PL/SQL过程。
6. Web Agent将在QUERY_STRING变量中传给他的参数传给他调用的PL/SQL过程。

传递参数给PL/SQL

　这些关键概念和要领为：

• 从Web浏览器到Web Agent的参数获取

• 使用HTML表格传递参数

• 参数排序

• 参数缺省值

• 多个HTML表格字段使用同一个名字

• 过程重载

　依赖使用REQUEST_METHOD 的不同, 参数由Web浏览器到Web Listener的传递有两种方法：

• QUERY_STRING　环境变量 -- 如果浏览器使用GET方法，Web Listener用此环 境变量传递参数给Web Agent。

• 标准输入 -- 如果使用POST方法，Web Listener使用标准输入传递参数到Web Agent。

　 建议：可能的情况下，使用POST。GET方法用于链接和非表格URL。对于HTML表格，
可以有个选择。因为GET方法使用操作系统环境变量，QUERY_STRING有长度限制。

使用HTML表格传递参数

　下例模拟前一节，除非它使用HTML表格使用POST REQUEST_METHOD。
　

<FORM METHOD="POST" ACTION="http://www.nhl.com:8080/ows-bin/nhl/owa/hockey.pass">
Please type the name of the person you wish to search for:
<INPUT TYPE="text" NAME="person"><P>
To submit the query, press this button:　
<INPUT TYPE="submit" VALUE="Submit Query">. <P>
</FORM>

注意：HTML输入变量的名字，此处为"person"，必须和与它相匹配的PL/SQL参数完全
相同。
　 上述参数的接收的PL/SQL过程如下：
　

create or replace
procedure hockey_pass (person in varchar2) is
　　 n_assists integer;
begin
　　 select num_assists into n_assists
　　　　　 from hockey_stats
　　 where name=person;
　　 htp.print(person||' has '||to_char(n_assists)||' assists this　　　　　 season');
end;

　总的来说, PL/SQL开发员不需要关心Oracle Web Agent以什么顺序从HTML表格或
通过一个URL接收参数. 它仅在从一个表格字段传递多个值时才有关系。参见本节
后面的"多个HTML表格字段使用相同的名字"。

参数缺省值

　如果PL/SQL开发员不能保证对于特定的PL/SQL过程参数必然有从Web浏览器传来的值
的话，建议给此参数一个缺省值，例如：

create or replace procedure showvals(a in varchar2 DEFAULT NULL,
　　　　　　　　　　　　　　　　　　 b in varchar2 DEFAULT NULL)　
is　
begin　
　　 htp.print('a = '||a||htp.br);
　　 htp.print('b = '||b||htp.br);　
end;

OWS-05111: Agent : no procedure matches this call
　 OWA SERVICE: test_service　
　 PROCEDURE: showvals　
　PARAMETERS:　
　 ===========　
　 B:　
　　 Hello

a = <BR>　

b = Hello<BR>

a =　
b = Hello

有些情形下，人们想。为处理这种想用相同HTML字段即PL/SQL参数传递多个值的情
况，可以用PL/SQL表创建值的数组。

要用相同HTML字段传递多个值的一种情况是HTML表格的"SELECT"标记的使用。如果设
参数SIZE为比1大的值，用户将能从同一个表格字段选择多个值。
　 另一种情况是人在单个表格字段选择一组相应的值：

-- QUERY_FORM prints an HTML page with all the columns for the　　　
-- specified table.　 Invoke the procedure from a Web Browser with
-- a URL like:
http://yourhost:port_num/service_name/owa/query_form?the_table=emp

create or replace procedure query_form(the_table in varchar2) is　　
　　 cursor cols is　
　　 select column_name　　　
　　　　　　 from user_tab_columns　
　　 where table_name = upper(the_table);　
begin
　　 htp.htmlOpen;　
　　 htp.headOpen;　
　　 htp.htitle('Query the '||the_table||' table!');　
　　 htp.headClose;　
　　 htp.bodyOpen;　
　　 -- Use owa_util.get_owa_service path to automatically retrieve　
　　 htp.formOpen(owa_util.get_owa_service_path||'do_query');
　　 -- Put in the table as a hidden field to pass on to do_query　　　
　　 htp.formHidden('the_table', the_table);
　　 -- Put in a dummy value, as we cannot DEFAULT NULL a PL/SQL table.　
htp.formHidden('COLS', 'dummy');　
　　 for crec in cols loop
　　　　　 -- Create a checkbox for each column. The form field name　　　
　　　　　 -- will be COLS and the value will be the given column name.
　　　　　 -- Will need to use a PL/SQL table to retrieve a set of　
　　　　　 -- values like this. Can use the owa_util.ident_arr type　　　　
　　　　　 -- since the columns are identifiers.
　　　　　 htp.formCheckbox('COLS',crec.column_name);　
　　　　　 htp.print(crec.column_name);　
　　　　　 htp.nl;　
　　 end loop;　
　　 -- Pass a NULL field name for the Submit field; that way, a　
　　 -- name/value pair is　 not sent in.　 Wouldn't want to do this　　
　　 -- if there were multiple submit buttons.
　　 htp.formSubmit(NULL, 'Execute Query');　　　　
　　 htp.formClose;　
　　 htp.bodyClose;　
　　 htp.htmlClose;　
end;

　
此例中，用户已经选择了查询EMPNO,ENAME,JOB,和SAL列 :

这里是处理此表格提交的过程：

-- DO_QUERY executes the query on the specified columns and　
-- tables.The OWA_UTIL.IDENT_ARR datatype is defined as:　
--　 -- type ident_arr is table of varchar2(30) index by binary_integer
--

create or replace procedure do_query(the_table in varchar2,

　cols in owa_util.ident_arr) is

　　 column_list varchar2(32000);　
　　 col_counter integer;
　　 ignore　　　　　 boolean;
begin　
-- For PL/SQL tables, have to just loop through until you hit　
-- no_data_found. Start the counter at 2 since we put in　
-- a dummy hidden field.　
　　 col_counter := 2;　
　　 loop　
　　　　　 -- build a comma-delimited list of columns　
　　　　　 column_list := column_list||cols(col_counter)||',';　
　　　　　 col_counter := col_counter + 1;　
　　 end loop;　
exception　
　　 when no_data_found　
　　 then　
　　　　　　 -- strip out the last trailing comma　
　　　　　　 column_list := substr(column_list,1,length(column_list)-1);　
　　　　　　　 -- print the table - assumes HTML table support　
　　　　　　 ignore := owa_util.tablePrint(the_table, 'BORDER',　　　　　　　　　　　　　　　
　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　 OWA_UTIL.HTML_TABLE,
　column_list);　
end;

使用隐藏的站位变量作为第一个值是个好想法，如果你不能保证至少一个值被提交到
PL/SQL表的话。其原因是不能为PL/SQL表设缺省值。并且，调用这个仅一个参数(the_table)的过程将导致Web Agent产生一个错误。

注意：Web Agent只可以传递基本类型为VARCHAR2的参数到PL/SQL表。这有个限制，
PL/SQL类型VARCHAR2作为最大的PL/SQL数据类型，最大长度限制为32767字节。值在
存储过程里被显式地转换到NUMBER, DATE,或LONG。（使用TO_NUMBER或TO_DATE-LONG
不需转换）。
　

过程重载

create or replace package overload is　
　　　　 procedure proc1(charval in varchar2);　
　　　　 procedure proc1(numval　 in number);　
end;　
　
create or replace package body overload is　
　　　　 procedure proc1(charval in varchar2) is　
　　　　 begin　
　　　　　　　 htp.print('The character value is '||charval);　
　　　　 end;　
　
　　　　 procedure proc1(numval　 in number);　
　　　　　　　 htp.print('The number value is '||numval);　
　　　　 end;　
end;

create or replace package overload is　
　　　　 procedure proc1(val in varchar2);　
　　　　 procedure proc1(val in number);　
end;

这个限制受HTML-表格数据类型较少的影响，但不会有明显的限制，PL/SQL类型VARCHAR2作为最大的PL/SQL数据类型，最大长度限制为32767字节。值在存储过程里被
显式地转换到NUMBER, DATE,或LONG。（使用TO_NUMBER或TO_DATE-LONG不需转换）。

存取CGI环境变量

　

Variable　变量	Variable Meaning　变量意义
AUTH_TYPE	Method used to validate user　　 校验用户的类型。
GATEWAY_INTERFACE	The revision of the CGI specification to which the server complies　　 服务器兼容的CGI说明书的版本。
HTTP_USER_AGENT	The browser the client is using to send the request　　 客户端用来发送请求的浏览器。
PATH_INFO	Extra path information given by the client　　 客户端给出的额外的路径信息。
PATH_TRANSLATED	Translated version of PATH_INFO provided by server for mapping. This consists of the document root concatenated to the PATH_INFO.　　 服务器提供的映射用的PATH_INFO的翻译版本。
REMOTE_HOST	Hostname making the request if it can be determined　　 发出请求的主机名，如果它可以判断的话
REMOTE_ADDR	IP address of the remote host making the request　　 发出请求的远程主机IP地址
REMOTE_USER	Used to authenticate user　　 用于鉴别用户
REMOTE_IDENT	Set to the remote username retrieved from the server　　 设置由服务器检索出的远程用户名
SERVER_PROTOCOL	Name and revision of the information protocol used in the request　　 请求使用的信息协议的名称和版本
SERVER_SOFTWARE	Name and version of information server software answering the request　　 回答请求的信息服务器软件的名称和版本。
SERVER_NAME	The server's hostname, or IP address　　 主机名或IP地址
SERVER_PORT	Port number on which the server is running　　 服务器所运行的端口
SCRIPT_NAME	Virtual path to the script being executed, used for self-referencing URL　　 将执行脚本的虚拟路径，用于自引用URL。

表 3 - 2. CGI 环境变量
　 这些环境变量可在PL/SQL里用函数owa_util.get_cgi_env获得。参见,"The Oracle WebServer Developer's Toolkit".