[IBM i]

IBM i 上的 MQIMPO (查询消息属性选项)

MQIMPO 结构允许应用程序指定用于控制如何查询消息属性的选项。

概述

用途: 此结构是 MQINQMP 调用上的输入参数。

字符集和编码:MQIMPO 中的数据必须是应用程序的字符集以及应用程序的编码 (ENNAT)。

字段

MQIMPO 结构包含以下字段; 这些字段按 字母顺序进行描述:

IPOPT (10 位有符号整数)

以下选项控制 MQINQMP 的操作。 您可以指定其中一个或多个选项。 要指定多个选项，请将值一起添加 (请勿多次添加同一常量) ，或者使用按位 OR 运算来组合值 (如果编程语言支持位运算)。 将记录无效选项的组合; 所有其他组合都有效。

值数据选项: 从消息中检索属性时，以下选项与值数据的处理相关。
国际化学品安全方案
此选项请求将属性值转换为符合在 MQINQMP 调用返回 Value 区域中的属性值之前指定的 IPREQCSI 和 IPREQENC 值。
  • 如果转换成功，那么 IPRETCSI 和 IPRETENC 字段将设置为与从 MQINQMP 调用返回时的 IPREQCSI 和 IPREQENC 相同。
  • 如果转换失败，但 MQINQMP 调用在未发生错误的情况下完成，那么将返回未转换的属性值。

    如果该属性是字符串，那么 IPRETCSI 和 IPRETENC 字段将设置为未转换字符串的字符集和编码。

    在此情况下，完成代码为 CCWARN ，原因码为 RC2466。 属性游标将高级至返回的属性。
如果属性值在转换期间扩展，并且超过 Value 参数的大小，那么将返回未转换的值，完成代码为 CCFAIL; 原因码设置为 RC2469。

MQINQMP 调用的 DataLength 参数返回属性值将转换为的长度，以便允许应用程序确定容纳转换后的属性值所需的缓冲区大小。 属性光标未更改。

此选项还请求:
  • 如果属性名称包含通配符，并且
  • IPRETNAMECHRP 字段使用返回的名称的地址或偏移量进行初始化。
那么返回的名称将转换为符合 IPREQCSI 和 IPREQENC 值。
  • 如果转换成功，那么 IPRETNAMECHRP 的 VSCCSID 字段和返回的名称的编码将设置为输入值 IPREQCSI 和 IPREQENC。
  • 如果转换失败，但 MQINQMP 调用在没有错误或警告的情况下完成，那么返回的名称将未转换。 在这种情况下，完成代码为 CCWARN ，原因码为 RC2492。

    属性游标将高级至返回的属性。 如果未转换值和名称，那么将返回 RC2466 。

如果返回的名称在转换期间扩展，并且超出 RequestedName的 VSBufsize 字段的大小，那么返回的字符串将保持未转换状态，完成代码为 CCFAIL ，原因码设置为 RC2465。

MQCHARV 结构的 VSLength 字段返回属性值将转换为的长度，以允许应用程序确定容纳转换后的属性值所需的缓冲区大小。 属性光标未更改。

国际化学品安全方案
此选项请求将属性值从其当前数据类型转换为 MQINQMP 调用的 Type 参数上指定的数据类型。
  • 如果转换成功，那么 Type 参数在返回 MQINQMP 调用时保持不变。
  • 如果转换失败，但 MQINQMP 调用在未发生错误的情况下完成，那么调用将失败，原因为 RC2470。 属性光标未更改。

如果转换数据类型导致值在转换期间扩展，并且转换后的值超过 Value 参数的大小，那么将返回未转换的值，完成代码为 CCFAIL ，原因码设置为 RC2469。

MQINQMP 调用的 DataLength 参数返回属性值将转换为的长度，以便允许应用程序确定容纳转换后的属性值所需的缓冲区大小。 属性光标未更改。

如果 MQINQMP 调用的 Type 参数值无效，那么调用将失败，原因为 RC2473。

如果不支持所请求的数据类型转换，那么调用将失败，原因为 RC2470。 支持以下数据类型转换:
表 1. 支持的数据类型转换
属性数据类型 受支持的目标数据类型
提货单 TYPSTR ， TYPI8， TYPI16， TYPI32和 TYPI64
类型 (TYPBST) TYPSTR
TYPI8 TYPSTR ， TYPI16， TYPI32和 TYPI64
TYPI16 TYPSTR ， TYPI32和 TYPI64
TYPI32 TYPSTR 和 TYPI64
TYPI64 TYPSTR
TYPF32 TYPSTR ， TYPF64
TYPF64 TYPSTR
TYPSTR TYPBOL ， TYPI8， TYPI16， TYPI32， TYPI64， TYPF32和 TYPF64
TYPNUL None
用于管理受支持转换的一般规则如下：
  • 可以将数字属性值从一种数据类型转换为另一种数据类型，前提是在转换期间不会丢失任何数据。

    例如，数据类型为 TYPI32 的属性的值可以转换为数据类型为 TYPI64的值，但不能转换为数据类型为 TYPI16的值。

  • 可以将任何数据类型的属性值转换为字符串。
  • 可以将字符串属性值转换为任何其他数据类型，前提是已针对转换正确格式化了该字符串。 如果应用程序尝试转换未正确格式化的字符串属性值，那么 IBM® MQ 将返回原因码 RC2472。
  • 如果应用程序尝试进行不受支持的转换，那么 IBM MQ 会返回原因码 RC2470。
将属性值从一种数据类型转换为另一种数据类型的具体规则如下:
  • 将 TYPBOL 属性值转换为字符串时，值 TRUE 将转换为字符串 "TRUE" ，而值 false 将转换为字符串 "FALSE"。
  • 将 TYPBOL 属性值转换为数字数据类型时，值 TRUE 将转换为 1 ，而值 FALSE 将转换为零。
  • 将字符串属性值转换为 TYPBOL 值时，会将字符串 "TRUE" 或 "1" 转换为 TRUE ，并将字符串 "FALSE" 或 "$TAG2" 转换为 FALSE。

    请注意，术语 "TRUE" 和 "FALSE" 不区分大小写。

    无法转换任何其他字符串; IBM MQ 返回原因码 RC2472。

  • 将字符串属性值转换为数据类型为 TYPI8， TYPI16， TYPI32 或 TYPI64的值时，该字符串必须具有以下格式:
    [blanks][sign]digits
    该字符串各个组成部分的含义如下：
    blanks
    可选前导空白字符
    sign
    可选的加号 (+) 或减号 (-) 字符。
    digits
    连续的数字字符序列 (0-9)。 必须至少存在一个数字字符。

    在数字字符序列之后，该字符串可包含其他非数字字符，但是在到达这些字符中的第一个字符后会立即停止转换。 假设该字符串表示十进制整数。

    如果字符串的格式不正确， IBM MQ 将返回原因码 RC2472 。

  • 将字符串属性值转换为数据类型为 TYPF32 或 TYPF64的值时，该字符串必须具有以下格式:
    [blanks][sign]digits[.digits][e_char[e_sign]e_digits]
    该字符串各个组成部分的含义如下：
    blanks
    可选前导空白字符
    sign
    可选的加号 (+) 或减号 (-) 字符。
    digits
    连续的数字字符序列 (0-9)。 必须至少存在一个数字字符。
    e_char
    一个指数字符，即 "E" 或 "e"。
    e_sign
    指数的可选加号 (+) 或减号 (-) 字符。
    e_digits
    该指数的连续数字字符序列 (0-9)。 如果该字符串包含指数字符，那么必须至少存在一个数字字符。

    在数字字符序列或表示指数的可选字符之后，该字符串可包含其他非数字字符，但是在到达这些字符中的第一个字符后会立即停止转换。 假设该字符串表示十进制浮点数，指数幂为 10。

    如果字符串的格式不正确， IBM MQ 将返回原因码 RC2472 。

  • 将数字属性值转换为字符串时，该值将转换为该值作为十进制数字的字符串表示，而不是包含该值的 ASCII 字符的字符串。 例如，整数 65 转换为字符串 "65" ，而不是字符串 "A"。
  • 将字节字符串属性值转换为字符串时，每个字节将转换为表示字节的两个十六进制字符。 例如，字节数组{0xF1, 0x12, 0x00, 0xFF}被转换为字符串"F11200FF"。
IPQLEN
查询属性值的类型和长度。 在 MQINQMP 调用的 DataLength 参数中返回长度。 未返回属性值。

如果指定了 ReturnedName 缓冲区，那么将使用属性名称的长度填充 MQCHARV 结构的 VSLength 字段。 未返回属性名称。

迭代选项: 以下选项与使用带有通配符的名称对属性进行迭代相关
IPINQF
查询与指定名称匹配的第一个属性。 在此调用之后，将在返回的属性上建立游标。

这是缺省值。

随后可以将 IPINQC 选项与 MQINQMP 调用配合使用 (如果需要) ，以再次查询同一属性。

请注意，只有一个属性游标; 因此，如果 MQINQMP 调用中指定的属性名更改，那么将重置游标。

对于以下任一选项，此选项无效:
  • IPINQN
  • IPINQC
IPINQN
查询与指定名称匹配的下一个属性，然后从属性光标继续搜索。 光标将前进到返回的属性。

如果这是针对指定名称的第一个 MQINQMP 调用，那么将返回与指定名称匹配的第一个属性。

随后可以将 IPINQC 选项与 MQINQMP 调用配合使用 (如果需要) ，以再次查询同一属性。

如果已删除游标下的属性，那么 MQINQMP 将返回已删除的属性之后的下一个匹配属性。

如果添加了与通配符匹配的属性，那么在迭代进行期间，该属性可能在迭代完成期间返回，也可能不会返回。 使用 IPINQF 重新启动迭代后，将返回此属性。

当迭代正在进行时，与已删除的通配符匹配的属性在其删除后不会返回。

对于以下任一选项，此选项无效:
  • IPINQF
  • IPINQC
IPINQC
检索属性光标指向的属性值。 属性光标指向的属性是上次使用 IPINQF 或 IPINQN 选项查询的属性。

如果复用了消息句柄，在 MQGET 调用的 MQGMO 的 MsgHandle 字段中指定了消息句柄，或者在 MQPUT 调用的 MQPMO 结构的 OriginalMsgHandle 或 NewMsgHandle 字段中指定了消息句柄，那么将重置属性游标。

如果在尚未建立属性游标时使用此选项，或者如果已删除属性游标所指向的属性，那么调用将失败，完成代码为 CCFAIL ，原因为 RC2471。

对于以下任一选项，此选项无效:
  • IPINQF
  • IPINQN
如果不需要先前描述的任何选项，那么可以使用以下选项:
IPNONE
使用此值来指示未指定任何其他选项；所有选项均采用其缺省值。

IPNONE 帮助程序文档; 不打算将此选项与任何其他选项一起使用，但由于其值为零，因此无法检测到此类使用。

这始终是一个输入字段。 此字段的初始值为 IPINQF。

IPREQCSI (10 位带符号整数)

要将查询的属性值转换为的字符集 (如果该值是字符串)。 这也是指定 IPCVAL 或 IPCTYP 时要将 ReturnedName 转换为的字符集。

此字段的初始值为 CSAPL。

IPREQENC (10 位有符号整数)

这是指定 IPCVAL 或 IPCTYP 时要将查询的属性值转换为的编码。

此字段的初始值为 ENNAT。

IPRE1 (10 位有符号整数)

这是保留字段。 此字段的初始值为空白字符。

IPRETCSI (10 位有符号整数)

在输出时，这是 MQINQMP 调用的 Type 参数为 TYPSTR 时返回的值的字符集。

如果指定了 IPCVAL 选项并且转换成功，那么返回时 ReturnedCCSID 字段的值与传入的值相同。

此字段的初始值为零。

IPRETENC (10 位有符号整数)

在输出时，这是返回的值的编码。

如果指定了 IPCVAL 选项并且转换成功，那么返回时 ReturnedEncoding 字段的值与传入的值相同。

此字段的初始值为 ENNAT。

IPRETNAMCHRP (10 位有符号整数)

查询的属性的实际名称。

在输入时，可以使用 MQCHARV 结构的 VSPtr 或 VSOffset 字段来传递字符串缓冲区。 字符串缓冲区的长度是使用 MQCHARV 结构的 VSBufsize 字段指定的。

从 MQINQMP 调用返回时，将使用查询的属性的名称来完成字符串缓冲区，前提是字符串缓冲区的长度足以完全包含该名称。 MQCHARV 结构的 VSLength 字段中填充了属性名称的长度。 MQCHARV 结构的 VSCCSID 字段将填充以指示返回的名称的字符集，无论该名称的转换是否失败。

这是输入/输出字段。 此字段的初始值为 MQCHARV_DEFAULT。

IPSID (10 位带符号整数)
这是结构标识。 该值必须为:
IPSIDV
查询消息属性选项结构的标识。

这始终是一个输入字段。 此字段的初始值为 IPSIDV。

IPTYP (10 位有符号整数)

属性的数据类型的字符串表示。

如果在 MQRFH2 头中指定了属性，并且无法识别 MQRFH2 dt 属性，那么可以使用此字段来确定属性的数据类型。 TypeString 以编码字符集 1208 (UTF-8) 返回，并且是无法识别的属性 dt 属性值的前 8 个字节

这始终是输出字段。 此字段的初始值是 C 编程语言中的空字符串，以及其他编程语言中的 8 空白字符。

IPVER (10 位带符号整数)
这是结构版本号。 该值必须为:
IPVER1
查询消息属性选项结构的版本号。
以下常量指定当前版本的版本号:
IPVERC
当前版本的查询消息属性选项结构。

这始终是一个输入字段。 此字段的初始值为 IPVER1。

初始值

表 2. MQIPMO 中的字段
字段名称 常量的名称 常量值
IPSID IPSIDV 'IMPO'
IPVER IPVER1 1
IPOPT IPINQF  
IPREQENC ENNAT  
IPREQCSI CSAPL  
IPRETENC ENNAT  
IPRETCSI 0  
IPRE1 0  
IPRETNAMCHRP    
IPTYP   空白

RPG 声明

D* MQIMPO Structure
D*
D*
D* Structure identifier
D IPSID         1   4  INZ('IMPO')
D*
D* Structure version number
D IPVER         5   8I 0 INZ(1)
D*
** Options that control the action of
D* MQINQMP
D IPOPT         9   12I 0 INZ(0)
D*
D* Requested encoding of Value
D IPREQENC       13   16I 0 INZ(273)
D*
** Requested character set identifier
D* of Value
D IPREQCSI       17   20I 0 INZ(-3)
D*
D* Returned encoding of Value
D IPRETENC       21   24I 0 INZ(273)
D*
** Returned character set identifier of
D* Value
D IPRETCSI       25   28I 0 INZ(0)
D*
D* Reserved
D IPRE1         29   32I 0 INZ(0)
D*
D* Returned property name
D* Address of variable length string
D IPRETNAMCHRP     33   48*  INZ(*NULL)
D* Offset of variable length string
D IPRETNAMCHRO     49   52I 0 INZ(0)
D* Size of buffer
D IPRETNAMVSBS     53   56I 0 INZ(-1)
D* Length of variable length string
D IPRETNAMCHRL     57   60I 0 INZ(0)
D* CCSID of variable length string
D IPRETNAMCHRC     61   64I 0 INZ(-3)
D*
D* Property data type as a string
D IPTYP         65   72  INZ