db2batch －基准评测工具命令

从平面文件或标准输入读取 SQL 语句和 XQuery 语句，动态准备并描述这些语句，然后返回答案集。

此工具可以在单分区数据库和多分区数据库中工作。

通过此工具的可选参数，您可以控制要从答案集访存的行数、要发送至输出文件或标准输出的访存行数，以及要返回的性能信息级别。

输出缺省情况为使用标准输出。您可以为结果摘要指定输出文件。

权限

与所要读取的 SQL 语句或 XQuery 语句所需的权限级别相同。

要使用 -o p 选项（用于指定性能信息级别），或者要使用 -o e 选项（用于设置说明方式），您需要 SYSMON 权限。

需要的连接

无。此命令会建立数据库连接。

命令语法

命令参数

-d dbname

SQL 语句和 XQuery 语句所要应用于的数据库的别名。如果未指定此选项，那么会使用 DB2DBDFT 环境变量的值。

-f file_name

包含 SQL 语句和 XQuery 语句的输入文件的名称。缺省情况为标准输入。

通过在注释文本前面添加两个连字符（即，--comment），可以指示注释文本。在两个连字符之后，直到行尾为止的所有文本都被视为注释。以单引号或双引号定界的字符串可以包含两个相邻连字符，并且会被视为字符串常量而非注释。要将注释包括在输出中，请进行如下标记：--#COMMENT comment。

块是要视为一个整体的一组 SQL 语句和 XQuery 语句。缺省情况下，将会同时收集块中所有语句的信息，而不是一次收集一个语句的信息。指示查询块开头的方式如下所示：--#BGBLK。指示查询块结尾的方式如下所示：--#EOBLK。通过在定义块时指定重复计数，可以将查询块包括在重复循环中，如下所示：--#BGBLK repeat_count。只有在该循环的第一次迭代过程中，才会准备该块中的语句。

可以使用 #PARAM 伪指令或参数文件来指定用于块的给定语句和给定迭代的参数值。有关详细信息，请参阅以下有关 -m 选项的部分。

请指定一个或多个控制选项，如下所示：--#SET control option value。有效控制选项如下所示：

ROWS_FETCH

要从答案集访存的行数。有效值为 -1 到 n。缺省值为 -1（访存所有行）。如果使用值 0，那么不会访存任何行，并且不会返回错误消息。

ROWS_OUT

要发送至输出的访存行数。有效值为 -1 到 n。缺省值为 -1（所有访存的行都会发送至输出）。

PERF_DETAIL perf_detail

指定要返回的性能信息级别。有效值为：

0: 不返回任何计时信息或监视快照。
1: 仅返回耗用时间。
2: 返回应用程序的耗用时间和快照。
3: 返回耗用时间，以及数据库管理器、数据库和应用程序的快照。
4: 返回数据库管理器、数据库、应用程序和语句的快照（仅当自动落实为 OFF，并且正在处理单个语句而非语句块时，才会返回语句的快照）。快照不包括散列连接信息。
5: 返回数据库管理器、数据库、应用程序和语句的快照（仅当自动落实为 OFF，并且正在处理单个语句而非语句块时，才会返回语句的快照）。并且，返回缓冲池、表空间和 FCM 的快照（FCM 快照仅在多数据库分区环境中可用）。快照不包括散列连接信息。

缺省值为 1。值 >1 仅在 Db2® V2 和 Db2 数据库服务器上有效，在主机上当前不受支持。

ERROR_STOP

指定发生非严重错误时，db2batch 是否应停止运行。有效值为：

no: 发生非严重错误时继续运行。这是缺省选项。
yes: 发生非严重错误时停止运行。

DELIMITER

一个字符或两个字符的语句结束定界符。缺省值为分号 (;)。

SLEEP

休眠秒数。有效值为 1 到 n。

PAUSE

提示用户继续。

SNAPSHOT snapshot

指定要建立的监视快照。请参阅 -mss 选项，以了解可建立的快照。

TIMESTAMP

生成时间戳记。

TIMING

打印计时信息。有效值为：

ON: 打印计时信息。这是缺省值。
OFF: 不打印计时信息。

-a userid/passwd

指定用于连接至数据库的用户标识和密码。必须包括斜杠 (/)。

-m parameters_file

指定输入文件，其中包含执行语句前要与 SQL 语句参数标记绑定的参数值。缺省情况是不绑定参数。

如果使用了参数文件，那么每一行均指定用于块的给定语句和给定迭代的参数值。如果改用 #PARAM 伪指令，那么可以为每个语句的每个参数提前指定多个值甚至参数范围，在块的每一次迭代过程中，都会从每个参数的指定集合中选择随机值。#PARAM 伪指令与参数文件不能搭配使用。

参数值格式：

     -36.6       'DB2'         X'0AB2'    G'...'   NULL
     12          'batch'       x'32ef'    N'...'   null
     +1.345E-6   'db2 batch'   X'afD4'    g'...'   Null

每个参数的定义都类似于 SQL 常量，并以空格与其他参数分隔。非定界文本表示数字，定界 (') 纯文本表示单字节字符串，以“x”或“X”作为前缀并括在单引号 (') 内的文本表示编码为十六进制数字对的二进制字符串，以“g”、“G”、“n”或“N”为前缀且括在单引号 (') 内的文本表示由双字节字符组成的图形字符串，而“NULL”（不区分大小写）表示空值。要指定 XML 数据，请使用定界 (') 文本，例如 '<last>Brown</last>'。

参数输入文件格式：

行 X 列出要为输入文件中执行的第 X 个 SQL 语句提供的一组参数。如果语句块不重复，那么这对应于输入文件中列出的第 X 个 SQL 语句。空白行表示相应的 SQL 语句没有参数。参数数目及其类型必须与 SQL 语句所期望的参数数目和类型一致。

参数伪指令格式：

 --#PARAM [single | start:end | start:step:end] [...]

每个参数伪指令都指定参数值的一个集合，每次执行该查询时，都会从中选择一个随机值。这些集合由单个参数值和参数值范围组成。要指定参数值范围，请在两个有效参数值之间放置冒号 (:)，空格是可选分隔符。可以在开始值与结束值之间放置第三个参数值，用作步长大小，它会覆盖缺省值。每个参数范围都等同于指定单个值“start”、“start+step”、“start+2*step”、...“start+n*step”，其中，选择的 n 使得“start+n*step”>=“end”，但“start+(n+1)*step”>“end”。虽然参数伪指令可用于指定任何类型的参数（甚至 NULL）的值集，但是只有数字参数值（整数和十进制数）才支持范围。

运行存储过程时，请更新 parameters_file，将哑元值用于 IN 和 OUT 参数。

-t delcol

指定单个字符的列分隔符。指定 -t TAB 表示制表符列定界符，指定 -t SPACE 表示空格列定界符。缺省情况下，如果设置了 -q on 选项，那么会使用空格；如果设置了 -q del 选项，那么会使用逗号。

-r result_file [,summary_file]

指定输出文件，查询结果将会写入其中。缺省情况为标准输出。错误消息会在标准错误中返回。如果指定了可选的 summary_file，那么它会包含摘要表。

-z output_file [,summary_file]

指定输出文件，查询结果以及返回的任何错误消息将会写入其中。缺省情况为标准输出。错误消息还会在标准错误中返回。如果指定了可选的 summary_file，那么它会包含摘要表。此选项从 V9.7 FP1 开始可用。

-c

自动落实每个语句所引起的更改。缺省值为 ON。

-i

指定测量耗用时间间隔。有效值为：

short: 测量运行每个语句所耗用的时间。这是缺省值。
long: 测量运行每个语句所耗用的时间，包括语句之间的额外处理时间。
complete: 测量运行每个语句所耗用的时间，其中，准备时间、执行时间和访存时间分别报告。

-g

指定是按块还是按语句来报告计时。有效值为：

on: 针对整个块建立快照，在摘要表中仅报告块计时。这是缺省值。
off: 建立快照，并针对块中执行的每个语句报告摘要表计时。

-w

指定结果集的最大列宽，允许的范围为 0 到 2 G。除非数据不可截断，否则显示时会截断为此宽度。您可以增大此设置，以消除警告 CLI0002W 并获取更准确的访存时间。缺省最大宽度为 32768 列。

-time

指定是否报告计时信息。有效值为：

on: 报告计时。这是缺省值。
off: 不报告计时。

-cli

嵌入式动态 SQL 方式（先前是 db2batch 的缺省方式）命令不再受支持。此命令仅以 CLI 方式运行。-cli 选项是为向后兼容性而保留。指定此选项（包括可选的 cache-size 自变量）不会导致错误，但在内部予以忽略。

-msw switch

设置每个指定的监视开关的状态。可以指定下列任何选项：uow、statement、table、bufferpool、lock、sort 和 timestamp。特殊开关 all 会设置上述所有开关。对于指定的每个开关，必须选择下列其中一个值：

hold: 开关的状态保持不变。这是缺省值。
on: 开关已开启。
off: 开关已关闭。

-mss snapshot

指定在执行每个语句或块（取决于 -g 选项）之后应建立的监视快照。一次可以建立多个快照，所有快照中的信息在打印前合并成一个大型的表。可能的快照包括：applinfo_all、dbase_applinfo、dcs_applinfo_all、db2、dbase、dbase_all、dcs_dbase、dcs_dbase_all、dbase_remote、dbase_remote_all、agent_id、dbase_appls、appl_all、dcs_appl_all、dcs_appl_handle、dcs_dbase_appls、dbase_appls_remote、appl_remote_all、dbase_tables、appl_locks_agent_id、dbase_locks、dbase_tablespaces、bufferpools_all、dbase_bufferpools 和 dynamic_sql。

特殊快照 all 表示建立所有快照。任何涉及 appl 标识的快照均不受支持，应替换为等同的代理程序标识（应用程序句柄）快照。缺省情况下，不会建立任何监视快照。

-iso

指定隔离级别，用于确定在访问数据时，如何锁定数据并与其他进程隔离。缺省情况下，db2batch 使用 RR 隔离级别。

db2cli.ini 文件中的 TxnIsolation 配置关键字不影响 db2batch。要在隔离级别并非 RR 的情况下运行此命令，必须指定 -iso 参数。

RR: 可重复读（ODBC 可序列化）。这是缺省值。
RS: 读稳定性（ODBC 可重复读）。
CS: 游标稳定性（ODBC 已落实的读）。
UR: 未落实的读（ODBC 未落实的读）。

-car

指定要用于 db2batch 操作的并行访问解决方案。-car 参数需要正确配置的数据库服务器，并且隔离级别参数 -iso 设置为 CS。

CC: 指定在更新或删除数据的过程中，db2batch 操作应将当前已落实的数据版本用于适用的扫描。可以跳过正在插入的行。当生效中的隔离级别为“游标稳定性”或“读稳定性”时，将会应用此选项（对于“读稳定性”，仅跳过未落实的插入），否则予以忽略。适用的扫描包括可以在只读语句及非只读语句的执行过程中执行的只读扫描。
WFO: 指定 db2batch 操作应等待操作结果。对于“游标稳定性”和更高级别的扫描，遇到正在进行更新或删除的数据时，db2batch 将等待落实或回滚。不会跳过正在插入的行。

-o options

控制选项。有效选项如下所示：

f rows_fetch

要从答案集访存的行数。有效值为 -1 到 n。缺省值为 -1（访存所有行）。如果使用值 0，那么不会访存任何行，并且不会返回错误消息。

r rows_out

要发送至输出的访存行数。有效值为 -1 到 n。缺省值为 -1（所有访存的行都会发送至输出）。

p perf_detail

指定要返回的性能信息级别。有效值为：

0: 不返回任何计时信息或监视快照。
1: 仅返回耗用时间。
2: 返回应用程序的耗用时间和快照。
3: 返回耗用时间，以及数据库管理器、数据库和应用程序的快照。
4: 返回数据库管理器、数据库、应用程序和语句的快照（仅当自动落实为 OFF，并且正在处理单个语句而非语句块时，才会返回语句的快照）。
5: 返回数据库管理器、数据库、应用程序和语句的快照（仅当自动落实为 OFF，并且正在处理单个语句而非语句块时，才会返回语句的快照）。并且，返回缓冲池、表空间和 FCM 的快照（FCM 快照仅在多数据库分区环境中可用）。

缺省值为 1。值 >1 仅在 Db2 V2 和 Db2 数据库服务器上有效，在主机上当前不受支持。

o query_optimization_class

设置查询优化类。有效值包括 0、1、2、3、5、7 和 9。缺省值为 -1，这表示使用当前优化类。

e explain_mode

设置运行 db2batch 时采用的说明方式。必须先创建说明表，然后才能使用此选项。有效值为：

no: 仅运行查询（缺省值）。
explain: 仅填充说明表。此选项会填充说明表，并导致建立说明快照。
yes: 填充说明表并运行查询。此选项会填充说明表，并导致建立说明快照。

s error_stop

指定发生非严重错误时，db2batch 是否应停止运行。有效值为：

no: 发生非严重错误时继续运行。这是缺省选项。
yes: 发生非严重错误时停止运行。

-v

详细。在查询处理期间，将信息发送到标准错误。缺省值为 OFF。

-s

摘要表。针对每个查询或查询块提供摘要表，其中包含耗用时间的算术和几何平均值、访存行数以及行输出。

-q

查询输出。有效值为：

off: 输出查询结果和所有关联信息。这是缺省值。
on: 仅以非定界格式输出查询结果。
del: 仅以定界格式输出查询结果。

-l stmt_delimiter

指定终止字符（语句定界符）。定界符可以是 1 个或 2 个字符。缺省值是分号 (;)。

-h | -u | -?

显示帮助信息。指定了此选项时，将会忽略所有其他选项，并且仅显示帮助信息。

示例

以下示例是 db2batch -d crystl -f update.sql 命令的样本输出：

* Timestamp: Thu Feb 02 2006 10:06:13 EST
---------------------------------------------

* SQL Statement Number 1:

create table demo (c1 bigint, c2 double, c3 varchar(8));

* Elapsed Time is:       0.101091 seconds

---------------------------------------------

* SQL Statement Number 2:

insert into demo values (-9223372036854775808, -0.000000000000005, 'demo');

* Elapsed Time is:       0.002926 seconds

---------------------------------------------

* SQL Statement Number 3:

insert into demo values (9223372036854775807, 0.000000000000005, 'demodemo');

* Elapsed Time is:       0.005676 seconds

---------------------------------------------

* SQL Statement Number 4:

select * from demo;

C1                   C2                     C3
-------------------- ---------------------- --------
-9223372036854775808 -5.00000000000000E-015 demo
 9223372036854775807 +5.00000000000000E-015 demodemo

* 2 row(s) fetched, 2 row(s) output.

* Elapsed Time is:       0.001104 seconds

---------------------------------------------

* SQL Statement Number 5:

drop table demo;

* Elapsed Time is:       0.176135 seconds

* Summary Table:

Type      Number      Repetitions Total Time (s) Min Time (s)   Max Time (s)
--------- ----------- ----------- -------------- -------------- -------------- 
Statement           1           1       0.101091       0.101091       0.101091
Statement           2           1       0.002926       0.002926       0.002926
Statement           3           1       0.005676       0.005676       0.005676
Statement           4           1       0.001104       0.001104       0.001104
Statement           5           1       0.176135       0.176135       0.176135

Arithmetic Mean Geometric Mean Row(s) Fetched Row(s) Output
--------------- -------------- -------------- -------------
       0.101091       0.101091              0             0
       0.002926       0.002926              0             0
       0.005676       0.005676              0             0
       0.001104       0.001104              2             2
       0.176135       0.176135              0             0

* Total Entries:              5
* Total Time:                 0.286932 seconds
* Minimum Time:               0.001104 seconds
* Maximum Time:               0.176135 seconds
* Arithmetic Mean Time:       0.057386 seconds
* Geometric Mean Time:        0.012670 seconds
---------------------------------------------
* Timestamp: Thu Feb 02 2006 10:06:13 EST

用法说明

所有 SQL 语句都必须以 --#SET DELIMITER 命令所设置的定界符（缺省值为“;”）终止。此定界符可以是 1 个或 2 个字符。
SQL 语句长度仅受可用内存量及使用的界面限制。语句可以分为多行，但在一行上不能有多个语句。
输入文件的行长度仅受可用内存量限制。
c 会自动发出 CONNECT 和 CONNECT RESET 语句。
对 -i 计时选项指定了 long 时，就会对 PAUSE 和 SLEEP 进行计时。
必须先创建说明表，然后才能使用说明选项。
对于 db2batch，所有命令行选项和输入文件语句都不区分大小写。
db2batch 支持以下数据类型：INTEGER、CHAR、VARCHAR、LONG VARCHAR、FLOAT、SMALLINT、BIGINT、DECIMAL、DATE、TIME、TIMESTAMP、CLOB、GRAPHIC、VARGRAPHIC、LONGVARGRAPHIC、DBCLOB、BLOB 和 XML。
--#SET PERF_DETAIL perf_detail（或 -o p perf_detail）提供了获取监视输出的快捷方法。如果性能详细信息级别大于 1，那么 db2batch 会在内部开启所有监视开关。如果需要更精确地控制监视输出，请使用选项 -msw 和 -mss（或 #SET SNAPSHOT）。
如果同时指定 -r 和 -z 选项，那么会忽略 -r 选项，因为 -z 选项包含 -r 所指定的内容。