ile rpg 紅皮書_在ILE RPG中使用IBM WebSphere MQ消息属性API

旧的路和前进的路

传统上，要与JMS应用程序（例如，在IBM WebSphere Application Server中运行的Web服务）进行通信，则需要使用RFH2标头。 这很麻烦，尤其是在RPG中。 RFH2头包括一组固定的头字段，后跟任意数量的数据结构，每个数据结构包含一个长度字段和一个缓冲区，该缓冲区包含定义属性的XML数据。 生成RFH2标头并不难。 只需将复制文件cmqrfh2g包含到您的数据结构中，并根据需要设置的文件夹数量定义所需的长度和数据对即可（不同文件夹中的属性必须成对发送）。 为了获得更大的自由并消除从固定长度字段中发送额外的空格，您还可以动态构建缓冲区。 真正的麻烦在于尝试读取属性，这需要解析另一个应用程序发送的RFH2标头。 尽管RPG完全能够解析具有任意数量的可变长度字段的可变长度报头，但它更适合固定长度，类似记录的数据。

在RPG（实际上是任何ILE语言）中使用RFH2标头的另一个问题是XML数据必须为Unicode。 RPG在此具有原生支持UTF-16的优势。 但是，除非您仅与其他RPG应用程序打交道，否则您从其他应用程序获得的任何RFH2标头很可能都将使用UTF-8，因为这是Linux，Windows和Java的默认设置。 这意味着您几乎可以肯定必须处理iconv，这总是很痛苦的。

随着WebSphere MQ 7.0的发布，MQ获得了新的API调用，从而大大减少了与消息属性进行交互所需的工作量，并消除了生成或解析RFH2标头的需要。 这些是：

• MQSETMP –设置消息属性
• MQDLTMP –删除消息属性
• MQINQMP –查询消息属性

除了这些API之外，还添加了其他API来帮助使用消息属性API：

• MQCRTMH –创建消息句柄
• MQDLTMH –删除消息句柄
• MQBUFMH –将消息缓冲区转换为消息句柄
• MQMHBUF –将消息句柄转换为消息缓冲区

新消息属性API的关键是消息句柄。 消息句柄（ MQHMSG ）是64位标识符，用于允许应用程序引用消息的属性，类似于使用MQHCONN来引用与队列管理器的连接或使用MQHOBJ来进行连接。请参阅主题或队列。 使用这些新的消息属性API的第一步是创建消息句柄。

dcl-s Hmsg int(20);
dcl-ds MQCMHO Qualified;
    /copy CMQCMHOG
end-ds;

MQCRTMH(HConn : MQCMHO : HMsg : CompletionCode : Reason);

您声明两个变量， HMsg为64位整数和MQCMHO （创建消息句柄选项）结构。 然后，您调用MQCRTMH生成我们的消息句柄。 假设CompletionCode为0 ，您现在有了一个消息句柄，可以使用它使用新的消息属性API。

使用MQSETMP

要查看如何使用MQSETMP设置消息属性，让我们首先看一下MQSETMP的参数：

示例1：来自CMQG的MQSETMP过程定义

DMQSETMP          PR                  EXTPROC('MQSETMP')
D* Connection handle
D HCONN                         10I 0 VALUE
D* Message handle
D HMSG                          20I 0 VALUE
D* Options that control the action of MQSETMP (MQSMPO)
D SETOPT                        20A   
D* Property name (MQCHARV)
D PRNAME                        32A   
D* Property descriptor (MQPD)
D PRPDSC                        24A   
D* Property data type
D TYPE                          10I 0 VALUE
D* Length of the Value area
D VALLEN                        10I 0 VALUE
D* Property value
D VALUE                           *   VALUE
D* Completion code
D CMPCOD                        10I 0
D* Reason code qualifying CompCode
D REASON                        10I 0

在本练习中，可以使用MQSMPO和MQPD的默认值。 有关这些参数的更多信息，请参考WebSphere MQ信息中心 。

让我们定义一些变量以使用MQSETMP ：

dcl-ds PropName Qualified;
    /copy QMCHRVG
end-ds;

dcl-s PropertyName varchar(40);
dcl-s PropertyValue varchar(40);

dcl-ds MQPD Qualified;
    /copy CMQPDG
end-ds;

dcl-ds MQSMPO Qualified;
    /copy CMQSMPOG
end-ds;

在此示例中，我们将定义usr.format属性，以通知接收应用程序该消息是XML数据。 首先，设置属性名称。

PropertyName = 'format';
PropertyValue = 'xml';
PropName.VCHRP = %ADDR(PropertyName : *DATA);
PropName.VCHRL = %LEN(PropertyName);

注意：如果您没有限定属性名称，则默认为“ usr”文件夹。

然后，您只需要调用MQSETMP ，指定所有参数：

MQSETMP(HConn : HMsg : MQSMPO : PropName : MQPD : TYPSTR :
        %LEN(PropertyValue) : %ADDR(PropertyValue : *DATA) :
        CompletionCode : Reason);

至此，您已经创建了一个消息句柄并将usr.format属性设置为xml ，但是什么消息接收到了该属性？ 答案是您尚未在实际消息上实际设置此属性。 您已经完成的所有工作都分配了一个消息句柄，该消息句柄指向WebSphere MQ中包含消息属性的存储区域。 放置消息时，可以告诉WebSphere MQ将那些属性添加到您要放置的消息中。 为此，您唯一要做的就是将消息句柄字段设置为从MQCRTMH获得的消息句柄，并告诉WebSphere MQ您正在使用版本3 MQPMO （以便WebSphere MQ知道已定义消息句柄字段。 ）。

MQPMO.PMVER = PMVER3;
MQPMO.PMOMH = Hmsg;

现在，像往常一样执行MQPUT ，消息属性将添加到消息中。 在幕后，WebSphere MQ将从消息句柄读取属性并为您生成RFH2标头。 您可以使用IBM WebSphere MQ Explorer或WRKMQMQ系统命令轻松地验证一切是否正常。 MQ Explorer是基于Eclipse的图形工具，使您能够从Microsoft®Windows®或Linux®PC浏览和配置所有WebSphere MQ对象和资源。 它包含在MQ服务器安装中，也可以在MS0T SupportPac中单独获得。 要在MQ Explorer中查看，请展开队列管理器，然后单击Queues 。 然后，您可以右键单击队列，然后单击浏览消息 。 在列表中找到要检查的消息，然后右键单击它，然后单击“ 属性” 。 在左窗格中选择“ 命名属性”时 ，可以看到如图1所示的属性。

图1：MQ Explorer

使用MQINQMP

像MQSETMP一样，它使设置消息属性更加容易，还有MQINQMP可以检索特定消息属性的值，甚至可以使用通配符来获取多个属性的值。 示例2中显示了一个原型。

示例2：来自CMQG的MQINQMP过程定义

DMQINQMP          PR                  EXTPROC('MQINQMP')
D* Connection handle
D HCONN                         10I 0 VALUE
D* Message handle
D HMSG                          20I 0 VALUE
D* Options that control the action of MQINQMP (MQIMPO)
D INQOPT                        72A   
D* Property name (MQCHARV)
D PRNAME                        32A   
D* Property descriptor (MQPD)
D PRPDSC                        24A   
D* Property data type
D TYPE                          10I 0
D* Length in bytes of the Value area
D VALLEN                        10I 0 VALUE
D* Property value
D VALUE                           *   VALUE
D* Length of the property value
D DATLEN                        10I 0
D* Completion code
D CMPCOD                        10I 0
D* Reason code qualifying CompCode
D REASON                        10I 0

与MQSETMP的唯一真正区别是，您使用MQIMPO而不是MQSMPO 。

要使用MQINQMP ，首先要像上面那样创建一个消息句柄，并将其传递到MQGMO 。 您唯一需要的其他技巧是告诉WebSphere MQ您希望在消息句柄中而不是在RFH2标头中返回消息属性。

MQGMO.GMVER = GMVER4;
MQGMO.GMMH = Hmsg;

MQGMO.GMOPT += GMPRIH; // return message properties in handle

MQIMPO.IPOPT = IPINQN + // iterate over properties
               IPCTYP + // convert type if necessary
               IPCVAL;  // convert value into native CCSID

PropQuery = 'usr.%';
PropName.VCHRP = %ADDR(PropQuery : *DATA);
PropName.VCHRL = %LEN(PropQuery);

MQIMPO.IPRETNAMCHRP = %ADDR(PropertyName : *DATA);
MQIMPO.IPRETNAMVSBS = PropNameMax;

MQINQMP(HConn : HMsg : MQIMPO : PropName : MQPD : PropertyType :
        PropValueMax : %ADDR(PropertyValue : *DATA) :
        ActPropLength : CompletionCode : Reason);

%LEN(PropertyValue) = ActPropLength;
%LEN(PropertyName) = MQIMPO.IPRETNAMCHRL;

在这里，您使用usr.%的查询来检索usr文件夹中的所有属性。 在调用MQINQMP ， PropertyName包含找到的第一个用户属性的名称，而PropertyValue包含其值。 处理MQINQMP此属性后，可以再次调用MQINQMP来检索与查询匹配的下一个属性。 最终，将没有更多的属性，并且WebSphere MQ将设置完成码1和原因码2471（MQRC_PROPERTY_NOT_AVAILABLE）。

结论

随着WebSphere MQ 7.0中新消息属性功能的出现，现在在ILE应用程序中处理消息属性变得更加容易。 应用程序不再需要解析RFH2标头，处理XML或使用iconv处理字符转换来获取或设置消息属性。 本文介绍了如何在您的应用程序中使用这些新的API。 完整示例可在WebSphere MQ 7.1随附的AMQ3IQM4和AMQ3STM4示例中找到。 这些样本也包含在WebSphere MQ 7.0.1.6和更高版本的修订包中。

翻译自: https://www.ibm.com/developerworks/ibmi/library/i-websphere-mq-messaging/index.html