WebSphere MQ Workflow 3.4 Generic C API Test / Prototyping Tool

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

TEST TOOL SYNTAX - Introduction



In MQ Workflow Version 3 you can test or prototype each of the MQ Workflow C 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.


TEST _ CASE _ BODY :

This is made up of a sequence of function templates and comments. In most cases, you have more than one function template in a test case file.
The syntax is :
 TEST_CASE_BODY = [ FUNCTION_TEMPLATE | COMMENT ]+



FUNCTION_TEMPLATE:

A function 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 function template has the following syntax:
C-API-FunctionName
  HandleKeyWord1             Handle1
  HandleKeyWord2             Handle2
  ...
  ParameterKeyWord1          Parameter1
  ParameterKeyWord2          Parameter2
  ...
  ExpectedParameterKeyWord1  ExpectedParam.1
  ExpectedParameterKeyWord2  ExpectedParam.2
  ...
End


COMMENT:

Comments must not appear within a method template.
  /* 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 function templates, the parameter value ALL (... VectorHdl) supports the possibility to apply the functionon all queried- objects( or created objects) .

Table 1 : Valid user-defined handle values (external representation)
   Handle name                            Handle range
-------------------------------------------------------
   ActivityInstanceHdl                    1-49
   ActivityInstanceVectorHdl              1-49
   ActivityInstanceNotificationHdl        1-49
   ActivityInstanceNotificationVectorHdl  1-49
   BlockInstanceMonitorHdl                1-49
   ContainerElementHdl                    1-49
   ContainerElementVectorHdl              1-49
   ControlConnectorInstanceHdl            1-49
   ControlConnectorInstanceVectorHdl      1-49
   DateTimeHdl                            1-49
   DllOptionsHdl                          1-49
   ErrorHdl                               1-49
   ExecutionDataHdl                       1-49
   ExecutionServiceHdl                    1-49
   ExeOptionsHdl                          1-49
   ExternalOptionsHdl                     1-49
   ImplementationDataHdl                  1-49
   ImplementationDataVectorHdl            1-49
   InstanceMonitorHdl                     1-49
   ItemHdl                                1-49
   ItemVectorHdl                          1-49
   PersonHdl                              1-49
   PointHdl                               1-49
   PointVectorHdl                         1-49
   ProcessInstanceHdl                     1-49
   ProcessInstanceListHdl                 1-49
   ProcessInstanceListVectorHdl           1-49
   ProcessInstanceMonitorHdl              1-49
   ProcessInstanceNotificationHdl         1-49
   ProcessInstanceNotificationVectorHdl   1-49
   ProcessInstanceVectorHdl               1-49
   ProcessTemplateHdl                     1-49
   ProcessTemplateListHdl                 1-49
   ProcessTemplateListVectorHdl           1-49
   ProcessTemplateVectorHdl               1-49
   ProgramDataHdl                         1-49
   ProgramTemplateHdl                     1-49
   ReadOnlyContainerHdl                   1-49
   ReadWriteContainerHdl                  1-49
   ResultHdl                              1-49
   StringVectorHdl                        1-49
   SymbolLayoutHandle                     1-49
   WorkitemHdl                            1-49
   WorkitemVectorHdl                      1-49
   WorklistHdl                            1-49
   WorklistVectorHdl                      1-49

   CorrelId(Hdl)                          1-49
   PersistentOidHdl                       1-49
   SessionIdHdl                           1-49
   StreamHdl                              1-49


RETURN CODES AND EVALUATION

One of the major advantages of the tool is that you can specify an expected result or API return code. You can use XpRc for API return codes and XpValue for expected results. If you do not specify values for these, the tool does not check the return values.

If you use the parameter ALL (...VectorHdl), then XpValue will not be evaluated.


KEYWORD ABBREVIATIONS:

The following are abbreviations of keywords, which are used for defining data in the test case 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...
  ...Rc     ...Return Code
  ...Hdl    ...Handle
  ...Obj... ...Object...



PARAMETER ABBREVIATIONS:
  i              Handle value of existing object, for example: 1
  i+             Handle value of existing object. The result will be appended
                 to the existing object.
  n              Handle of an object, which will be
                 created with "...Allocate", e.g. 1
  int            int value
  short          short value
  long           long value
  unsigned long  unsigned long value
  double         double value
  value          string value without blanks, e.g. ADMIN
  "value"        string value with blanks, e.g. "WL of ADMIN"
                        If '"' should be a part of the string then use '""'
  "dt_value"     date-time string value, for example,  "04-16-1998 08:32:59PM"
  "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)
  "value1;value2;..." several string values separated by ';'
  "<CL-VALUE>"   string value will be taken from the command line arguments
  FileSpec       e.g. d:\tc\handle.lst
  NULL           Reference of a NULL pointer



LOOPS

You can define "Loops" within a test case with the following methods: TestTool_LoopStart, TestTool_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 test case with the following methods: TestTool_If, TestTool_Then, TestTool_Else, TestTool_EndIf.
Between the IF and THEN statement specify one or more API expressions as IF expression. If all API expressions are TRUE, then the IF expression is TRUE. An API statement containing "XpRc" or "XpValue" parameter is an API expression, when specified between IF and THEN statement. The API expression rule is following:
(AcRc == XpRc) -> true/false,
(AcValue == XpValue) -> true/false.
APIs without "XpRc" 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 can not use nested IFs!
           | ...
           + If
           |    API                with XpRc/XpValue as "API Expression"
           |    [... more APIs ]   with XpRc/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 ...


DLL VERSIONS OF MQ Workflow C API TEST TOOL
DLL name:        fmctjca0.dll / libfmctjca0.a  (with version 3 signature)
Entry point:     CApiTestToolDll
1st argument:    Parameter string (same as EXE)
Behaviour:       Same as EXE version of MQ Workflow C API Test Tool 


DLL name:        fmctjca2.dll / libfmctjca2.a  (with version 2 signature)
Entry point:     CApiTestToolDll
1st argument:    ProgramID
2nd argument:    Parameter string (same as EXE)
Behaviour:       Same as EXE version of MQ Workflow C API Test Tool
Remark:          1st argument is generated and passed from PEA 


RUNNING THE TOOL



INVOCATION HELP (Invocation Mode 1) :

Usage:  fmctjca1 <[path]tc fn> <[path]log fn>
or
Usage:  fmctjca1 <[path]tc fn> NoOutput
or
Usage:  fmctjca1 Syntax <FileSpec>
or
Usage:  fmctjca1 ApiRCs <FileSpec>
or
Usage:  fmctjca1 ToolRCs <FileSpec>


INVOCATION HELP ABBREVIATIONS:
  tc        test case
  fn        file name
  log       result 

The following statements do not affect OS/390:
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:
  fmctjca1 d:\testcase\tc01.dat d:\result\tc01.log

INVOCATION EXAMPLE of the test tool as MQ Workflow activity implementation (FDL):
   ...
   PROGRAM 'FMCTJCA0_tc02' ( 'PersonInfo', 'PersonInfo' )
      DESCRIPTION           'Activity implementation as DLL - MQ Workflow C API Test Tool'
      OS2 PATH_AND_FILENAME 'd:\fmc\dll\FMCTJCA0.DLL'
      OS2 ENTRY_POINT       'CApiTestToolDll'
      OS2 PARAMETER         'd:\testcase\tc02.dat d:\result\tc02.log'
   END 'FMCTJCA0_tc02'
   ...

INVOCATION EXAMPLE to retrieve the Test Tool Syntax:
  fmctjca1 syntax d:\testcase\syntax.txt

RUNNING PARALLEL TOOL APPLICATIONS:
CAUTION :
When invoking the Test Tool for executing testcases in parallel, use different parameters to specify the testcases that are to be run under each invocation.

Forexample :
  fmctjca1 tc01a tc01a       (application A)
  fmctjca1 tc01b tc01b       (application B)



INVOCATION HELP (Invocation Mode 2):
For details enter the following :
fmctjca1 -h



PARALLEL ACTIVITY IMPLEMENTATIONS AS DLL:

The Dll-Version of the MQ Workflow C API Test Tool contains global data. It is built with "DATA MULTIPLE NONSHARED" .The behavior of the DLL is different when running the DLL in FENCED mode, compared to UNFENCED mode.

FENCED mode: The program execution agent (PEA) starts a separate process for each invocation of a DLL entry point a separate process. This process executes a MQ Workflow stub, which only calls the DLL entry point.

UNFENCED mode: One program execution agent (PEA) process invokes the DLL multiple times.

In MQ Workflow Version 3.1, the fenced/unfenced mode can be controlled via an FDL keyword when the program is defined.

When running the obove mentioned DLL in an UNFENCED mode the DATA MULTIPLE NONSHARED has no effect, due the the fact that calling process is always the same. In this case multiple invocations are NOT ALLOWED.

When running the above mentioned DLL in FENCED mode the DATA MULTIPLE NONSHARED is effective, due to the fact that calling process is always a sepparate one. In this case multiple invocations are allowed.


RETURN VALUES:

The tool returns, depending on the error type, following return values:
  Error type          Return value
  --------------------------------
  no error                       0
  usage error                    4
  error                          8
  severe error                  12
  user defined return code     int


TEST CASE SKIP STATEMENTS


For common API language (Java, C, etc.) test cases, skip statements were introduced. If an MQWF C API skip statement <NOT_C> occurs within a test case script, then everything will be skipped until a skip-end statement </NOT_C> 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.

Inside CICS you can use also the <NOT_390CICS> flag to skip APIs that will be called in OS/390 native and on LAN platforms. The corresponding end skip statement is: </NOT_390CICS>.

On every other platform, the same thing happens with the <NOT_WORKSTATION> and </NOT_WORKSTATION> statements.

The following statements will be ignored:

  <NOT_CPP>
  </NOT_CPP>
  <NOT_JAVA>
  </NOT_JAVA>
  <NOT_X>
  </NOT_X>
  <NOT_VB>
  </NOT_VB>



TEST CASE RESTRICTIONS


This tool can not run test case files (xxx.dat) with UNIX format on OS/2 and Windows platforms (CRLF is supported, but LF alone is not allowed).