如何使用 WebSphere MQ FTE Ant 与最佳实践

开始之前

关于本教程

本教程详细地介绍了 IBM WebSphere MQ FTE 所提供的 Ant 功能以及相关命令与任务，并结合具体实例，演示如何基于 Eclipse 平台开发 Ant 脚本以实现更强大的文件传输功能，最后提出开发 FTE Ant 任务脚本的最佳实践。

目标

希望读者通过本教程，能够了解：

WebSphere MQ FTE 中所提供的 Ant 功能；

基于 Eclipse 开发 FTE Ant 任务脚本；

使用 FTE Ant 的最佳实践

先决条件

本教程要求读者了解 WebSphere MQ、WebSphere MQ FTE 以及 Apache Ant 的基本概念、基本功能和基本操作步骤。

前言

IBM WebSphere MQ File Transfer Edition（简称 MQFTE）结合 WebSphere MQ 的消息传输解决方案，提供了受管的文件传输功能，实现了消息传输平台与文件传输平台的完美统一，逐步成为信息传输领域的主流解决方案。MQFTE 的一个重要扩展是与 Apache Ant 的有效集成，通过使用 Ant 脚本，MQFTE 能够利用可解读的脚本语言执行更为复杂的文件传输任务，因此丰富和扩展了 MQFTE 文件传输的集成能力和覆盖面。

WebSphere MQ FTE Ant 功能介绍

Ant 简介

Another Neat Tools (Ant) 是一种基于 java 的 build 工具。理论上来说，它类似于（Unix）C 中的 make ，但又有所不同，Ant 运行时需要 XML 格式的文件不是 Shell 命令文件。通常情况下，用户使用 Ant 来构建 java 程序，包括类库、.jar 文件、.war 文件等等。Ant 脚本是 XML 文件，其中包含许多步骤的任务，例如创建文件夹、调用 java 编译器、传递编译参数等工作。

Ant 是 Apache 软件基金会 JAKARTA 目录中的一个子项目，Ant 是纯 java 语言编写的，所以具有很好的跨平台性，并且 Ant 操作简单，它由一个内置任务和可选任务组成的，运行时只需要一个 XML 文件 ( 构建文件 )。 Ant 通过调用 target 树，就可以执行各种 task。每个 task 实现了特定接口对象。由于 Ant 构建文件是 XML 格式的文件，所以很容易维护和书写，而且结构很清晰。由于 Ant 的跨平台性和操作简单的特点，它很容易集成到一些开发环境中去。关于 Ant 的更详细介绍请参与参考 [1]。

WebSphere MQ FTE Ant 功能概述

MQFTE 的一个重要扩展是与 Apache Ant 的有效集成，基于 MQFTE 平台，用户通过使用 Ant 脚本，利用可解读的脚本语言来执行更为复杂的文件传输任务，通常每个任务的执行都依赖于之前的任务执行情况，这是受管文件传输中非常普遍的需求。基于 Apache Ant 的可扩展性，FTE Ant 扩展了 Ant 的功能，它创建出符合 MQFTE 可解读的消息并提交给 FTE 代理，用于执行复杂的文件传输任务，如图 1 所示。

图 1 FTE Ant 架构

查看原图（大图）

FTE Ant 任务

FTE 提供了如表 1 所示的 Ant 任务，用户可以使用这些任务实现文件传输功能。

表 1：FTE Ant 任务列表

FTE Ant 命令

FTE Ant 功能提供了一个强大的命令 fteant，在 MQFTE 环境下运行 Ant 脚本，执行复杂的文件传输任务。与标准的 Ant 命令不同，fteant 需要实现定义 Ant 脚本文件。Fteant 的重要参数包括如表 2 所示：

表 2：fteant 命令参数

例如命令形式：

fteAnt -f FTECOPYPrePostSamp.xml -DDSTFILE=\tmp\MyFile4.txt -DjobName=myTestjob

表示执行 Ant 任务脚本 FTECOPYPrePostSamp.xml，并设置其中的两个属性 DSTFILE 和 jobName 为特定的属性值。

WebSphere MQ FTE Ant 开发与最佳实践

WMQ FTE Ant 开发环境配置

下文将详细介绍如何使用 MQ FTE 资源管理器开发 Ant 脚本。

打开 MQ 资源管理器，选择“窗口”菜单，选择“首选项”，在左侧列表中选择“WebSphere MQ 资源管理器”，将启动模式修改为“在 Eclipse 工作台中”。

在首选项左侧列表中选择“常规”— >“编辑器”－>“文档关联”，在右侧选择“添加”，如图 2 所示：

图 2 文件关联

在对话框中填入“*.xml”，并选择确定；

在相关联的编辑器中选择“Ant 编辑器”，并选择“缺省值”，并选择“确定”如图 3 所示。

图 3 Ant 编辑器

重新启动 MQ 资源管理器，选择“打开视图”按钮，选择“资源”，选择“确定”。

在首选项左侧列表选择“Ant”— >“运行时”，选择“全局条目”，选择“添加外部 JAR”，如图 4 所示：

图 4 Ant 运行时

浏览至 <MQFTE INSTALL DIRECTORY>/lib 目录，将其下的所有 .jar 文件选中，选中“打开”，其中 <MQFTE INSTALL DIRECTORY> 为 MQFTE 的安装目录。

选择“Ant 主目录”，浏览至 <MQFTE INSTALL DIRECTORY>/ant 目录，选择“确定”。

设置环境变量 FTEAnt_HOME 为 <MQFTE INSTALL DIRECTORY>/ant，FTEAnt_WMQ_HOME 为 <MQ INSTALL DIRECTORY> 变量，其中 <MQ INSTALL DIRECTORY> 为 MQ 的安装目录 。

使用 ftepingagent 命令测试各个代理是否活动，如图 5 所示。

图 5 ftepingagent 命令

FTE Ant 任务样例

下面描述如何使用 FTE Ant 功能来执行文件传输任务。

简单文件传输

使用在上文中配置好的 WMQFTE Ant 开发环境创建项目，并创建 Ant 文件 testsample.xml，在该文件的前端会出现 Ant 文件标识，将如下文件拷贝到 testsample.xml 中：

代码 1：testsample.xml

　<?xml　version='1.0'?>　
　<project　xmlns:fte="antlib:com.ibm.wmqfte.ant.taskdefs"　name="testsample"　
　default="job"　basedir="."　>　
　<target　name="step1"　description="Transfer　file">　
　　　<fte:filecopy　cmdqm="C_QM"　
　　　　src="A1@A1_QM"　dst="A2@A2_QM"　
　　　　outcome="await"　
　　　　jobname="testsample"　
　　　　rcproperty="step1.result">　
　　<fte:metadata>　
　　<fte:entry　name="departId"　value="Demo"　/>　
　　</fte:metadata>　
　　　<fte:filespec　srcfilespec="E:\fileinput\WMQSS_Securing_WMQFTEV70.pdf"　
　　　　dstfile="E:\fileoutput\transfered_file.pdf"　overwrite="true"/>　
　　　</fte:filecopy>　
　　</target>　
　<target　name="job"　depends="step1"　/>　　
　</project>　

其中 project 可以包含一个或多个 target，一个 target 可以依赖于其他的 target。target 中调用 Tasks，例如在上面例子中，名为“step1”的 target 中包含的 Tasks 为 “filecopy”，其中相关参数请参阅参考资料 [6]。

在 testsample 文件上点击右键，选择“运行方式”，选择“Ant 构建”，在 console 视图中显示该 Ant 任务执行结果输出，如图 6 所示：

图 6 文件传输 console 输出

查看原图（大图）

启动 WMQ FTE 图形管理界面，如图 7 所示，有一条与 filecopy 任务相对应的记录出现：

图 7 filecopy 任务记录

查看原图（大图）

多功能文件传输任务

在上述简单文件传输 Ant 任务基础之上，定义具有更多功能特征的 Ant 文件传输任务。下面将实现一个特定的文件传输任务：

1 ．在文件传输之前，Ant 任务调用源文件所在系统的命令“netstat – n”，检查源系统的端口使用情况；

2 ．执行文件传输任务，并在被传输的文件名前面加上文件发送的日期标记；

3 ．在文件落地之后，执行目标文件所在系统的命令“netstat – n”，检查目标系统的端口使用情况；

配置过程如下。

修改源系统与目标系统上代理属性配置文件。打开发送代理与接收代理的属性配置文件 <config_directory>\config\<coordination_QMgr_name>\agents \<agent_name>\agent.properites，添加如下所示属性定义：

　commandPath=C:\\WINDOWS\\system32;　
　maxCommandOutput=204800　
　maxDestinationTransfers=8　
　maxSourceTransfers=8　　

netstat 命令位于“c:\WINDOWS\system32”目录下，保存并关闭该文件。

按照如下模式编写 Ant 文件传输脚本：

代码 2：多功能文件传输脚本

　<?xml　version='1.0'?>　
　<project　xmlns:fte="antlib:com.ibm.wmqfte.ant.taskdefs"　
　name="SimpleTransfer"　default="job"　basedir="."　>　
　<description>　Complex　FTE　file　Transfer　with　datestamp　file　name,　
　　pre　and　post　program　invocations　</description>　
　
　<!--　Target：init。定义一系列全局变量；用　${timestamp}　获取当前日期函数，作为文件名　-->　
　<target　name="init"　description="Set　Global　variables">　
　<tstamp>　
　　<format　property="timestamp"　pattern="yyyyMMdd"　/>　
　</tstamp>　
　<property　name="srcfile"　value="e:\fileinput\File.txt"　/>　
　<property　name="dstfile"　value="e:\${timestamp}_File.txt"　/>　
　<property　name="SNODE"　value="A1@A1_QM"/>　
　<property　name="DNODE"　value="A2@A2_QM"/>　
　<property　name="cmdqm"　value="C_QM"/>　
　<property　name="jobName"　value="Complex　file　transfer"　/>　
　<property　name="departId"　value="IBM　service"　/>　　
　</target>　
　
　<!--Target:step1.　定义任务　filecopy;　定义事先处理任务　fte:presrc;　定义事后处理任务　fte:postdst　-->　
　<target　name="step1"　depends="init"　description="Transfer　file">　
　　　<fte:filecopy　cmdqm="${cmdqm}"　
　　　　src="${SNODE}"　dst="${DNODE}"　
　　　　outcome="await"　
　　　　jobname="${jobName}"　
　　　　rcproperty="step1.result">　
　　<fte:metadata>　　
　　<fte:entry　name="departId"　value="${departId}"　/>　
　　<fte:entry　name="jobName"　value="${jobName}"　/>　
　　</fte:metadata>　
　　　<fte:filespec　srcfilespec="${srcfile}"　dstfile="${dstfile}"　
　overwrite="true"/>　
　　<fte:presrc　command="netstat"　successrc="0">　
　　<fte:arg　value="-n"　/>　
　　</fte:presrc>　
　　<fte:postdst　command="netstat"　successrc="0">　
　　<fte:arg　value="-n"　/>　
　　</fte:postdst>　
　　　</fte:filecopy>　
　　</target>　
　
　<!--Target:check1.　定义文件传输结果判断条件　;　定义输出文件传输结论；-->　
　<target　name="check1"　depends="step1"　description=　
"Check　return　code　and　set　variables">　
　<condition　property="step1-failed">　
　　<not>　
　　<equals　arg1="${step1.result}"　arg2="0"　/>　
　　</not>　
　</condition>　
　<fail　if="step1-failed"　
　message="step1　transfer　failed　MAXRC=${step1.result}.">　
　</fail>　
　<echo　message="The　FTE　transfer　was　successfull!"　/>　
　</target>　
　
　
　<!--Target：job.　定义　job,　确定　target　之间的依赖关系　-->　
　<target　name="job"　depends="init,　step1,check1"　/>　　
　</project>　

右键选择“运行方式”，选择“Ant 构建”，控制台输出如下信息：

　init:　
　step1:　
　[fte:filecopy]　BFGAN0046I:　正在发出要将文件从“A1@A1_QM”复制到“A2@A2_QM”的请求。　
　[fte:filecopy]　BFGAN0048I:　
　　已对复制操作分配传输标识　414d5120435f514d2020202020202020dafb184b20005e03。　
　[fte:filecopy]　BFGAN0050I:　
　　复制操作　414d5120435f514d2020202020202020dafb184b20005e03　成功完成。　
　check1:　
　　　[echo]　The　FTE　transfer　was　successfull!　
　job:　
　BUILD　SUCCESSFUL　
　Total　time:　1　second　

打开 MQFTE 管理控制台传输日志，显示文件传输日志，其中包括事先处理与事后处理的命令信息，如图 8 所示。

图 8 复杂文件传输结果

查看原图（大图）

在“[preSourceCall] c:\WINDOWS\system32\netstat.exe”上右键，并选择属性，即可看到在源系统上的事先处理命令“netstat -n”的执行结果，如图 9 所示。同理也可查看事后处理结果。

图 9 事先处理结果

检查文件输出目录，被传输文件名已经改为 20091207_File.txt。

WMQ FTE Ant 开发调试

Eclipse 平台提供了 Ant 任务脚本的调试工具，通过添加断点，执行任务脚本的跟踪与调试。如图 10 所示，在需要调试的脚本处右键，选择“添加断点”。

图 10 Ant 任务脚本添加断点

在 Ant 编辑界面中右键，选择“调试方式”，选择“Ant 构建”，即可进入 Ant 的脚本调试状态，如图 11 所示。

图 11 Ant 任务脚本调试

查看原图（大图）

FTE Ant 最佳实践

MQ FTE Ant 功能为文件传输领域提供了更大的灵活性，在定义 Ant 任务脚本过程中，经过探索与比较，建议用户采用下面几条最佳实践建议。

使用 init 任务初始化全局属性与变量

使用 init 任务来初始化全局属性与变量，使之后的脚本文件引用全局变量与属性，可以提高脚本修改效率。通常情况下，init 任务放在脚本的最前端，并设置变量缺省值，并使用 tstamp 函数获取脚本执行时间点。在 Ant 脚本编写过程中，建议将 init 任务与具体 Ant 任务结合起来，定义为通用 Ant 任务“模板”，通过更改 init 部分的变量，即可修改整个 Ant 任务定义。例如以下代码所示：

代码 3：定义全局属性与变量

　<target　name="init"　description="Set　Global　variables">　
　<tstamp>　
　　<format　property="timestamp"　pattern="yyyyMMdd"　/>　
　</tstamp>　
　<property　name="srcfile"　value="e:\fileinput\File4.txt"　/>　
　<property　name="dstfile"　value="e:\${timestamp}_File4.txt"　/>　
　<property　name="SNODE"　value="A1@A1_QM"/>　
　<property　name="DNODE"　value="A2@A2_QM"/>　
　<property　name="cmdqm"　value="C_QM"/>　
　<property　name="jobName"　value="Complex　file　transfer"　/>　
　<property　name="departId"　value="IBM　service"　/>　　
　</target>　
　
　<target　name="step1"　depends="init"　description="Transfer　file">　
　　　<fte:filecopy　cmdqm="${cmdqm}"　
　　　　src="${SNODE}"　dst="${DNODE}"　
　　　　outcome="await"　
　　　　jobname="${jobName}"　
　　　　rcproperty="step1.result">　
　　<fte:metadata>　　
　　<fte:entry　name="departId"　value="${departId}"　/>　
　　<fte:entry　name="jobName"　value="${jobName}"　/>　
　　</fte:metadata>　
　　…　…　…　…　

使用“条件”任务

在 Ant 任务脚本中加入对任务执行结果的判断条件，以此作为下一步操作的基础。例如下面代码所示，在 target check1 中，对 step1 的返回结果进行判断，判断该返回值是否为 0。

代码 4：定义“条件”任务

　<condition　property="step1-failed">　
　　<not>　
　　　<equals　arg1="${step1.result}"　arg2="0"　/>　
　</not>　
　　</condition>　

调用“fail”函数

在 Ant 脚本中加入错误处理部分，即调用 Ant 的 fail 函数，例如下面代码所示：

代码 5：定义“fail”函数

　<fail　if="step1-failed"　
　message="step1　transfer　failed　MAXRC=${step1.result}.">　
　　</fail>　

总结

本文介绍了 WebSphere MQ File Transfer Edition 7.0 所提供 Ant 功能，并以此实现了简单、复杂文件传输任务，并描述了 Ant 任务脚本开发的环境配置、跟踪调试与最佳实践，为基于 WMQ FTE 实现大文件传输提供技术参考。