WebSphere MQ Workflow 3.4.0 Java Generic API Test / Prototyping Tool

[prev][next][parent][TOC]

TEST TOOL SYNTAX - Introduction

In MQSeries Workflow Version 3.x you can test or prototype each of the MQSeries Workflow JAVA APIs with a tool. To use the tool, you must create files containing test case information. This section describes the syntax for creating test case files that you can use with the tool.
The tool is able to interpret 2 kinds of syntax languages:

  1) JAVA API tool syntax
     - see the follow on chapters

  2) C API tool syntax in conjunction with a property file
     - see MQSeries Workflow C API Test and Prototyping Tool
       (fmctjca1.exe) and chapter Property File of this documentation.
       ==> C API test cases can be reused 

TEST_CASE_BODY:

This is made up of a sequence of method templates and comments. In most cases, you have more than one method template in a testcase file.

The syntax is:

 TEST_CASE_BODY = [ METHOD_TEMPLATE | COMMENT ]+


METHOD_TEMPLATE:

A method template corresponds to a specific API invocation. It is used to define the API that is to be invoked, the parameters that are to be passed, and the expected results.

Each method template has the following syntax:

  ApiClass/InterfaceName.methodName
     HandleKeyWord1             Handle1
     HandleKeyWord2             Handle2
     ...
     ParameterKeyWord1          Parameter1
     ParameterKeyWord2          Parameter2
     ...
     ExpectedParameterKeyWord1  ExpectedParam.1
     ExpectedParameterKeyWord2  ExpectedParam.2
     ...
  End 

COMMENT:

  /* comment line 1

...
comment line n */

HANDLE MANAGEMENT:

Handles are used to identify objects. Using the handle management, you map the external handle representation into an internal format. Table1 shows valid external handle values.

For certain method templates, the parameter value ALL (...ArrayHdl) supports the possibility to apply the method on all queried-objects (or created objects).

Table 1 : Valid user- defined handle values( external representation of objects)
Handle name                            Handle range
-------------------------------------------------------
   activityInstanceHdl                    1-49
   activityInstanceArrayHdl               1-49
   activityInstanceNotificationHdl        1-49
   activityInstanceNotificationArrayHdl   1-49
   agentHdl                               1-49
   blockInstanceMonitorHdl                1-49
   containerElementHdl                    1-49
   containerElementArrayHdl               1-49
   controlConnectorInstanceHdl            1-49
   controlConnectorInstanceArrayHdl       1-49
   dateTimeHdl                            1-49
   dllOptionsHdl                          1-49
   errorHdl                               1-49
   exeOptionsHdl                          1-49
   executionAgentHdl                      1-49
   executionDataHdl                       1-49
   executionServiceHdl                    1-49
   externalOptionsHdl                     1-49
   implementationDataHdl                  1-49
   implementationDataArrayHdl             1-49
   instanceMonitorHdl                     1-49
   itemHdl                                1-49
   itemArrayHdl                           1-49
   optionsHdl                             1-49
   personHdl                              1-49
   pointHdl                               1-49
   pointArrayHdl                          1-49
   processInstanceHdl                     1-49
   processInstanceListHdl                 1-49
   processInstanceListArrayHdl            1-49
   processInstanceMonitorHdl              1-49
   processInstanceNotificationHdl         1-49
   processInstanceNotificationArrayHdl    1-49
   processInstanceArrayHdl                1-49
   processTemplateHdl                     1-49
   processTemplateListHdl                 1-49
   processTemplateListArrayHdl            1-49
   processTemplateArrayHdl                1-49
   programDataHdl                         1-49
   programTemplateHdl                     1-49
   readOnlyContainerHdl                   1-49
   readWriteContainerHdl                  1-49
   stringArrayHdl                         1-49
   symbolLayoutHdl                        1-49
   workItemHdl                            1-49
   workItemArrayHdl                       1-49
   workListHdl                            1-49
   workListArrayHdl                       1-49

   persistentOidHdl                       1-49
   sessionIdHdl                           1-49
   streamHdl                              1-49
   

EXCEPTIONS AND EVALUATION

One of the major advantages of the tool is that you can specify an expected result or a FmcExecption. You can use xpFmcException for API exceptions and xpValue for expected results. If you do not specify values for these, the tool does not check the return values or exception.

If you use the parameter ALL (...ArrayHdl), then xpValue will not be evaluated.


KEYWORD ABBREVIATIONS:

The following are abbreviations of keywords, which are used for defining data in the testcase body. These abreviations are standardized to make the test and modify even if changes need to be made in the future.

  ac...     Actual....
  xp...     Expected...
  ...Hdl    ...Handle
  ...Obj    ...Object...

PARAMETER ABBREVIATIONS:
  i              Handle value of existing object, for example: 1
  n              Handle of an object, which will be created with a
                 constructor, create method or a query method, e.g. 1
  int            int value
  double         double value
  value          string value without blanks, e.g. ADMIN
  "value"        string value with blanks, e.g. "WL of ADMIN"   (beginning of a string)
                 If '"' should be a part of the string then use '""'
  "like_value"   string value with blanks, e.g. "WL of A"
  "dt_value"     date-time string value, for example,  "Thu Feb 18 13:48:10 CET 1999"
  "sc_value"     sort criteria string value, for example "NAME DESC"
  "fi_value"     filter string value, e.g. "NAME = 'Life_Insurance'"
  "hex_value"    hex string value, e.g. "9FA7BB78..."
                   (representing a binary value)
  rc_value       exception value as string, FMC_ERROR_...
  "value1;value2;..." several string values separated by ';'
  "<CL-VALUE>"   string value will be taken from the command line arguments
  "<RT-VALUE>"   string value generated by an API during runtime execution
  fileSpec       e.g. "d:\tc\handle.lst"

LOOPS:

You can define "Loops" within a test case with the following methods: Tool .loopStart, Tool.jumpToLoopStart.

Remark: You cannot use nested loops!

           | ...
           | API 1
       /-->| StartLoop( NoOfLoops )
       |   | API 2
       |   | API 3
       |   | API 4
       \---| JumpToStartLoop
           | API 5
           V ...                   

IF, THEN, ELSE:

You can define "IF-THEN" and "ELSE" statements within a testcase with the following methods:

Tool.if, Tool.then, Tool.else, Tool.endIf.

Between the IF and THEN statement specify one or more APIs expressions as IF expression . If all API expressions are TRUE, then the IF expression is TRUE. An API statement containing "xpFmcException" or "xpValue" parameter is an API expression, when specified between IF and THEN statement. The API expression rule is following:
(acFmcException == xpFmcException) -> true/false,
(acValue== xpValue ) -> true/false .
APIs without "xpFmcException" and "xpValue" are not used for the IF expression.
Between IF and THEN the API result does not contain the +++OK+++ or the +++ERROR+++ statement.

Remark: You cannot use nested IFs!

           | ...
           + If
           |    API                with xpFmcException/xpValue as "API Expression"
           |    [... more APIs ]   with xpFmcException/xpValue as "API Expression"
           |                       If all single "API expressions" are TRUE,
           |                       the "IF expression" will be TRUE
           + Then
           |    [ API ]
           |    [... more APIs ]
           + Else                  else is optional
           |    [ API ]
           |    [... more APIs ]
           + EndIf
           V ...


RUNNING THE TOOL

INVOCATION HELP (Invocation Mode 1):

Usage:
java com.ibm.workflow.api.tool.JGATT <[path]tc fn> <[path]log fn> or
jre -classpath  com.ibm.workflow.api.tool.JGATT <[path]tc fn> <[path]log fn>
or
java com.ibm.workflow.api.tool.JGATT Syntax <FileSpec>

INVOCATION HELP ABBREVIATIONS:

  tc        test case
  log       result
  fn        file name
If no test case file name extension is specified, an extension "dat" is expected.
If no result file name extension is specified, the tool will create an extension "log".

INVOCATION EXAMPLE of the test tool as MQ Workflow client application:

java com.ibm.workflow.api.tool.JGATT d:\testcase\tc01 d:\result\tc01

INVOCATION EXAMPLE to retrieve the Test Tool Syntax:

java com.ibm.workflow.api.tool.JGATT syntax d:\testcase\syntax.txt

RUNNING PARALLEL TOOL APPLICATIONS:
CAUTION :
When you invoke the Test Tool to carry out test cases in parallel, use different parameters to specify the test cases that are to be run under each invocation.

For example:

e.g.   java com.ibm.workflow.api.tool.JGATT tc01a tc01a       (application A)
       java com.ibm.workflow.api.tool.JGATT tc01b tc01b       (application B)

INVOCATION HELP (Invocation Mode 2):
For details enter following:

java com.ibm.workflow.api.tool.JGATT -h

Note: Flags -e and -c in version 3.3.0 or >

RETURN VALUES:
Depending on the error type, the tool returns the following return values:

  Error type            Return value
  ----------------------------------
  no error              0
  usage error           4
  FmcException          8
  Java exception        8
  userDefinedReturnCode int


TEST CASE SKIP STATEMENTS


For common API language (Java, C, etc.) test cases we introduced skip statements. If a MQWF Java API skip statement <NOT_JAVA> occurs within a test case script, then everything will be skipped until a skip-end statement </NOT_JAVA> occurs.

If this tool is running on a OS/390 platform and a skip statement <NOT_390> occurs within a test case script, then everything will be skipped until a skip-end statement </NOT _390> occurs. On every other platform, the same thing happens with the <NOT_WORKSTATION> and </NOT_WORKSTATION> statements.

The following statements will be ignored:
   <NOT_C>
   </NOT_C>
   <NOT_CPP>
   </NOT_CPP>
   <NOT_X>
   </NOT_X>
   <NOT_VB>
   </NOT_VB>
   <NOT_390CICS>
   </NOT_390CICS>