更改开始

DSNUTILV存储过程

使用DSNUTILV存储过程，从 Db2 应用程序运行 Db2 实用程序。 DSNUTILV可以运行最大为2GB的实用程序语句。

当被调用时，DSNUTILV执行以下操作：

  • 将指定给utility-id 和restart参数 的值转换为EBCDIC
  • 为以Unicode编码的实用程序控制语句创建实用程序输入流（SYSIN）
  • 使用DSNUTILB调用 Db2 实用程序
  • 删除当前已创建临时表（ SYSIBM.SYSPRINT ）中的所有行
  • 将实用程序输出流（SYSPRINT）捕获到创建的临时表（ SYSIBM.SYSPRINT ）中
  • 声明一个光标，以便从SYSPRINT中选择：
    DECLARE SYSPRINT CURSOR WITH RETURN FOR
  SELECT SEQNO, TEXT FROM SYSPRINT
  ORDER BY SEQNO;
  • 打开SYSPRINT光标

调用程序随后从返回的结果集中提取行，以获取捕获的实用程序输出。

结果实用程序 SYPRINT 输出中放置在 SYSIBM.SYSPRINT 表中的字符集由 DSNUTILV 存储过程的 BIND PACKAGE 语句确定。 如果指定了编码选项 ENCODING(EBCDIC)，则 SYSPRINT 内容将以 EBCDIC 格式显示。 如果指定了编码选项ENCODING(UNICODE)，则SYSPRINT内容将以Unicode格式显示。 默认安装任务 DSNTIJRT 包含 ENCODING(EBCDIC)。

DSNUTILV的环境

DSNUTILV必须在WLM环境中运行。 WLM核心环境 DSNWLM_UTILS。 DSNWLM_UTILS仅适用于以下 Db2 实用程序存储过程：

  • 更改开始DSNUTILV更改结束
  • DSNUTILU
  • DSNUTILS（已弃用）

如果您打算在此环境中运行其他应用程序，请添加该过程并添加SYSIN的DCB信息，如下例所示：

//SYSIN    DD    UNIT=SYSDA,SPACE=(4000,(20,20),,,ROUND),
//         DCB=(RECFM=V,LRECL=32708)

更多信息，请参阅 Db2-supplied 例程的核心WLM环境。

WLM为DSNUTILV建立的地址空间

启动DSNUTILV运行的WLM建立地址空间的JCL程序需要DSSPRINT、SYSIN和SYSPRINT的DD语句。 SYSIN和SYSPRINT DD语句必须分配工作文件，DSNUTILV可以使用这些文件临时存储实用程序输入语句和实用程序输出消息。 如果您打算运行RUNSTATS并收集发行统计信息，还需要为 RNPRIN01 分配DD语句。

Db2 为DSNWLM_UTILS提供地址空间过程，这是DSNUTILV的核心WLM环境。 该地址空间过程称为DSNWLMU。 有关DSNWLMU的详细信息，请参阅 Db2-supplied 例程的核心WLM环境。

DSNUTILV需要授权

要调用DSNUTILV存储过程，包含CALL语句的程序包或计划的所有者必须在存储过程使用的每个程序包上拥有以下一项或多项权限：

  • DSNUTILV软件包的EXECUTE权限
  • 套餐所有权
  • PACKADM 包裹收集授权
  • DATAACCESS 权限
  • SYSADM 权限

然后，要执行该实用程序，必须使用包含运行指定实用程序授权的权限集。

更改开始如果您使用 RACF 来保护JES资源，则必须定义一个有权访问这些资源的 RACF 组，并将该 RACF 组名称添加到调用DSNUTILV的用户ID的配置文件中。更改结束

传递给DSNUTILV的实用程序控制语句

实用程序控制语句的输入数据集可以由以下Unicode字符开头：

  • 一个Unicode UTF-8 空格 （X'20'）
  • Unicode UTF-8 破折号（ X'2D' ）
  • 大写Unicode UTF-8 "A" 至 "Z" (X'41' 至 X'5A' )

任何需要排序的实用程序必须在实用程序控制语句中包含SORTDEVT关键字。 SORTNUM关键字的使用是可选的。

此外，DSNUTILV不会动态分配数据集。 使用模板实用程序控制语句动态分配数据集。

有关更多信息，请参阅：

DSNUTILV存储过程语法图

下面的语法图显示了将实用程序作为存储过程调用的SQL CALL语句。

阅读语法图跳过可视化语法图CALLDSNUTILV(实用程序ID, restart, 声明, 重编码)

DSNUTILV选项说明

实用程序ID
在 Db2 中为该实用程序指定一个唯一的标识符。

utility-id 是Unicode中VARCHAR(16)类型的输入参数 UTF-8 ，必须可转换为以下允许的EBCDIC字符：

  • A–Z（大写和小写）
  • 0–9
  • #、$、@、¢、！、‸或句号（.）
重启
指定 Db2 是否重新启动当前实用程序，如果是，则指定重新启动实用程序的时机。

restart 是Unicode中VARCHAR(8)类型的输入参数 UTF-8 ，必须可转换为EBCDIC允许的字符。 请为该参数指定以下值之一：

NO 或 null
表示该实用程序是新创建的，而不是重新启动的。 同一实用程序标识符（UID）下不能存在其他实用程序。

默认值为空。

CURRENT
在最后提交点重新启动该实用程序。
PHASE
在当前停止阶段开始时重新启动实用程序。 使用显示实用程序命令确定当前停止的相位。
PREVIEW
在预览模式下执行后续的实用程序控制语句。

在预览模式下， Db2 会分析所有实用程序控制语句是否存在语法错误，但不会执行正常的实用程序。 如果语法正确， Db2 将展开SYSIN中包含的所有LISTDEF列表和TEMPLATE数据集名称表达式，并将结果打印到SYSPRINT数据集中。 Db2 评估并扩展所有LISTDEF语句，生成表空间或索引空间列表。 Db2 还通过变量替换将模板数据集名称表达式转换为数据集名称。 Db2 还扩展了由实用程序调用引用的任何 LISTDEF 库和模板库中的列表和数据集名称表达式。

如果省略了PREVIEW关键字，预览处理将被关闭，但有一个例外。 如果没有指定该关键字，则不会覆盖预览 JCL 参数，该参数如果指定，则在整个作业步骤中保持有效。

此选项与PREVIEW JCL参数相同。

有关更多信息，请参阅：

声明
指定实用程序控制语句。

utstmt 是Unicode UTF-8 中CLOB（ 2G ）类型的输入参数。 UTF-8 如果实用程序声明不是Unicode格式， Db2 会将其转换为 UTF-8。 因此，如果您以其他格式传递实用程序控制语句，请考虑字符转换的可能后果。

您可以为该参数指定一个CLOB文件引用变量。 但是，所引用的数据集必须采用可变记录格式。 例如，假设您希望 DSNUTILV 使用由 UNLOAD 实用程序生成的 LOAD 实用程序语句。 您可以使用文件引用变量将这些语句传递给DSNUTILV。 但是，您必须先将包含这些语句的数据集转换为可变记录格式。 （默认情况下，UNLOAD以固定记录格式创建这些数据集。） 然后，进行其他必要的更改，例如为LOAD数据集添加模板。

限制 ：实用程序控制语句中的任何关键字、名称或常量不能超过32704字节。

由于UNICODE和EBCDIC之间的转换并不总是精确的，因此一些常量（例如表名、索引名、列名和常量值）可能会被错误地转换。 在这种情况下，请使用十六进制常数。 例如，使用X'31'代替字符'1'的UNICODE值。

有关更多信息，请参阅：

重编码
指定实用程序的最高返回代码。

retcode 是INTEGER类型的输出参数。

使用DSNUTILV终止或重启实用程序

如果您不想在故障后重新启动实用程序，请执行以下操作：

  1. 使用TERM UTIL命令终止失败的实用程序。

    当您终止该实用程序时， Db2 会删除该实用程序所需的数据集。

  2. 请通过以下方式之一刷新WLM环境：
    • 提交VARY命令：
      VARY WLM,APPLENV=xxx,REFRESH
    • 调用存储过程 WLM_REFRESH。

如果想在故障后重启实用程序，请执行以下操作：

  1. 运行实用程序时，使用模板实用程序控制语句，并在模板中指定实用程序所需数据集的DISP（NEW、CATLG、CATLG）。
  2. 当实用程序出现故障时，请刷新WLM环境，但不要终止实用程序。
  3. 实用程序完成后，手动删除已分配的数据集。

更多信息，请参阅存储过程WLM_REFRESH。

调用DSNUTILV的示例程序

以下示例程序调用DSNUTILV，包含在 SDSNSAMP 中：

  • 更改开始工作 DSNTEJ6X 编译、链接编辑、绑定并运行示例C语言调用程序 DSN8EDA ，该程序调用存储过程DSNUTILV来执行实用程序。 DSN8EDA 可以传递实用语句或包含实用语句的数据集名称。 更改结束

欲了解更多信息，请发送电子邮件至 DSNTEJ6R。

DSNUTILV输出

Db2 根据DECLARE语句创建结果集，该语句在SYSPRINT中用于声明用于选择的游标示例中显示

成功执行 DSNTEJ6R 示例作业或等效作业的输出将列出指定的参数，然后是 Db2 诊断显示MEPL实用程序生成的消息。

更多信息，请参阅 “诊断 ”。

更改结束