Testing webMethods EntireX and WebSphere MQ Queues

Event Replicator for Adabas provides two utilities you can use to test your EntireX and WebSphere MQ queues.

  • The ADAMTR (Message Test Receive) utility can be used to receive one or more messages from an webMethods EntireX or WebSphere MQ queue, and, optionally, print the messages read from that queue.

  • The ADAMTS (Message Test Send) utility can be used to send requests to the Event Replicator Server without having (or prior to writing) a target application.

This document covers the following topics:

Using the ADAMTR (Message Test Receive) Utility

The ADAMTR (Message Test Receive) utility can be used to receive one or more messages from an webMethods EntireX or WebSphere MQ queue and, optionally, print the messages read from that queue. This utility allows you to read and print messages sent to a queue by:

The ADAMTR utility issues messages for any errors it encounters. For more information, read ADAMTR Messages.

This section covers the following topics:

Syntax

The overall syntax of the ADAMTR utility is:

graphics/adamtr.png

The webMethods EntireX and WebSphere MQ parameters you can specify in ADAMTR are described in the following sections:

Note:
Do not mix webMethods EntireX parameters and WebSphere MQ parameters in the same ADAMTR run.

webMethods EntireX ADAMTR Parameters

The parameters that can be used for the ADAMTR utility when testing an webMethods EntireX queue are shown in the following syntax. Note that all but the MTYPE and ETBSCONV parameter are required.

graphics/adamtr_exx.png

Note:
Do not specify any of the parameters associated with WebSphere MQ in the same ADAMTR utility run.

WebSphere MQ ADAMTR Parameters

The parameters that can be used for the ADAMTR utility when testing a WebSphere MQ queue are shown in the following syntax. Note that all parameters are required.

graphics/adamtr_mq.png

Note:
Do not specify any of the parameters associated with webMethods EntireX in the same ADAMTR utility run.

Parameters

Parameters for the ADAMTR utility vary, depending on the kind of queue you are using. Each input parameter line to DDKARTE should begin with ADAMTR and is structured in the same manner as other Adabas utilities. All of the parameters that can be specified in the ADAMTR utility are now described.

MTYPE

This required parameter identifies the type of queue (webMethods EntireX or WebSphere MQ) that will be read by ADAMTR. Valid values are "ETBROKER" or "MQSERIES". The default for MTYPE is "ETBROKER".

ETBBROKERID

Use this parameter to specify the webMethods EntireX Broker ID to use for the ADAMTR run. This parameter is required when MTYPE=ETBROKER and should not be specified otherwise.

Broker IDs come in two formats: one for TCP/IP communications and one for Adabas SVC communications. For TCP/IP communications, the format is: 

ip-address:port-number:TCP

In this case, the ip-address setting is the TCP/IP IP address and the port-number setting should match the webMethods EntireX PORT parameter.

For Adabas SVC communications, the format is: 

'broker-id:SVCnnn:NET'

In this case, the broker-id setting should match the webMethods EntireX BROKER-ID parameter in the Broker ETBFILE DD. The nnn setting should match either the webMethods EntireX ADASVC or ADA5SVC parameters in the Broker PARMS DD statement.

ETBBROKERNAME

Use this parameter to specify the name of the EntireX Broker stub program to use for the ADAMTR run. This parameter can only be specified when MTYPE=ETBROKER. When not specified, this parameter defaults to "BROKER".

Notes:

  1. EntireX Broker is a component of webMethods EntireX.
ETBSERVICE

Use this parameter to specify the webMethods EntireX service that should be used for the ADAMTR run. This should be the same as the value specified for the SERVICE parameter in webMethods EntireX. This parameter is required when MTYPE=ETBROKER and should not be specified otherwise.

ETBSERVICENAME

Use this parameter to specify the webMethods EntireX service name that should be used for the ADAMTR run. This should be the same as the value specified for the SERVER parameter in webMethods EntireX. This parameter is required when MTYPE=ETBROKER and should not be specified otherwise.

ETBSERVICECLASS

Use this parameter to specify the webMethods EntireX service class that should be used for the ADAMTR run. This should be the same as the value specified for the CLASS parameter in webMethods EntireX. This parameter is required when MTYPE=ETBROKER and should not be specified otherwise.

ETBSCONV

Use this parameter to specify the webMethods EntireX queue is to run using single conversation mode. This parameter is optional when MTYPE=ETBROKER.

ETBTOKEN

Use this parameter to specify the webMethods EntireX queue is to run using single conversation mode. This parameter is optional when ETBSCONV=YES. When not specified, this parameter defaults to "ADAMTR".

ETBUSERID

Use this parameter to specify the webMethods EntireX queue is to run using single conversation mode. This parameter is optional when ETBSCONV=YES. When not specified, this parameter defaults to REPTOR-<node>-----<jobname>.

IQBUFLEN

Use this parameter to specify the length (in bytes) of the input buffer that will be allocated and used by the ADAMTR utility. The default for IQBUFLEN is 32,767 bytes. The minimum value is 2048 bytes and will be used if any lower value is entered for the IQBUFLEN parameter.

The theoretical maximum value that can be specified for this parameter is 2,147,483,647 bytes. In practice, however, the maximum value for IQBUFLEN specification is limited by the region size available to ADAMTR.

The value of the IQBUFLEN parameter should be set to a value at least as large as the largest expected message. For example, when reading messages written by an Event Replicator Server, a user may want to set IQBUFLEN to a value greater than or equal to the value set for the Event Replicator Server parameter MAXOUTPUTSIZE. If a message is read that is larger than the value specified for IQBUFLEN, the message will be truncated prior to its receipt by ADAMTR.

The suffix "K" may be used to denote that the value is in kilobytes (e.g. 1K = 1024 bytes, 4K = 4096 bytes, etc.).

MQQMGRNAME

Use this parameter to specify the WebSphere MQ queue manager name that should be used for the ADAMTR run. This parameter is required when MTYPE=MQSERIES and should not be specified otherwise.

MQQNAME

Use this parameter to specify the WebSphere MQ queue name that should be used for the ADAMTR run. This parameter is required when MTYPE=MQSERIES and should not be specified otherwise.

MSGLIMIT

Use this parameter to specify the number of messages processed by this ADAMTR utility run. Valid values range from zero (0) through 2,147,483,647. A value of zero indicates that there is no size limit for the number of messages processed by the utility. The utility will terminate when it has read and optionally printed the number of messages specified for MSGLIMIT. The default is zero.

Note:
When a Broker queue is read by the ADAMTR utility, the utility must read input messaging transactions in the same manner the transactions were written to the queue. That is, assuming the sending program sends three messages and then commits the messaging transaction, ADAMTR will read the three messages and then commit the input messaging transaction. The value for MSGLIMIT is only checked by ADAMTR after committing an input messaging transaction. In the previously described transaction, if MSGLIMIT=1 or MSGLIMIT=2 is specified, ADAMTR will only terminate after reading and optionally printing the three messages.

PAGESIZE

Use this parameter to specify the number of lines to print prior to printing a new output page. The default value is 55 lines. The minimum value is 10 lines. If a value less than 10 is specified, the default value of 55 will be used.

PRINT

Use this parameter to indicate whether or not the ADAMTR utility should print each message it reads from the messaging system. Valid values are "YES" or "NO". The default is "YES". When PRINT=YES is specified, ADAMTR will print each message read from the messaging system. When PRINT=NO is specified, ADAMTR will not print the contents of each message. Use PRINT=YES when you want to see the content of each message; use PRINT=NO when you want to read messages from a queue but do not care or want to see the contents of each message.

Running the Utility

The JCL and input parameters for the ADAMTR utility are structured in the same manner as other Adabas utilities. Example JCL is shown below: 

//(jobcard)
//* 
//* 
//* ADAMTR
//*   
//*   Receive one or more messages from and Entire Broker or MQSeries
//*   Queue.
//*    
//ADAMTR    EXEC PGM=ADARUN 
//STEPLIB   DD DISP=SHR,DSN=USER.ADABAS.LOAD
//DDCARD    DD *
ADARUN PROGRAM=ADAMTR,SVC=xxx,DEVICE=dddd,DB=yyyyy
//DDDRUCK   DD SYSOUT=*                                              
//DDKARTE   DD *                                                     
ADAMTR MTYPE=MQSERIES                                                
ADAMTR MTYPE=ETBROKER                                              
ADAMTR ETBBROKERNAME=BROKER                                        
ADAMTR ETBBROKERID='III’
ADAMTR ETBSERVICE=SSSSSSSS                                               
ADAMTR ETBSERVICENAME=SNSNSNSN                                        
ADAMTR ETBSERVICECLASS=SCSCSCSC                                        
ADAMTR MSGLIMIT=20000                                                
ADAMTR PRINT=YES                                                     
//DDPRINT   DD SYSOUT=*                                              
//SYSUDUMP  DD SYSOUT=*

Informational Messages

The following informational messages are displayed when ETBSCONV=YES. 

Single Conversation Mode Set
Token  =
Userid =

Example showing default values

Single Conversation Mode Set
Token  = ADAMTR
Userid = REPTOR-DA3F-----USARCMTR

Stopping the Utility

You can stop ADAMTR utility execution in one of the following ways:

  • If the MSGLIMIT parameter is set to a nonzero value, ADAMTR will terminate after processing the number of messages specified in the MSGLIMIT parameter.

    Note:
    When a Broker queue is read by the ADAMTR utility, the utility must read input messaging transactions in the same manner the transactions were written to the queue. That is, assuming the sending program sends three messages and then commits the messaging transaction, ADAMTR will read the three messages and then commit the input messaging transaction. The value for MSGLIMIT is only checked by ADAMTR after committing an input messaging transaction. In the previously described transaction, if MSGLIMIT=1 or MSGLIMIT=2 is specified, ADAMTR will only terminate after reading and optionally printing the three messages.

  • ADAMTR will terminate after processing an input message that contains the eight-byte string "terminat" (all in lower case letters). With this in mind, a user could run ADAMTR with MSGLIMIT=0 (or MSGLIMIT set to a very high value) and then send this eight-byte string to the related queue using ADAMTS. When ADAMTR receives this special message, ADAMTR will optionally print the message and then terminate.

Using the ADAMTS (Message Test Send) Utility

The ADAMTS (Message Test Send) utility can be used to send requests to the Event Replicator Server without having (or prior to writing) a target application. The utility allows functional testing of:

  • requests (for example, initial-state requests, prior-transaction requests, or status requests) sent to an Event Replicator Server via an webMethods EntireX or WebSphere MQ queue.

  • an webMethods EntireX or WebSphere MQ queue, by sending one or more messages to that queue.

The ADAMTS utility issues messages for any errors it encounters. For more information, read ADAMTS Messages.

This section covers the following topics:

Syntax

The overall syntax of the ADAMTS utility is:

graphics/adamts.png

The webMethods EntireX and WebSphere MQ parameters you can specify in ADAMTS are described in the following sections:

Note:
Do not mix webMethods EntireX parameters and WebSphere MQ parameters in the same ADAMTS run.

webMethods EntireX ADAMTS Parameters

The parameters that can be used for the ADAMTS utility when testing an webMethods EntireX queue are shown in the following syntax. Note that all but the MTYPE parameter are required.

graphics/adamts_exx.png

Note:
Do not specify any of the parameters associated with WebSphere MQ in the same ADAMTS utility run.

WebSphere MQ ADAMTS Parameters

The parameters that can be used for the ADAMTS utility when testing a WebSphere MQ queue are shown in the following syntax. Note that all parameters are required.

graphics/adamts_mq.png

Note:
Do not specify any of the parameters associated with webMethods EntireX in the same ADAMTS utility run.

Parameters

Parameters for the ADAMTS utility vary, depending on the kind of queue you are using. Each input parameter line to DDKARTE should begin with ADAMTS and is structured in the same manner as other Adabas utilities. All of the parameters that can be specified in the ADAMTS utility are now described.

MTYPE

This required parameter identifies the type of queue (webMethods EntireX or WebSphere MQ) to which requests should be sent for the ADAMTS test. Valid values are "ETBROKER" or "MQSERIES". The default for MTYPE is "ETBROKER".

ETBBROKERID

Use this parameter to specify the webMethods EntireX Broker ID to use for the ADAMTS run. This parameter is required when MTYPE=ETBROKER and should not be specified otherwise.

Broker IDs come in two formats: one for TCP/IP communications and one for Adabas SVC communications. For TCP/IP communications, the format is: 

ip-address:port-number:TCP

In this case, the ip-address setting is the TCP/IP IP address and the port-number setting should match the webMethods EntireX PORT parameter.

For Adabas SVC communications, the format is: 

'broker-id:SVCnnn:NET'

In this case, the broker-id setting should match the webMethods EntireX BROKER-ID parameter in the Broker ETBFILE DD. The nnn setting should match either the webMethods EntireX ADASVC or ADA5SVC parameters in the Broker PARMS DD statement.

ETBBROKERNAME

Use this parameter to specify the name of the EntireX Broker stub program to use for the ADAMTS run. This parameter can only be specified when MTYPE=ETBROKER. When not specified, this parameter defaults to "BROKER".

Notes:

  1. EntireX Broker is a component of webMethods EntireX.
ETBSERVICE

Use this parameter to specify the webMethods EntireX service that should be used for the ADAMTS run. This should be the same as the value specified for the SERVICE parameter in webMethods EntireX. This parameter is required when MTYPE=ETBROKER and should not be specified otherwise.

ETBSERVICENAME

Use this parameter to specify the webMethods EntireX service name that should be used for the ADAMTS run. This should be the same as the value specified for the SERVER parameter in webMethods EntireX. This parameter is required when MTYPE=ETBROKER and should not be specified otherwise.

ETBSERVICECLASS

Use this parameter to specify the webMethods EntireX service class that should be used for the ADAMTS run. This should be the same as the value specified for the CLASS parameter in webMethods EntireX. This parameter is required when MTYPE=ETBROKER and should not be specified otherwise.

ETBSCONV

Use this parameter to specify the webMethods EntireX queue is to run using single conversation mode. This parameter is optional when MTYPE=ETBROKER.

ETBTOKEN

Use this parameter to specify the webMethods EntireX queue is to run using single conversation mode. This parameter is optional when ETBSCONV=YES. When not specified, this parameter defaults to "ADAMTS".

ETBUSERID

Use this parameter to specify the webMethods EntireX queue is to run using single conversation mode. This parameter is optional when ETBSCONV=YES. When not specified, this parameter defaults to REPTOR-<node>-----<jobname>.

MQQMGRNAME

Use this parameter to specify the WebSphere MQ queue manager name that should be used for the ADAMTS run. This parameter is required when MTYPE=MQSERIES and should not be specified otherwise.

MQQNAME

Use this parameter to specify the WebSphere MQ queue name that should be used for the ADAMTS run. This parameter is required when MTYPE=MQSERIES and should not be specified otherwise.

Running the Utility

The ADAMTS utility reads messages from the MTSIN file in its JCL and sends those messages to an webMethods EntireX or WebSphere MQ queue. JCL and input parameters for ADAMTS are structured in the same manner as for other Adabas utilities. The MTSIN should be defined with RECFM=VB.

This section covers the following topics:

Sample JCL

The JCL and input parameters for the ADAMTS utility are structured in the same manner as other Adabas utilities. Example JCL is shown below: 

//ADAMTS   EXEC PGM=ADARUN
//STEPLIB  DD DISP=SHR,DSN=USER.ADABAS.LOAD
//DDDRUCK  DD SYSOUT=X
//DDPRINT  DD SYSOUT=X
//SYSUDUMP DD SYSOUT=X
//DDCARD   DD *
ADARUN PROGRAM=ADAMTS,SVC=xxx,DEVICE=dddd,DB=yyyyy
/*
//DDKARTE  DD *
ADAMTS MTYPE=MQSERIES
ADAMTS MQQMGRNAME=MQnn
ADAMTS MQQNAME=’user.local.queue’
/*
//*   The MTSIN file should be defined with RECFM=VB
//*   The messages to send are read from the MTSIN file.
//MTSIN    DD  DISP=SHR,DSN=ARFvrs.MVSMTSI

Informational Messages

The following informational messages are displayed when ETBSCONV=YES. 

Single Conversation Mode Set
Token  =
Userid =

Example showing default values

Single Conversation Mode Set
Token  = ADAMTS
Userid = REPTOR-DA3F-----USARCMTS

This example JCL tests a WebSphere MQ queue.

Example of MTSIN Input Data

The file allocated by MTSIN in the JCL contains the messages to be read for the test. It should be defined with RECFM=VB.

The following sample MTSIN input data is shown with the hexadecimal offset in the first column, the hexadecimal representation of the data in the next four columns, and the actual data on the right of each line bounded by an asterisk. 

0000 E4D9C2C8 00000040 F0F10001 000000A7 *URBH    01 .   x*
0010 00000000 00000000 00000000 00000000 *                *
0020 C1D3C7D9 E3C8D4F1 00000000 00000000 *ALGRTHM1        *
0030 00000000 00000000 00000000 00000000 *                *
0040 E4D9C2C9 00000067 00000060 00000007 *URBI   .   -   .*
0050 C1D3C7D9 E3C8D4F1 D6E4E3F1 40404040 *ALGRTHM1OUT1    *
0060 C9D5E2E3 00C7008F C9F1F9F9 F1F4F3F1 *INST G .I1991431*
0070 40404040 40404040 40404040 40404040 *                *
0080 00000000 00000000 00000000 00000000 *                *
0090 00000000 00000000 00000000 00000000 *                *
00A0 C4C4C4C4 C4C4C4                     *DDDDDDD*