STAX XML 解析

利用stax xml文件可以提交Job给staf执行。下面结合具体实例讲述XML如何编写。

1 STAX基本的Job模板

1: <?xml version="1.0" encoding="UTF-8" standalone="no"?>
2: <!DOCTYPE stax SYSTEM "stax.dtd">
3:
4: <stax>
5:
6: <defaultcall function="main"/>
7:
8: <function name="main">
9: <nop/>
10: </function>
11:

12: </stax>

第一行和第二行一般都是一样的，每一个stax Job以stax标签开头。function 元素是Job中的主要的结构化机制，仅仅能stax根目录进行定义。defaultcall用来定义当Job提交的时候被调用的函数。nop是个空元素，表示什么都不做。

2利用stax启动notepad

1: <?xml version="1.0" encoding="UTF-8" standalone="no"?>
2: <!DOCTYPE stax SYSTEM "stax.dtd">
3:
4: <stax>
5:
6: <defaultcall function="main"/>
7:
8: <function name="main">
9:
10: <process>
11: <location>'local'</location>
12: <command>'notepad'</command>
13: </process>
14:
15: </function>
16:
17: </stax>

process元素：包含两个子元素location和command，其中location用来申明任务执行的机器，可以是本地的机器也可以是远程的机器，如果是远程的机器，必须在staf的配置文件中申明安全等级为5.本地直接用local表示。command为执行的具体命令，两个元素的值都用单引号，表示为Python的字符串。

上述实例是用来打开notepad的job。利用STAF Monitor可以用来提交job以及检测执行。

首先启动STAX检测器：C:\STAF\services\stax>java -jar STAXMon.jar

选择"文件"->"提交新任务"，在出现的界面中选择需要提交的job对应的XML文件，并设置相关job的名称，然后提交即可

3 stafcmd

<stafcmd>
    <location>'local'</location>
    <service>'delay'</service>
    <request>'delay 30000'</request>
</stafcmd>

stafcmd元素可以用来调用staf的service，包含三个子元素，location，service以及request。其中location表示机器，service表示具体的服务名称，request为具体执行的命令。

获取stafcmd命令执行的返回值：
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE stax SYSTEM "stax.dtd">
<stax>
<defaultcall function="main"/>
<function name="main">
<sequence>
<stafcmd>
<location>'local'</location>
<service>'var'</service>
<request>'resolve string {STAF/Config/OS/Name}'</request>
</stafcmd>
<if expr="RC != 0">
<message>'Oops, RC = %s, Result = %s' % (RC, STAFResult)</message>
<else>
<message>'Great! STAF/Config/OS/Name = %s' % (STAFResult)</message>
</else>
</if>
</sequence>
</function>
</stax>

因为function element只能允许包含一个子元素，而在检查stafcmd执行的返回值的时候有个if子元素，因此需要使用sequence 进行wrapper。stafcmd命令执行的返回值可以通过变量RC来进行确认，expr属性用来申明python的表达式。message元素则用来向monitor显示信息。STAFResult用来存储执行结果的具体信息。

成功执行的时候信息显示如下：

20110915-10:09:54    Great! STAF/Config/OS/Name = WinXP                

process也可以去验证执行的返回值，并且可以使用env元素申明环境变量。returnstdout用来申明process 完成时候的标准输出，而stderr则是表示标准错误输出。
<sequence>
<process name="'My Test Process'">
<location>'local'</location>
<command>
'java com.ibm.staf.service.stax.TestProcess 10 3 99'
</command>
<env>
'CLASSPATH=C:/STAF/bin/JSTAF.jar;C:/STAF/services/stax/STAXMon.jar'
</env>
<stderr mode="'stdout'"/>
<returnstdout/>
</process>
<if expr="RC != 0">
<message>'Error: RC=%s, STAXResult=%s' % (RC, STAXResult)</message>
<else>
<message>'Process RC was 0. STAXResult=%s' % STAXResult</message>
</else>
</if>
</sequence>
4 使用参数：

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE stax SYSTEM "stax.dtd">
<stax>
<defaultcall function="main"/>
<function name="main">
<function-prolog>
This function is used as an example in the "Getting Started with STAX"
document. It starts the TestProcess, and allows the parms, machine,
java_command, java_class, processName, and classpath to be passed as
arguments to the
</function-prolog>
<function-map-args>
<function-required-arg name="parms">
The three parameters to pass to the process.
</function-required-arg>
<function-optional-arg name="machine" default="'local'">
The name of machine where the test process should run.
</function-optional-arg>
<function-optional-arg name="java_command" default="'java'">
The name of java executable that should be used to execute the test
process.
</function-optional-arg>
<function-optional-arg name="java_class"
default="'com.ibm.staf.service.stax.TestProcess'">
The name of java class for the test process.
</function-optional-arg>
<function-optional-arg name="processName" default="'My Test Process'">
The name of the process.
</function-optional-arg>
<function-optional-arg name="classpath"
default="'{STAF/Config/STAFRoot}/bin/JSTAF.jar;{STAF/Config/STAFRoot}/services/stax/STAXMon.jar'">
The CLASSPATH that should be used when the test process is started..
</function-optional-arg>
</function-map-args>
<sequence>
<process name="processName">
<location>machine</location>
<command>'%s %s %s' % (java_command, java_class, parms)</command>
<env>'CLASSPATH=%s' % classpath</env>
<stderr mode="'stdout'"/>
<returnstdout/>
</process>
<if expr="RC != 0">
<message>'Error: RC=%s, STAXResult=%s' % (RC, STAXResult)</message>
<else>
<message>'Process RC was 0. STAXResult=%s' % STAXResult</message>
</else>
</if>
</sequence>
</function>

</stax>

function-prolog：函数的说明，相当于注释
function-map-args：表明你可以传递对函数的参数传递一个python map，上面的例子中可以传递6个参数
function-required-arg表示是必须的参数
function-optional-arg.表示可选的参数，如果是可选的，必须声明default的值，如default="'java'"。这两个元素的值是对函数参数的具体说明

可以通过log元素对job的执行添加日志，在message中时候log和level属性，其中level表示日志的级别。如果函数的执行需要返回给调用者，则可以使用return 元素。<return>RC</return>

5 使用import和call

1: <?xml version="1.0" encoding="UTF-8" standalone="no"?>
2: <!DOCTYPE stax SYSTEM "stax.dtd">
3:
4: <stax>
5:
6: <defaultcall function="begin_tests"/>
7:
8: <script>
9: ImportMachine = 'local'
10: ImportDirectory = '{STAF/Config/STAFRoot}/services/stax'
11: </script>
12:
13: <function name="begin_tests">
14:
15: <sequence>
16:
17: <import machine="ImportMachine"
18: file="'%s/FunctionParametersLogging.xml' % ImportDirectory"/>
19:
20: <call function="'main'">{ 'parms' : '9 2 7' }</call>
21:
22: <call function="'main'">{ 'parms' : '2 9 15' }</call>
23:
24: </sequence>
25:
26: </function>
27:
28: </stax>

import可以从其他STAX xml文件中import函数。上面的例子是import 所有的函数，call元素则用来调用，script元素中用来定义变量。上述例子中调用两次。如果想并行运行job，可以使用parallel 元素。
<parallel>
<call function="'main'">{ 'parms' : '40 1 0' }</call>
<call function="'main'">{ 'parms' : '15 2 0' }</call>
<call function="'main'">{ 'parms' : '10 2 0' }</call>
</parallel>

使用循环：
<loop from="1" to="3" var="index">
<block name="'Block #%s' % index">
<call function="'main'">{ 'parms' : '10 %s 0' % index }</call>
</block>
</loop>
在机器执行的时候可以使用loop来控制执行，其中from和to分别表示循环的起始，var表示循环迭代的变量。
在XML中还可以使用testcase元素：
<testcase name="'Test Process'">
<sequence>
<script>r = randint(1, 100)</script>
<call function="'main'">{ 'parms' : '1 1 %s' % r }</call>
<if expr="STAXResult &lt;= 50">
<tcstatus result="'pass'"/>
<else>
<tcstatus result="'fail'"/>
</else>
</if>
</sequence>
</testcase>
使用testcase之后可以嵌入tcstatus来确认执行的结果。