第十一章 发送和接收IBM WebSphere MQ消息

InterSystems IRIS为IBM WebSphere MQ提供了一个接口，可以使用该接口在InterSystems IRIS和IBM WebSphere MQ的消息队列之间交换消息。要使用此接口，必须能够访问IBM WebSphere MQ服务器，并且IBM WebSphere MQ客户端必须与InterSystems IRIS在同一台计算机上运行。

该接口由%Net.MQSend和%Net.MQRecv类组成，这两个类都是%Net.abstractMQ的子类。这些类使用由InterSystems IRIS在所有合适的平台上自动安装的动态链接库。(这是Windows上的MQInterface.dll；其他平台的文件扩展名不同。)。反过来，InterSystems IRIS动态链接库需要IBM WebSphere MQ动态链接库。

该界面仅支持发送和接收文本数据，不支持二进制数据。

使用IBM WebSphere MQ的RIS接口

通常，要使用IBM WebSphere MQ的InterSystems IRIS接口，请执行以下操作：

1. 确保有权访问IBM WebSphereMQv7.x或更高版本。具体而言：

• IBM WebSphere MQ客户端必须与InterSystems IRIS安装在同一台计算机上。请注意，安装程序会根据需要更新PATH环境变量并添加其他系统变量。
• 确保在安装客户端后重新启动计算机，以便InterSystems IRIS能够识别该客户端。
• 客户端必须能够访问IBM WebSphere MQ服务器。
• 将用来访问服务器的用户名必须具有使用队列管理器和计划使用的队列的权限。

2. 创建%Net.MQSend或%Net.MQRecv的新实例，具体取决于要发送还是接收消息。
3. 连接到IBM WebSphere MQ服务器。执行此操作时，您需要提供以下信息：

• 队列管理器的名称。
• 要使用的队列的名称。
• 与该队列通信的通道。可以指定IBM WebSphere MQ服务器的通道名称、传输机制以及IP地址和端口。

如果正在使用IBM WebSphere MQ的身份验证功能，还可以提供名称和密码。

4. 调用%Net.MQSend或%Net.MQRecv的相应方法来发送或接收消息。

注意：要在64位Linux平台上使用IBM Websphere MQ，必须设置LD_LIBRARY_PATH以包括MQ库的位置。因为必须为任何使用MQ接口的InterSystems IRIS进程设置路径，所以如果正在运行后台进程，则必须在启动InterSystems IRIS之前设置该路径，并在运行IRIS终端之前在任何UNIX®终端中设置该路径。

获取错误代码

%Net.MQSend和%Net.MQRecv的方法如果成功则返回1，如果不成功则返回0。在出现错误的情况下，调用%GetLastError()方法，该方法返回IBM WebSphere MQ给出的最后一个原因代码。

创建连接对象

在可以通过IBM WebSphere MQ发送或接收消息之前，必须创建一个Connection对象，该对象可以建立到队列管理器的连接、打开通道和打开队列以供使用。有两种方法可以做到这一点：
- 可以使用%Init方法，该方法接受指定所有所需信息的参数。
- 可以在首次设置指定所有所需信息的属性后使用%Connect方法。

使用%Init()方法

要使用%Init()方法创建连接对象，请执行以下操作：

1. 创建%Net.MQSend(如果要发送消息)或%Net.MQRecv(如果要接收消息)的实例。本主题将此实例称为连接对象。

注意：如果收到 <DYNAMIC LIBRARY LOAD>错误，则表示缺少动态链接库，并且messages.log文件(在系统管理器的目录中)有更多详细信息。

2. 如果需要身份验证，请设置Connection对象的以下属性：

• 用户名-指定有权使用此频道的用户名。
• 密码-指定给定用户的密码。

3. 调用Connection对象的%Init()方法。此方法按顺序接受以下参数。

a. 指定队列名称的字符串；这应该是指定队列管理器的有效队列。

b. 指定队列管理器的字符串；它应该是IBM WebSphere MQ服务器上的有效队列管理器。

如果省略此参数，系统将使用IBM WebSphere MQ中配置的默认队列管理器。或者，如果IBM WebSphere MQ已配置为队列管理器由队列名称确定，则系统将使用适合给定队列名称的队列管理器。

c. 指定频道规范的字符串，格式如下：

"channel_name/transport/host_name(port)"

这里，channel_name是要使用的通道的名称，Transport是通道使用的传输，host_name是运行IBM WebSphere MQ服务器的服务器名称(或IP地址)，port是该通道应该使用的端口。

传输可以是以下之一：TCP、LU62、NETBIOS、SPX

例如：

"CHAN_1/TCP/rodan(1401)"

"CHAN_1/TCP/127.0.0.1(1401)"

如果省略此参数，系统将使用IBM WebSphere MQ中配置的默认通道规范。或者，如果系统已配置为通道由队列名称确定，则系统使用适合给定队列名称的通道。

d. 一个可选字符串，它指定要向其中写入错误消息的日志文件。默认情况下，不进行日志记录。

4. 检查%Init()方法返回的值。如果该方法返回1，则表明连接已成功建立，可以使用Connection对象发送或接收消息(具体取决于使用的类)。

使用%Connect()方法

在某些情况下，可能更喜欢单独指定连接的所有详细信息。为此，请使用%Connect()方法，如下所示：

1. 创建%Net.MQSend(如果要发送消息)或%Net.MQRecv(如果要接收消息)的实例。如前所述，本主题将此实例称为连接对象。

注意：如果收到<DYNAMIC LIBRARY LOAD> 错误，则表示缺少动态链接库，并且messages.log文件(在系统管理器的目录中)有更多详细信息。

2. 设置Connection对象的以下属性：

• QName-(必选)指定队列名称；这应该是指定队列管理器的有效队列。
• QMgr-指定要使用的队列管理器；它应该是IBM WebSphere MQ服务器上的有效队列管理器。

如果省略此参数，系统将使用IBM WebSphere MQ中配置的默认队列管理器。或者，如果IBM WebSphere MQ已配置为队列管理器由队列名称确定，则系统将使用适合给定队列名称的队列管理器。

3. 或者，通过设置Connection对象的以下属性来指定要使用的频道：

• Connection - 指定IBM WebSphere MQ服务器的主机和端口。例如："127.0.0.1:1401"。
• Channel - 指定要使用的频道的名称。这必须是IBM WebSphere MQ服务器上的有效通道。
• Transport - 指定通道使用的传输。此属性可以是以下之一： "TCP", "LU62", "NETBIOS", "SPX"

如果省略这些参数，系统将使用IBM WebSphere MQ中配置的默认通道规范。或者，如果系统已配置为通道由队列名称确定，则系统使用适合给定队列名称的通道。

4. 如果频道需要身份验证，请设置Connection对象的以下属性：

• 用户名-指定有权使用此频道的用户名。
• 密码-指定给定用户的密码。

5. 调用Connection对象的%ErrLog()方法。此方法接受一个参数，即要用于此连接对象的日志文件的名称。
6. 检查%ErrLog()方法返回的值。
7. 调用Connection对象的%Connect()方法。
8. 检查%Connect()方法返回的值。如果该方法返回1，则表明连接已成功建立，可以使用Connection对象发送或接收消息(具体取决于您使用的类)。

指定字符集(CCSID)

要设置用于消息转换的字符集，请调用Connection对象的%SetCharSet()方法。指定在IBM WebSphere MQ中使用的整数编码字符集ID(CCSID)。

• 如果正在发送消息，这应该是这些消息的字符集。如果不指定字符集，则MQ系统假定消息使用为MQ客户端指定的默认字符集。
• 如果要检索邮件，则这是要将这些邮件翻译为的字符集。

要获取当前正在使用的CCSID，请调用%charset()方法。此方法通过引用返回CCSID，并返回1或0以指示是否成功.

指定其他消息选项

要指定消息描述符选项，可以选择设置连接对象的以下属性：
- ApplIdentityData指定应用程序标识消息描述符选项。
- PutApplType指定PUT Application Type消息描述符选项。

发送消息

要发送邮件，请执行以下操作：

1. 按照“创建连接对象”中的说明创建连接对象。在这种情况下，请创建%Net.MQSend的实例。Connection对象有一个消息队列，可以向该队列发送消息。
2. 根据需要调用以下方法：

• %put()-给定一个字符串，此方法将该字符串写入消息队列。
• %PutStream()-给定初始化的文件字符流，此方法将该字符串写入消息队列。请注意，必须设置流的Filename属性才能对其进行初始化。不支持二进制流。
• %SetMsgId()-给定一个字符串，此方法使用该字符串作为发送的下一条消息的消息ID。

3. 检查调用的方法返回的值。
4. 检索完消息后，调用Connection对象的%Close()方法以释放动态链接库的句柄。

示例1：SendString()

下面的类方法使用队列管理器QM_antigua和名为 S_antigua的队列通道向队列mqtest发送一条简单的字符串消息。通道使用TCP传输，IBM WebSphere MQ服务器运行在名为Antigua的机器上，并侦听端口1401。

///Method returns reason code from IBM WebSphere MQ
ClassMethod SendString() As %Integer
{
 Set send=##class(%Net.MQSend).%New()
 Set queue="mqtest"
 Set qm="QM_antigua"
 Set chan="S_antigua/TCP/antigua(1414)"
 Set logfile="c:\mq-send-log.txt"

 Set check=send.%Init(queue,qm,chan,logfile)
 If 'check  Quit send.%GetLastError()

 //send a unique message
 Set check=send.%Put("This is a test message "_$h)

 If 'check  Quit send.%GetLastError()
 Quit check
}

示例2：SendCharacterStream()

下面的类方法发送文件字符流的内容。它使用的队列与上一个示例中使用的队列相同：

///Method returns reason code from IBM WebSphere MQ
ClassMethod SendCharacterStream() As %Integer
{
 Set send=##class(%Net.MQSend).%New()
 Set queue="mqtest"
 Set qm="QM_antigua"
 Set chan="S_antigua/TCP/antigua(1414)"
 Set logfile="c:\mq-send-log.txt"

 Set check=send.%Init(queue,qm,chan,logfile)
 If 'check  Quit send.%GetLastError()

 //initialize the stream and tell it what file to use
 Set longmsg=##class(%FileCharacterStream).%New()
 Set longmsg.Filename="c:\input-sample.txt"

 Set check=send.%PutStream(longmsg)

 If 'check  Quit send.%GetLastError()
 Quit check
}

示例3：从终端发送消息

以下示例显示了向IBM WebSphere MQ队列发送消息的终端会话。这只能在配置了IBM WebSphere MQ客户端的计算机上运行。

Set MySendQ = ##class(%Net.MQSend).%New()

Do MySendQ.%Init("Q_1", "QM_1","QC_1/TCP/127.0.0.1(1401)","C:\mq.log")

Do MySendQ.%Put("Hello from tester")

Set MyRecvQ =##class(%Net.MQRecv).%New()

Do MyRecvQ.%Init("Q_1", "QM_1","QC_1","C:\mq.log")

Do MyRecvQ.%Get(.msg, 10000)

Write msg,!