workshop lab to create cics request and response … lab consists of five "phases": phase...

IBM WebSphere Message Broker for z/OS

Workshop Lab to Create CICSRequest and Response Flow

This document can be found on the web at:www.ibm.com/support/techdocs

Search for document number WP100783 under the category of "White Papers"

Version Date: June 30, 2006Please see "Document Change History" on page 46 for updates provided in this version of the document.

IBM Washington Systems Center

Don BagwellIBM Washington Systems Center

[email protected]

Subhajit MaitraIBM Washington Systems Center

[email protected]

(This page intentionally left blank)

Executive SummaryThis document is based on a hand-on lab used in the ZSOA1 workshop conducted by the IBMWashington Systems Center. The intent of the lab is to show the use of the Message BrokerToolkit to create a workflow to access a CICS application on the z/OS system. The CICSapplication is a very simple one that returns a fictional address based on an integer input ofbetween 1 and 10.

In picture format, the lab exercise consists of the following:

Broker Toolkit MQBroker CICS

WBCSCUST

BAR

Deployed Workflow

MQ

MQ

MQ

EXCI Req

EXCI Resp

Request Message

Flow

Response Message

Flow

RFHUTILC "Write Queue"

<Customer> <CustNo>3</CustNo></Customer>

<Name>John Smith</Name><Address>123 Maple</Address><City>Oak Grove</City><State>NY</State>

RFHUTILC "Read Queue"

BAR

DB2

AK "Alaska"AL "Alabama" :WY "Wyoming"

"Get State"

Q

C Q

CICS Q

Q

C Q

D Q

Request Flow

Response Flow

Domain Connection

Dep

loy

BA

R

Picture representation of the structure of the lab

The key points are these:! The workflow consists of two flows -- a request flow (which uses the CICSRequest node) and a response

flow.

! The RFHUTILC tool is used to drive the workflow by placing an XML file on the request queue, and pullingthe resulting XML off the response queue.

! The Broker runtime is on the same z/OS system as the CICS region.

! The CICS application is accessed by formatting a COMMAREA and using the CICS EXCI interface

! The DB2 database access is simply to fetch the full name of the state based on the two-characterabbreviation. This was included in the lab as a way to illustrate DB2 access as well, though in truth theaccess is trivial and not central to the point of the lab

WP100783 - WebSphere Message Broker for z/OS -- CICS Request/Response Lab

Version Date: June 30, 20061© 2006, IBM Americas Advanced Technical SupportWashington Systems Center, Gaithersburg, MD

The lab consists of five "phases":

37Phase 5 - Create Broker Archive, Deploy and Test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

31Phase 4 - Create Response Message Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

18Phase 3 - Create Request Message Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

11Phase 2 - Create Message Set Project and Message Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3Phase 1 - General Lab Setup and Housekeeping Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .PagePhase

Important points

! This lab is built upon a set of system definitions in place at the Washington Systems Center.You won't have those exact things, but you may have things similar. You'll need to mapyour system information to that used in this lab.

! This lab makes use of a CICS application (WBCSCUST) that you may not have.

! This lab makes use of three files -- one COBOL COPYBOOK file and two files containingcustom ESQL used to populate the nodes in the workflow.

! This document is not intended to be a cookbook that works in all environments. It isintended to be a guide to see how such a process is done.



Phase 1 - General Lab Setup and Housekeeping Tasks

In this phase we'll take care of some basic stuff. In other phases we'll develop the Broker code.Overview:

Make certain you’re logged on as MQMaster ID, not administrator

This lab will involve a connection to MQBroker on the host. The ID the workstation is logged onto is whatgets passed up to the host to check for authority to make the connection. "MQMaster" (or mqmaster) hasbeen granted authority. Other IDs have not.

???

" Click on the "Start" button at the lower-left of your screen. Then look at the top:

If "mqmaster" then simply hit Esc key

If "administrator" or other ID, then you'll need to log off and log on as "mqmaster"

" Do the following:

# If "mqmaster," then skip to the next heading of this lab ("Download files...")

# If anything other than "mqmaster," then:! Go close any applications you may have open -- 3270 terminals, Notepad, RAD, etc.

! Press Ctrl-Alt-Del and then "Log Off"

! Log on as mqmaster ... password will be given to you in class

Download files needed for this lab

" Create a directory on your PC ... such as C:\TEAMtt, where "tt" is your team number.

" Open up a command prompt window (a "DOS window" for old-timers)

" Change directories to that new directory you created

" Now FTP down the source files:# Enter command:

ftp mig.null.washington.ibm.com

# Logon using your TSO userid and password# At the ftp> prompt, enter:

cd /u/teamxx/ZSOA1_MQBroker

Where teamxx is literal -- do not substitute your team number for "xx". Case matters.# Issue the command ls -al ... you should see something like this:

ftp> ls -al200 Port request OK.125 List started OKtotal 56drwxr-xr-x 2 ... Apr 15 22:29 .drwxr-xr-x 9 ... Apr 15 22:17 ..-rwxr-xr-x 1 ... Apr 15 22:28 CICS_Commarea_Customer.cpy-rwxr-xr-x 1 ... Apr 15 22:29 CustREQflow.txt-rwxr-xr-x 1 ... Apr 15 22:29 CustRESPflow.txt250 List completed successfully.



CICS_Commarea_Customer.cpy -- COBOL COPYBOOK for CICS applicationCustREQflow.txt -- custom code we wrote that will be used for "Request Flow" processingCustRESPflow.txt -- custom code we wrote that will be used for "Response Flow" processing

???

# Enter command ascii. It should respond with "200 Representation type is Ascii NonPrint"

# Now issue the command:mget *.*

Answer Y to each prompt about file to be downloaded. You should be asked three times: one foreach of the files you saw when you issued the ls -al command.

# Exit FTP by entering the command quit

" In Windows Explorer, go to your directory and open the CICS_Commarea_Customer.cpy fileusing Notepad. It should look something like this:

If you can't see readable text, then you downloaded the file with "binary" rather than "ascii."Delete the file and FTP it down again, this time with "ascii" encoding.

Important:

01 DFHCOMMAREA. 02 CUSTNO PIC S9(9) COMP-5 . 02 LASTNAME PIC A(25). 02 FIRSTNAME PIC A(15). 02 ADDRESS1 PIC X(20). 02 CITY PIC A(20). 02 STATE PIC A(5). 02 COUNTRY PIC X(15). 02 RETCODE PIC S9.

" Close Notepad (without saving if you accidentally made a modification to file).

Start Rational Application Developer and select new workspace

" Start Rational Application Developer:

Start $ All Programs $ IBM Rational $ IBM Rational Application Developer V6.0 $

Rational Application Developer

" It should ask you for a �Workspace� .... do the following:

Provide value of:C:\ZSOA1\MQBROKER

Click "OK"

1

2



" Close all perspectives by doing the following:

Again ... this is so we can have a consistent starting point for the lab instructions.Note:

In the upper-right corner of your screen, right-click on

the current perspective

1

Click "Close All"

2

<perspective>

Create "Domain Connection" to z/OS system

This defines the connection to the MQ Queue Manager which, for this lab, is on the z/OS system.???

" Do the following to switch to the "Broker Administration" perspective:

1 Select Window $ Open Perspective $ Other

Select "Broker Administration"

2

Click "OK"

3

" Open up the Domain wizard:

File $ New $ Domain



" Then do the following:

Queue Manager: MQ11

Host: mig.null.washington.ibm.com

Port: 1414

Click "Next"

1

2

3Bitmap cropped to save space

4

" If the connection was successful, you'll see what's shown here. Do the following:

Accept:

Servers1

Type:

TEAMtt_Domain_Connection

where "tt" is your team number

2

Click "Finish"

3

You should now see:

Your new domain connection. Green

"pipe" means connection open



Install the CICS Node you'll use later in the lab

This is a quick process of incorporating a feature into MQBroker???

" From the menu bar, go to Help $ Software Updates $ Find and Install

" Do the following:

Select "Search for new featuers

to install"1

Click "Next"

2

" Then the following:

Click on "New Local Site"

1In standard explorer that appears, select folder:C:\Download\WMB06

2

Click the checkbox next to

the folder

3

Click "Next"4



" Then:

Select the one and only feature

that appears

1

Click "Next"

2

" Accept the license agreement

" Then:

Make sure everything is

checked

1

Click "Next"

2

" When the "Install Location" window comes up, it'll have figured out where RationalApplication Developer is installed. Click Finish.

" If you get a warning about the feature being "unsigned," click Install.

" When it asks you whether to restart the workbench, click Yes.

" The "Select a workspace" window should come back with the same value you used initially(C:\ZSOA1\MQBroker). Click on OK.



Close all perspectives and re-open only “Broker Application Development”

To avoid any confusion about what you're seeing on your screen vs. what's shown in the labs, we're closingall perspectives. Next we'll have you open the "MQBroker Application Development" perspective.

???

" Close all perspectives by doing the following:

In the upper-right corner of your screen, right-click

on the field that says "Broker Admin..."

1

Click "Close All"

2

" Now open the "Broker Application Development" perspective. Do the following:


Select "Broker Application

Development"

2

Click "OK"

3



" You should be at a screen that looks like this:

"Resource Navigator"

"Outline"

"Broker Applic..."

"Problems"

What you accomplished in this Phase:Just some basic housekeeping in preparation for the creation of the Broker projects and flows, whichcomes next. The creation of the �Domain� is for testing of the application you�ll develop next.



Phase 2 - Create Message Set Project and Message Set

These are things the Broker Toolkit uses to organize the pieces of the MQ message program you�ll develop.???

Create Message Set Project

" From the menu bar, go to:

File $ New $ Message Set Project

" Provide the �Project� a name:

Provide name:TEAMtt_Message_Set_Project

1

Click "Next" 2

Where "tt" is your team number

" Provide the �Set� a name:

Provide name:TEAMtt_Message_Set

1

Click "Next" 2


The name you provide here -- TEAMtt_Message_Set where "tt" is your team number --will be somehting you will later match in some code. Type carefully here and later we'll Important!



" Our project is based on a COBOL copybook, so do the following:

Click "Finish"

3

Click "Custom Wire Format

Name" checkbox

1

Overtype default "CWF1" with:

COPYBOOK

2

Add a simple folder to the Message Set

This is where we�ll import the COPYBOOK for the CICS application we�ll be driving.???

" Do the following:

Highlight the Message Set

1Then:

Right clickSelect "New"

Select "Other"

2

Expand "Simple" and select "Folder"

3

Click "Next"

4



" Now name the folder and create it ... do the following:

Provide a name of docs

1

Click "Finish" 2

Import COPYBOOK you downloaded earlier

" Do the following:

Highlight the new "docs"

folder

1Then from menu bar:

File $ Import

2

Scroll down and highlight "File

System"

3

Click "Next" 4



" Now complete the selection and import the file. Do the following:

Use the browse button to navigate to the directory where you downloaded

the files earlier in the lab

1

Select the file CICS_Commarea_Customer.cpy,

but leave others unchecked2

Click "Finish" 3

Create a Message Definition file

" Do the following:

Highlight the Message Set

1Then:

Right clickSelect "New"Select "Message Definition File"

2

Select "COBOL File"

3

Click "Next"

4



" Then:

Expand until you expose the CPY file you imported

1

Highlight the CPY file 2

Click "Next"

3

" Then:

Take defaults

1

Click "Next"

2



" Then:

Highlight DFHCOMMAREA

1

Click the right arrow to move selection to

"Imported structures"

2

Check the "DFHCOMMAREA"

check box

3

Click "Next"4

" Finally:

Accept defaults up

here

1

Check both these boxes

2

Click "Finish" 3



Set default return code to zero

" Do the following:

Expand "Elements and Attributes" 1

Expand "msg_DFHCOMMAREA"

Highlight "RETCODE"

2

3

Click on "Properties" tab 4

" Finally:

Note: "RETCODE" is the selected property and "Local Element" is

the initial default display

Set default to 0 (zero)

1

Right mouse click anywhere in here

2

Select "Save"

3

Close tab

4

What you accomplished in this Phase:You set up the basic Broker Toolkit framework for the message flow development, which comes next.



Phase 3 - Create Request Message Flow

Now comes the fun part ... drawing out the graphical message flow, setting up connections and specifying theattributes. From this will come the MQBroker code that's actually used.

???

Create Message Flow Project

" From the menu bar, go to:

File $ New $ Message Flow Project

" Provide a name for the project such as TEAMtt_Message_Flow_Project (where "tt" isyour team number) and then click "Finish"

Create Request Message Flow

" Now do the following:

Highlight the Message Flow

Project

1

Then:Right clickSelect "New"Select "Message Flow"

2

" Next:

Provide schema:

TEAMtt_Request1

Provide name:

TEAMtt_Request_Flow2

Click "Finish"3


" You should now be at a point where you see something like this:

Message flow you just created

This is where we'll build our graphical layout of the flow



Detour -- peek at what you'll be building

We're going to spend a few minutes reviewing what we'll build. Nothing to do here other than look at thepictures and read the comments

???

" Review this picture ... this is our objective. We'll walk you through how to construct this, butfirst we want to give you a picture of what you're aiming at.

" What are all those things? Take a look at this:

MQInput Node

Compute Nodes

MQOutput Nodes

Connection between nodes

Input to the CICS

application

Return from CICS

Actual request against CICS



" Where do they come from? Take a look at this:

"Palette" expands to offer list of nodes

that may be included

Connections from nodes are created from option offered through right-click on node. You then drag connection to target node.

Create Request Message Flow - Part 1

Now we're ready to start actually doing something.???

" First, simply note the portion of the overall flow that we'll build first:

We'll build these three nodes and their connections first ...

... then we'll build these



Construct XML_Request_Queue "MQInput node"

" Do the following:

Click on "Palette" to

expand out the list of nodes

1

Click on "MQInput"

2

Move your cursor out into the field and

left-click the mouse ... that'll draw the node

3

Use arrows to scroll if necessary

" Using your mouse, drag the new node over to the left side of the field. (Recall thepicture of our objective ... we have many more nodes to build so we need to allow spacefor them all).

" Right mouse click on the node and click "Rename".

" Give it a new name of XML_Request_Queue

There's more we'll do to that node. For now let's get our nodes on the board and renamed. Thenwe'll create the connections. Then we'll set the attributes of the nodes.

Note:

Construct Extract_Errror "Compute node"

" Go back to the palette and select "Compute". You'll need to scroll down to find that.The nodes are in alphabetical order. Draw the compute node onto the board.

" Rename the compute node to Extract_Error

Construct Error_Queue "MQOutput node"

" Now select and draw an "MQOutput" node onto the board. Rename that toError_Queue.

Your drawing board should look something like this:



MQInput node

MQOutput node

Compute Node

Build connections between nodes

" Right click on the "XML_Request_Queue" node and select "Create Connection." Do thefollowing:

Highlight "Failure"

1

Click "OK"

2

End of arrow tied to your mouse location. It's waiting on you to tell

it where to connect to

" Position your mouse over the "Extract_Error" compute node and left-click the mouse.This anchors the connection to the target. You should see this:

" Right-click on the "XML_Request_Queue" node and create a second connection to the"Extract_Error" node, this time selecting Catch as the terminal from which theconnection will be made.



" Hover your mouse over one of the connections ... you should see it display the "from"terminal and the "to" terminal of connection:

Mouse over the connection displays the connection type

" Right-click on the "Extract_Error" node and create a connection to the "Error_Queue"node, selecting Out as the output terminal. Your picture should now look like this:



Set attributes for the two queue nodes

We need to tell the Toolkit a little about the two queue nodes.???

" Right click on the "XML_Request_Queue" node and select "Properties." Do thefollowing:

Select "Basic"

1

Provide MQ queue name:ZSOA.TEAMtt.XML.CUSTOMER.REQUEST


2

Select "Default"

3

Set "Message Domain" to XML 4

Select "Advanced"

5

Click "OK"

Set "Transaction Mode" to No 6

7



" Right click on the "Error_Queue" node and select "Properties." Do the following:

Select "Basic"

1

Click "OK"

Leave "Queue Manager Name" blank 2

Provide MQ queue name:ZSOA.TEAMtt.ERROR.OUTwhere "tt" is your team number

3

6

Select "Advanced"

4


The "Extract_Error" node (a compute node) has some work left as well, but we'll do that later.Note:



Create Request Message Flow - Part 2

" We're ready to build the remaining portion of the picture. We'll be a bit less explicit in ourinstructions. Note the portion of the overall flow that we'll build now:

We'll work left to right

A

B C

D E

F

From this point forward ... slow down ... take your time ... read instructions ... think aboutwhat you're doing ... be careful and thorough.Advice:

Draw nodes onto drawing board and rename them

The process is the same as done before:! Expand palette! Select node! Click on drawing board to place node! Move node to position it the way you want it! Right-click and "Rename" to rename the node

CICS_CPY_Response_QueueMQOutputF%

Failure_QueueMQOutputE%

Build_Fail_MessageComputeD%

n/a -- leave as "CICSRequest"CICSRequest(under "Additional IBM Nodes")C%

Build_CommareaComputeB%

n/a -- leave as "TryCatch"TryCatchA%

Rename toNode type in paletteLetter block Done



Create connections between nodes

Use previous picture as a guide.Note:

The process is the same as done before:! Right-click on origin node and select "Create Connection"! Select the output terminal (we'll supply which terminal to use here)! Left-click on the target node to anchor the connection to the node! Hover mouse over connection line to verify to/from terminals

OutC to F%

OutD to E%

ErrorSecond C to D connection%

FailFirst C to D connection%

OutB to C%

CatchA to D%

TryA to B%

OutInitial Input Queue to A%

Output terminal to useFrom/toDone

Set properties of MQ Queues

The process is the same as done before:! Right-click on queue node and select "Properties"! Set the properties as specified here! Click OK

In all cases, "tt" is your team number.Note:

#Under "Basic", set "Queue Name:ZSOA.TEAMtt.CPY.CICS.RESPONSE(where "tt" is your team number)

#Under "Advanced", set:Transaction Mode = No

CICS_CPY_Response_Queue%

#Under "Basic", set "Queue Name:ZSOA.TEAMtt.FAILURE.OUT(where "tt" is your team number)

#Under "Advanced", set:Transaction Mode = No

Failure_Queue%

PropertyOutput Queue NodeDone

Provide information into CICSRequest node

" Right-click on the "CICSRequest" node and select "Properties"

" Do the following:



Select "Basic"

1Applid:

CICSTMttwhere "tt" is your team number

Program Name:

WBCSCUST

Userid:

TEAMttwhere "tt" is your team number

1

2

3Check these two boxes

4

Click "OK"

5

Paste supplied custom code into compute node, set properties for each compute

The code you'll paste into the compute node is custom code ... written by one of us. The custom codehas multiple modules in it; but you paste the block into one compute node and it's available to allcompute nodes. We do need to tell each compute node which module to use. We'll do that by setting aproperty.

???

" From Windows Explorer, navigate to the directory where you downloaded the files fromthe host system at the start of this lab. (C:\TEAMtt, where tt is your team number).

" Open the CustREQflow.txt file with Notepad

" Edit $ Select All ... Edit $ Copy

" Now go back to the Broker Toolkit, right-click on any one of the compute nodes andselect Open ESQL. You'll get new tabbed-view in the toolkit that looks like this. Do thefollowing:

Insert cursor between "BROKER SCHEMA" line and

CREATE COMPUTE line

Paste copied code

1

2

Highlighted code is generic code required by

all compute nodes.



" Find the BuildCommarea section of code and do the following:

Right mouse click anywhere in the editor and select "Save" 3

Locate the section of code related to

"BuildCommarea"

1

Change the "tt" in 'TEAMtt_Message_Set' to

your team number

2

Close the editor by clicking the "X" on the tab 4

Earlier we mentioned how it was important to align the Message Set name with a piece of thecustom code ... this was it.

Note:

" You'll see one warning that looks like this. Don't worry ... it's only a warning, not anerror.



" Right click on the "Extract_Error" compute node and select "Properties." Then do thefollowing:

Click "Browse"

1

For the "Extract_Error" node, select the module

that ends with ... ...ExtractError

2

Click "OK"

3

Click "OK" to close "Properties" window

4

" Do the other two compute nodes in the same manner:

zsoa_GetCustInfo_Req_XML_BuildFailureBuild_Fail_Message%

zsoa_GetCustInfo_Req_XML_BuildCommareaBuild_Commarea%

Module NameCompute NodeDone

Save the message flow

" Right click anywhere in the drawing board that's not a node or connection

" Select "Save"

" Close the drawing board (better term: "Message Flow Editor") by clicking the "X" on thetab for the view.

What you accomplished in this Phase:Quite a bit, actually. You've built one-half the message flow. The response flow will involve steps verysimilar to what you've just gone through. It should go a bit faster.



Phase 4 - Create Response Message Flow

The response message flow will go in the same "message flow project" as the request flow. But it will be adifferent flow, with its own message flow file.

???

Create response message flow

" Do the following:

Highlight the Message Flow

Project

1

Then:Right clickSelect "New"Select "Message Flow"

2

" Next:

Provide schema:

TEAMtt_Response1

Provide name:

TEAMtt_Response_Flow2

Click "Finish"3


Not "Request" as before ... Response



A preview of the objective

A

B C

D

E F

G H I J

Build flow

Create nodes

The process is the same as done before:! Expand palette! Select node! Click on drawing board to place node! Move node to position it the way you want it! Right-click and "Rename" to rename the node

XML_Response_QueueMQOutputJ%

Build_XMLCompute I %

Get_State_DescDatabaseH%

Extract_State_CondComputeG%

Failure_QueueMQOutputF%

Build_Fail_MessageComputeE%

n/a - leave as "TryCatch"TryCatchD%

Error_QueueMQOutputC%

Extract_ErrorComputeB%

CICS_CPY_Response_QueueMQInputA%

Rename toNode type in paletteLetter block Done



Create connections

Use previous picture as a guide.Note:

The process is the same as done before:! Right-click on origin node and select "Create Connection"! Select the output terminal (we'll supply which terminal to use here)! Left-click on the target node to anchor the connection to the node! Hover mouse over connection line to verify to/from terminals

Out I to J%

OutH to I %

OutG to H%

TryD to G%

OutE to F%

CatchD to E%

OutA to D%

OutB to C%

CatchA to B, second connection%

FailureA to B, first connection%

Output terminal to useFrom/toDone

Paste supplied custom code into compute node, set properties for each compute

Just like you did for the "request" flow, this provides the custom code needed by each of the computenodes. The code we'll paste is different.

???

" From Windows Explorer, navigate to the directory where you downloaded the files fromthe host system at the start of this lab. (C:\TEAMtt, where tt is your team number).

" Open the CustRESPflow.txt file with Notepad

" Edit $ Select All ... Edit $ Copy

" Now go back to the Broker Toolkit, right-click on any one of the compute nodes andselect Open ESQL. You'll get new tabbed-view in the toolkit that looks like this. Do thefollowing:



Insert cursor between "BROKER SCHEMA" line and

CREATE COMPUTE line

Paste copied code

1

2

Right mouse click and "Save"

Close view by clicking on "X" on tab

3

4

Highlighted code is generic code required by

all compute nodes.

" You'll see a bunch of warnings and two errors. That's because we're not yet donesetting properties. The errors will clear when we do. The warnings persist, but it's okay.

Two "red X" errors

Set properties of each node

CICS_CPY_Response_Queue (block A in picture)

" Right-click on the node and select "Properties."

" For "Basic," set the queue name as:ZSOA.TEAMtt.CPY.CICS.RESPONSE

Where "tt" is your team number.



" For "Default," do the following:

Set "Message Domain" to MRM 1

Set other three to only option

available under each pulldown

2

" For "Advanced" do the following:


Click "OK"2

Get_State_Desc database node (block H in picture)

" Right-click on the node and select "Properties," then do the following:

Set "Data Source" to DB2LOCNM 1

Click "OK"3

Select module that ends withRes_CPY_Database

2

Customer_XML_Response_Queue (block J in picture)

" Right-click on the node and select "Properties"

" For "Basic," leave queue names blank



" For "Advanced" do the following:

Destination Mode:"Reply to Queue"

1

Click "OK"4

Transaction Mode:"No"

2

Persistence Mode:"No"

3

Error_Queue and Failure_Queue (blocks C and F in picture)

" For each, right-click on the node and select "Properties" and set the queue name:

# For "Basic," set Queue name to:ZSOA.TEAMtt.FAILURE.OUT(where "tt" is your team number)

# For "Advanced," set:Transaction Mode to No

Failure_Queue%

# For "Basic," set Queue name to:ZSOA.TEAMtt.ERROR.OUT(where "tt" is your team number)

# For "Advanced," set:Transaction Mode to No

Error_Queue%

Queue NameNodeDone

Compute nodes (blocks B, E, G and I )

" For each of the compute nodes set the "ESQL Module" appropriate for the node.

The process is the same as done before:! Right-click on the compute node and select "Properties"! Click the "Browse" button next to "ESQL Module"! Select the appropriate module and click "OK"

The list of modules will consist of both the new response modules and the requestmodules from earlier in this lab. Be careful in what you select. The name of themodule will imply response -- "Res_CPY"

Be Aware:

...Res_CPY_BuildXMLBuild_XML%

...Res_CPY_BuildGetStateCdExtract_State_Cond%

...Res_CPY_BuildFailMsgBuild_Fail_Message%

...Res_CPY_ExtractErrorExtract_Error%

Module that ends with:NodeDone



Save message flow

" Right click anywhere in the drawing board that's not a node or connection

" Select "Save". You'll continue to see "warning" messages:

All yellow warning ... ignore

" Close the drawing board (better term: "Message Flow Editor") by clicking the "X" on thetab for the view.

What you accomplished in this Phase:You've completed the second of two message flows. The project is now complete. You're ready to createthe archive file (called a "BAR" file -- Broker Archive).

Phase 5 - Create Broker Archive, Deploy and TestSwitch to the Broker Administration perspective

" Do the following to switch to the "Broker Administration" perspective:


Select "Broker Administration"

2

Click "OK"

3



Create Broker Archive

" From the "Broker Administration" perspective:

File $ New $ Message Broker Archive

" Do the following:

Highlight "Servers" 1

Name file:TEAMtt_MsgFlow_Bar


2

Click "Finish"

3

" Next:

Click on left icon 1

Select your two projects ... Message_Flow and Message_Set

2

Click "OK"

3

Click "OK"

4



" Close the "Archive Editor" ... do the following:

Click on "X" 1

Answer "Yes" 2

Deploy Message Flow

" The BAR file is now created and held in the toolkit. Now it's time to deploy the file up to MQBroker on the MIG z/OS system. Do the following:

Select your bar file under "Broker

Archives" and "Servers"

1

Right click and select "Deploy

File"

1

Expand and select the "default"

execution group3

Click "OK"

4



" You should see something like this. Do the following:

Click "Details" 1

Read message 2

Click "OK" 3

" Go read the event log to make sure things went okay:

Expand tree until you find "default" and

deployed flows under it1

Look for your team number in the list

2

Note: all teams will deploy to "default" execution group, so items under "default" may include more than just your team.

Test your deployed message flow

This will involve using the RFHUTILC utility -- a utility written as a handy interface to MQ -- to write amessage to the request queue. The message you'll write will be in the form a file with some very simpleXML in it. If things work, you'll see the CICS application's response in the response queue. You'll read theresponse queue by using RFHUTILC.

???

Make sure CICS region up

" Go to the MVS console and make sure your CICS region -- JOBNAME TEAMttC, where"tt" is your team number -- is active.

If it is not, then submit job TEAMtt.CICSLAB.CNTL(CICSTRT), where "tt" is your team number.Note:



Create request XML file

" Create a text file in the C:\TEAMtt directory, where "tt" is your team number (that is thedirector to which downloaded files earlier). Name the file something likeRequestXML.txt.

" Populate the file with:

<Customer><CustNo>1</CustNo></Customer>

The number in the middle of that -- 1 in this case -- is simply one of ten customer numbers held bythe WBCSCUST application. You may code any number between 1 and 10.

???

" Save the file

Start RFHUTILC utility and drive message flow

RFHUTILC is a MQ client utility that we'll use to connect to MQ on the host and place a message on therequest queue. The message we'll place there is the contents of our RequestXML.txt file. The queuewe'll write to is the input queue node on the far left of the "Request Flow" diagram -- theXML_Request_Queue.

???

" Using Windows Explorer, go to the directory:C:\Program Files\IH03

" Double click on the file rfhutilc. You'll get the following:



" Set the Queue Manager name and Queue Name. Do the following:

Select the one and only Queue Manager that appears in the

dropdown list

1

Select:ZSOA.TEAMtt.XML.CUSTOMER.REQUEST

Where "tt" is your team number2

Note: there'll be a lot of queues in the dropdown list ... choose carefully

The Queue Manager name that appears is based on a Windows system environmentvariable created with a format exactly as you see in the picture. When RFHUTILC starts up,it'll pick up the system environment variable and connect to the QM using the value specified.The "Queue Name" values that appear in the drop-down list are based on what the QMreports.

Important:

" Now read in your XML input file:

Click "Read File"1

Use the Explorer-like window that pops up to select your input

XML file

2



" Set the "Reply to Queue" on the MQMD tab:

Click on "MQMD" tab

1

Set "Reply to Queue" to:ZSOA.TEAMtt.XML.CUSTOMER.RESPONSE

where "tt" is your team number2Not the

Queue Mananger

This passes the "Reply to Queue" in as a header rather than hard-coding it in the app. That's more like how the Enterprise Service Bus will work -- dynamic

reply to information in headers.

" Let's do a "gee whiz" detour:

Click on "Data" tab

1

See data that will be written to

request queue3

Select the "XML" radio

button

2



" Now write the message to the request queue:

Click on "Write Q"

2

Go back to "Main" tab

1

Check for indication that message was sent to the queue

3

Check for success

" Do the following:

Select:ZSOA.TEAMtt.XML.CUSTOMER.RESPONSE


1

Click "Read Q"

2

Check for "Msg read" indication

3



A bad sign would be "No Msg on Queue" ... which would mean the response queue was empty.We would then need to go check the ERROR and FAILURE queues.

???

" Now go see what data was returned:

Click "Data" tab1

Click "XML"

for data format

2

Look at data, particular "CustNo", which should

match what you passed in

3

" Review the lab overview handout and see if your work here makes more sense ... theconstruction of the request and response flows, the driving of the CICS application, etc.

Finish the lab

If you were successful, you may simply stop at this point if you choose.???

" Read the ERROR queue and see if it has amessage

" Read the FAILURE queue and see if it has amessage

" Call instructor over to help debug problem

(Optional Extra Credit)Change your input XML so a different customernumber is used, and resubmit. Follow the sameprocess to read the message off the responsequeue.

If no message returnedIf you were successful

What you accomplished in this Phase:You made use of the message flows you created earlier. The archive was deployed up to Broker on thez/OS system. Then you used the RFHUTILC utility to write a message to the request queue, have yourflow process the request, and you then read the response queue.



Document Change HistoryCheck the date in the footer of the document for the version of the document.

Updated with document number WP100783June 30, 2006

Original document.June 29, 2006

End of Document



workshop lab to create cics request and response … lab consists of five "phases": phase...

Documents