74
CSC Proprietary 06/21/22 02:14 PM 5864_ER_WHITE.PPT 1 S31CV. Automating the Donut Donation. A CICS BTS Prototype Michael Erichsen, CSC Denmark, [email protected] GSE Nordic Technical Conference, May 2004, Stockholm, Sweden

Automating the Donut Donation

Embed Size (px)

Citation preview

Page 1: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 1

S31CV. Automating the Donut Donation. A CICS BTS Prototype

Michael Erichsen, CSC Denmark, [email protected] Nordic Technical Conference, May 2004, Stockholm, Sweden

Page 2: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 2

Agenda• What is BTS?• The Business Problem• The Prototype Application

• Application Design and Coding

• Debugging Tools• Lessons Learned• Adding the 3270 Bridge• Adding SOAP Support• The Bigger Picture

Page 3: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 3

The General Business Problem• Challenges emerged from two

separate Legacy Systems Transformation Scenarios

• In one project control and validation logic became too complicated for a 3270 bridge monitor

• Another project had componentisation problems:

– Some finalisation routines were common between many systems

– Components were physically separate, but had to run in sequence to have a consistent business transaction

• We need a higher level to handle control logic, separated from the business logic

Page 4: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 4

BTS Seen from a Classic CICS Perspective• An extension of the pseudo-conversational transaction

processing model• Transaction life is much longer• An extension to the EXEC CICS API• Multiple, named, persistent COMMAREA’s• A higher level dispatching mechanism called Scheduler Services• BTS is implemented as three new CICS domains

– Business application manager (BA)– Event manager (EM)– Scheduler services (SH)

• Two VSAM KSDS data sets– Internal state of BTS stored in DFHLRQ, Local Request Queue– Containers stored in repository files

Page 5: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 5

BTS Definitions• Process

– The largest unit of the environment– Maps to a number of transactions, events, and timers

• Activity– An event-driven piece of business logic– Normally implemented as a background transaction– Ends by sending an event back to caller

• Event– Sent by an activity or an external program– Causes the BTS Scheduler Services to reattach an activity

• Timer– Just like an ICE– Causes the BTS Scheduler Services to reattach an activity

• Container– A named, persistent COMMAREA, can be larger than 32K

Page 6: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 6

External Interfaces to a BTS Process• BTS-aware CICS programs

outside the BTS environment can

– Start a process– Acquire an activity and run it– Get and put BTS data

containers• BTS-unaware CICS programs

can be called by BTS activities– Through the BTS 3270 Bridge

interface– With an EXEC CICS LINK

PROGRAM

Page 7: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 7

The Prototype Application• BASS/E: Breakfast Administration Support System/Extended

– Handles the Donut Donation for the Friday morning breakfast meeting• Five versions since 1995

– A manual system, drawn on a whiteboard– A 3270 CICS VSAM application– Web enabled using the 3270 Bridge and CICS Web Support– A BTS application notifying the next happy donor by e-mail and SMS

using SMTP and the CICS Sockets interface• Mail function based on CICS Supportpak CA1H, developed by Don Grinsell,

IS Division, State of Montana, USA, and Corneel Booysen, EITS, South Africa

– A more sophisticated business process management model, including SMS messaging

Page 8: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 8

The Business Problem

Page 9: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 9

The Original Business Process Mapping

DFHINITIALDefine Input

EventsDefineTimer1

TIMER1POPPEDFind Giver

Timer1

GIVERFOUND

Send Mail1

MAIL1SENT

Wait foracceptance

Timer2BASSFILELookup

TIMER2POPPED

Send Mail2

SMTP Server

BASS/EMain Panel

SMTP Server

MAIL2SENT

Wait forCompletion

BASSEGIVEN

CompleteProcess

BASS/EMain Panel

BASS/EAbsence Panel

AbsenceHandler

GIVERACCEPTED

DefineTimer2

BASS/EMain Panel

Page 10: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 10

The Activity StructureMapping to CICS Transaction Programs

RootActivity

FindGiver

Send MailThursday

Send MailFriday

AbsencePanel

MainPanel

StartProcess

• The Main Panel sends events and calls the Start Process program

• The Absence Panel sends an event

• The Start Process program starts a new process

• The Root Activity program is the event handler (control logic) for the process

• The last three programs are BTS-aware. They represent three activities and LINK to business logic programs

Page 11: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 11

Version 1, 1995: A Manual System

Page 12: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 12

Version 2, 1997: A CICS VSAM 3270 Application

Page 13: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 13

Version 3, 1999: CICS Web Support and 3270 Bridge

Page 14: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 14

Version 4, 2003: BTS and e-mails

Page 15: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 15

Version 5, 2004: SMS added

Page 16: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 16

BTS-related CEDA Definitions

• Local Request Queue– VSAM file DFHLRQ in group DFHCBTS– Used by the BTS Scheduler Services

• Application Repository– VSAM file containing processes, activities, and containers

• Application Process type definition– Links process type to a repository file

• Ordinary transaction definitions– For programs implementing activities

Page 17: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 17

The BTS Process is started by an external input

• We have implemented this as a separate transaction that can be started from the Main Panel–EXEC CICS DEFINE PROCESS(processname) PROCESSTYPE("BASSE") TRANSID("BAS2")

–EXEC CICS RUN ACQPROCESS SYNCHRONOUS• This starts the BAS2 transaction, which is the Root Activity (i.

e.: An event handler program)• The first time an activity is attached, the reattach event is

called DFHINITIAL

Page 18: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 18

Event Handler Main Loop in Root Activity•EXEC CICS RETRIEVE REATTACH EVENT();•if "DFHINITIAL” then {

defineInputEvents(); timer1(); }

•else if "TIMER1_POPPED” then findGiver();•else if "GIVER_FOUND” then mail1();•else if "MAIL1_SENT” then waitAcceptance();•else if "GIVER_ACCEPTED” then timer2();•else if "TIMER2_POPPED” then mail2();

•else if "MAIL2_SENT” then waitCompletion();•else if "USER_ABSENT” then absenceHandler();

•else if "BASSE_GIVEN” then completeProcess();

Page 19: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 19

The Main Loop maps the Business Process

DFHINITIALDefine Input

EventsDefineTimer1

TIMER1POPPEDFind Giver

Timer1

GIVERFOUND

Send Mail1

MAIL1SENT

Wait foracceptance

Timer2BASSFILELookup

TIMER2POPPED

Send Mail2

SMTP Server

BASS/EMain Panel

SMTP Server

MAIL2SENT

Wait forCompletion

BASSEGIVEN

CompleteProcess

BASS/EMain Panel

BASS/EAbsence Panel

AbsenceHandler

GIVERACCEPTED

DefineTimer2

BASS/EMain Panel

Page 20: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 20

The DFHINITIAL Event is fired immediately• These events have to be predefined by the root process to

allow external BTS-aware programs to send them to the BTS process:–EXEC CICS DEFINE INPUT EVENT("GIVER_ACCEPTED");–EXEC CICS DEFINE INPUT EVENT("USER_ABSENT");–EXEC CICS DEFINE INPUT EVENT("BASSE_GIVEN");

• This event is sent back to the root activity when the timer pops. Until then the process is “Dormant” (sleeping):–EXEC CICS DEFINE TIMER("TIMER1") EVENT("TIMER1_POPPED") AFTER DAYS() HOURS();

Page 21: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 21

Thursday the Process Woke Up• In case we have just jumped backwards in the process, we

needed to delete an activity already defined–EXEC CICS DELETE ACTIVITY("FIND_GIVER");

• Then it ran a separate activity to find the next donor–EXEC CICS DEFINE ACTIVITY("FIND_GIVER") EVENT("GIVER_FOUND") TRANSID("BAS3");

–EXEC CICS RUN ACTIVITY("FIND_GIVER") SYNCHRONOUS;

• Outside BTS this would just have been an EXEC CICS START TRANS or LINK PROGRAM

– BTS Scheduler Services gives control to the program on behalf of the process

Page 22: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 22

The Find Giver Activity Program• Since this is a one-shot activity no event handler loop is needed

– EXEC CICS RETRIEVE REATTACH EVENT();

• Everything is done in the first activation called “DFHINITIAL”– This transaction is not reattached again in this process

• If not "DFHINITIAL” then we have an error– EXEC CICS ABEND ABCODE() NODUMP;

• LINK to a subprogram browsing through the BASS/E application VSAM file to find the donor

• Pass the data using a data container– EXEC CICS PUT CONTAINER("FIND_GIVER")

FROM(basse_container) FLENGTH();• Tell the BTS Scheduler Services that we do not want to be

reattached– EXEC CICS RETURN ENDACTIVITY;

Page 23: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 23

The Root Activity Reattached to Send a Mail•EXEC CICS CHECK ACTIVITY("FIND_GIVER") COMPSTATUS() MODE() SUSPSTATUS();

•EXEC CICS GET CONTAINER("FIND_GIVER") ACTIVITY("FIND_GIVER") INTO(basse_container) FLENGTH();

•EXEC CICS DELETE ACTIVITY("SEND_MAIL1");•EXEC CICS DEFINE ACTIVITY("SEND_MAIL1") EVENT("MAIL1_SENT") TRANSID("BAS4");

•EXEC CICS PUT CONTAINER("SEND_MAIL1") ACTIVITY("SEND_MAIL1") FROM(basse_container) FLENGTH();

•EXEC CICS RUN ACTIVITY("SEND_MAIL1") SYNCHRONOUS;

Page 24: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 24

The Donor is required to Accept Responsibility

Link to BASS/EWeb Page

(CICS 3270 Bridge)

E-mail sentfrom CICS

Page 25: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 25

The Donor Clicks the Main Panel Accept Button• The Main Panel has been

made BTS-aware by adding these statements

• An event is sent to the process– EXEC CICS ACQUIRE

PROCESS(processname) PROCESSTYPE("BASSE");

– EXEC CICS RUN ACQPROCESS INPUTEVENT("GIVER_ACCEPTED") SYNCHRONOUS;

– EXEC CICS CHECK ACQPROCESS COMPSTATUS() MODE() SUSPSTATUS();

Page 26: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 26

The Root Activity Reattached by the Event• An new timer is set up waiting for the expected breakfast

time–EXEC CICS DELETE TIMER("TIMER1");–EXEC CICS DEFINE TIMER("TIMER2") EVENT("TIMER2_POPPED") AFTER DAYS() HOURS();

• Once again the process becomes “dormant”• When the timer pops, the process is reattached to send

another mail asking the donor to confirm that breakfast has been given

Page 27: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 27

Finally the Donor Confirms• This is the only other

modification to the Main Panel• An event is sent to the process

the same way as before• The Root Activity program is

reattached to clean up• completeProcess()

– EXEC CICS RETURN ENDACTIVITY;

Page 28: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 28

Pseudo-Conversations and BTS Processes

Pseudo-conversation BTS ProcessIf no commarea is passed

Send an empty mapIf DFHINITIAL

Define input eventsStart first activity

Else if PF3Clear screen and return control to CICS dispatcher

Else if all activities have endedComplete the process by cleaning up and return control to Scheduler Services

ElseReceive a map with input dataProcess data using business logicSend a map with output data

ElseCheck activityGet containerProcess data using business logicPut containerRun another activity

Page 29: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 29

This was the Sequential Flow through the Process

DFHINITIALDefine Input

EventsDefineTimer1

TIMER1POPPEDFind Giver

Timer1

GIVERFOUND

Send Mail1

MAIL1SENT

Wait foracceptance

Timer2BASSFILELookup

TIMER2POPPED

Send Mail2

SMTP Server

BASS/EMain Panel

SMTP Server

MAIL2SENT

Wait forCompletion

BASSEGIVEN

CompleteProcess

BASS/EMain Panel

BASS/EAbsence Panel

AbsenceHandler

GIVERACCEPTED

DefineTimer2

BASS/EMain Panel

Page 30: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 30

But What if the Donor Used the Absence Panel?• The Absence Panel has been

made BTS-aware by adding these statements– EXEC CICS ACQUIRE PROCESS(processname) PROCESSTYPE("BASSE");

– EXEC CICS PUT CONTAINER("USER_ABSENT") ACQPROCESS FROM(absent_container) FLENGTH();

– EXEC CICS RUN ACQPROCESS INPUTEVENT("USER_ABSENT") SYNCHRONOUS;

– EXEC CICS CHECK ACQPROCESS COMPSTATUS() MODE() SUSPSTATUS();

Page 31: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 31

The Root Activity is being Reattached by the Event• The Root Activity program has to decide how to handle the

absence notification• Has the first timer popped yet?

–EXEC CICS CHECK TIMER("TIMER1") STATUS();• Is this the donor or somebody else?

–EXEC CICS GET CONTAINER("USER_ABSENT") PROCESS INTO(absent_container) FLENGTH();

–EXEC CICS GET CONTAINER("FIND_GIVER") ACTIVITY("FIND_GIVER") INTO(find_container) FLENGTH();

• Has somebody already accepted responsibility?– LINK to a subprogram reading the application VSAM file

• If needed jump backwards in the process

Page 32: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 32

DFHINITIALDefine Input

EventsDefineTimer1

TIMER1POPPEDFind Giver

Timer1

GIVERFOUND

Send Mail1

MAIL1SENT

Wait foracceptance

Timer2BASSFILELookup

TIMER2POPPED

Send Mail2

SMTP Server

BASS/EMain Panel

SMTP Server

MAIL2SENT

Wait forCompletion

BASSEGIVEN

CompleteProcess

BASS/EMain Panel

BASS/EAbsence Panel

AbsenceHandler

GIVERACCEPTED

DefineTimer2

BASS/EMain Panel

An Absence Notification makes us jump Backwards

Page 33: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 33

Debugging Tools• CBAM, IBM’s BTS Monitoring

tool• Your own application trace

statements• Your own clean-up utility• CICS auxiliary trace• You could also use the BTS

SPI to write programs to acquire activities and ask about their status etc.

Page 34: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 34

Page 35: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 35

Page 36: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 36

Page 37: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 37

Page 38: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 38

Page 39: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 39

Page 40: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 40

Process Lifecycle traced by Application in MSGLOG• ....BAS1 20040312114845 Starting process BASSE12 • ....BAS2 20040312114845 Process BASSE12 • ....BAS2 20040312114845 Activity DFHROOT • ....BAS2 20040312114845 Reattached by event DFHINITIAL• ....BAS2 20040312114846 Next event: TIMER 1 POPPED • ....BAS2 20040317064848 Process BASSE12 • ....BAS2 20040317064848 Activity DFHROOT • ....BAS2 20040317064848 Reattached by event TIMER1_POPPED• ....BAS3 20040317064848 Process BASSE12 • ....BAS3 20040317064848 Activity FIND_GIVER • ....BAS3 20040317064848 Reattached by event DFHINITIAL • ....BAS2 20040317064849 Next event: GIVER FOUND • ....BAS2 20040317064849 Process BASSE12 • ....BAS2 20040317064849 Activity DFHROOT • ....BAS2 20040317064849 Reattached by event GIVER_FOUND • ....BAS4 20040317064850 Process BASSE12 • ....BAS4 20040317064850 Activity SEND_MAIL1 • ....BAS4 20040317064850 Reattached by event DFHINITIAL • ....BAS2 20040317064853 Next event: MAIL 1 SENT

Page 41: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 41

A Clean-up Utility• A utility to remove processes that

have gone stuck is useful and simple to write

• This one removes one process per invocation– EXEC CICS STARTBROWSE PROCESS PROCESSTYPE("BASSE") BROWSETOKEN();

– EXEC CICS GETNEXT PROCESS(processname) BROWSETOKEN();

– EXEC CICS ENDBROWSE PROCESS BROWSETOKEN();

– EXEC CICS ACQUIRE PROCESS(processname) PROCESSTYPE("BASSE ");

– EXEC CICS CANCEL ACQPROCESS;

Page 42: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 42

CICS Auxiliary Trace• 01289 QR AP F801 EIBAM ENTRY PROCESS_EXEC_ARGUMENTS 002031D0,0005A988 • 01289 QR BA 0110 BAPR ENTRY ADD_PROCESS 0020316D , 00000000 , 0000• 01289 QR BA 0160 BATT ENTRY INQUIRE_PROCESSTYPE EMAIL • 01289 QR DD 0301 DDLO ENTRY LOCATE 1A890760,1B2FA47C,PTT,EMAI• 01289 QR DD 0302 DDLO EXIT LOCATE/OK 1A8BD5C0 , D7E3E3C5 • 01289 QR BA 0161 BATT EXIT INQUIRE_PROCESSTYPE/OK BASSREP,,OFF,ENABLED • 01289 QR XM 0201 XMXD ENTRY INQUIRE_TRANDEF BAS2 • 01289 QR DD 0301 DDLO ENTRY LOCATE 1A800040,1B2FA484,TXD,BAS2• 01289 QR DD 0302 DDLO EXIT LOCATE/OK 1A8FA8B8 , D7000000 • 01289 QR XM 021E XMXD EVENT Transaction_definition_BAS2_on_exit_from_module • 01289 QR XM 0202 XMXD EXIT INQUIRE_TRANDEF/OK CSCMMBT2 • 01289 QR SM 0301 SMGF ENTRY GETMAIN 20CDB728 , 0000004D,7C,YES• 01289 QR SM 0302 SMGF EXIT GETMAIN/OK 1A8BD5E0 • 01289 QR SM 0301 SMGF ENTRY GETMAIN 20CDB728 , 0000004D,C8,YES• 01289 QR SM 0302 SMGF EXIT GETMAIN/OK 1A8BD660 • 01289 QR BA 0709 BALR2 ENTRY Create_Key • 01289 QR AP 04E0 FCFR ENTRY WRITE BASSREP,1B2FA648,00000000,• 01289 QR AP EA00 TMP ENTRY LOCATE FCT,BASSREP • 01289 QR AP EA01 TMP EXIT LOCATE FCT,BASSREP,1B91B158,NORMA• 01289 QR AP EA00 TMP ENTRY UNLOCK FCT,BASSREP • 01289 QR AP EA01 TMP EXIT UNLOCK FCT,BASSREP,NORMAL

Page 43: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 43

A CICS Version Upgrade Damaged Consistency between the LRQ Data set and the BTS Repository• DFHDU0203I 30/10/2003 06:19:13 DCMCPXF A transaction dump was taken for dumpcode: ASH2, Dumpid: 2/0021.

• DFHAC2236 30/10/2003 06:19:13 DCMCPXF Transaction BAS2 abend ASH2 in program DFHXMAB term ????. Updates to local recoverable resources will be backed out.

• DFHSH0105 30/10/2003 06:19:14 DCMCPXF Request (Id: 200310300619110000000001, Processtype: BASSE, Processname: BASSE44, Activityname: DFHROOT, Transaction: BAS2) cannot be serviced. It will be retried every minute and will be purged after 24 hours if not serviced then.

• …………..1440 abends later………..• DFHSH0107 31/10/2003 06:22:11 DCMCPXF Request (Id: 200310300621190000000045, Processtype: BASSE, Processname: BASSE44, Activityname: DFHROOT, Transaction: BAS2) has remained unserviceable for 24 hours and has now been purged.

Page 44: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 44

Abend ASH2 Explanation• EXPLANATION: An attempt to service a

Scheduler Services request failed due to required resources being unobtainable.

• This may result in a request being unserviceable or an Activity being marked abended depending on the nature of the failure.

• SYSTEM ACTION: The transaction is abnormally terminated with abend code ASH2. CICS takes a transaction dump, unless module DFHDUIO is not loaded.

• USER RESPONSE: Check that any required links between regions are available. Check the Distributed Routing Program name is correct and the program is usable. Use the transaction dump to determine the cause of the failure. For further assistance, or if module DFHDUIO is not loaded and no transaction dump is available, contact your system programmer.

Page 45: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 45

DFHSH0105 Explanation• Explanation: A request cannot be serviced immediately. This is either because the

Distributed Routing Program, identified by the DSRTPGM SIT parameter, has returned a response which indicates that it is unable to route a request, or a temporary error occurred during an attempt to service the request locally.

• The request is identified by the request id id (the key of the request on the Local Request Queue data set (DFHLRQ)), the process type, the process name, the activity name, and the transaction id.

• System Action: No dumps are taken. The request is marked unserviceable, and is then retried every minute until it is either serviced, or 24 hours have elapsed in which case the request is purged and message DFHSH0107 issued.

• Message DFHSH0106 is issued once every hour while the request cannot be serviced. If the request is serviced successfully, message DFHSH0108 is issued.

• User Response: Investigate why the request cannot be serviced. This may be caused by one of the following:

– The local request queue is unavailable. – The request refers to a resource (activity or process) which is unavailable. – The system to which the request is to be routed is down, or the link is down. – The Distributed Routing Program is failing or is returning an invalid target system.

Page 46: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 46

Lesson Learned: Be careful with the Local Request Queue

Page 47: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 47

Other Lessons Learned• An Input Event needs a Define Activity done first• A child activity signals that it has finished using RETURN ENDACTIVITY, but it is not completed before the caller has done a CHECK ACTIVITY

• Child activities signal errors by abending– The caller should not propagate the abend, but handle it

intelligently• Draw a state graph as a roadmap for development and

testing or you will get lost– Write application trace statements to MSGLOG to follow

process states

Page 48: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 48

More Lessons Learned• Keep Control Logic in the Root Activity and Business Logic

in subprograms LINKed to by the Child Activities• Use CICS-supplied CBAM transaction to monitor

– It displays only objects, not state data– This might be a requirement to the Hursley lab?

• The week number routine in the C compiler does not respect that week number 1 is the first week with most of its days in the new year, i.e. the week of the first Thursday

– Takes a lot of code to work around

Page 49: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 49

The Worst Problem: Demanding Users!• Demands for more features skyrocketed• The latest version

– Sends a notification Wednesday– If nobody has accepted by Thursday, a mail is broadcast to

everybody not absent to take action– Sends an SMS Friday morning with the number of persons

present– Handles the complete cancellation of the process in weeks of

holiday– The process terminates itself if users forget to do so– And so on

• A spin-off– The mail routine has been generalised to a standardised service

available for other applications

Page 50: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 50

How difficult is BTS?• For the systems programmer

– Very easy– Just a few definitions

• For the application programmer– It takes an effort to learn API and syntax, and to understand

processes and scope of activities– Coding is not harder than classical EXEC CICS coding, once

you grasp the parallel to the pseudo-conversational model• For the system designer

– Not trivial to design the process flow– When it becomes too complicated, it is probably better to design

in graphical workflow or business process modelling tools and leave BTS to do simple processes

Page 51: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 51

Adding Bridge Support

Page 52: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 52

3270 BMS to 3270 Bridge Without Tears• The BMS Macro Source can be assembled with

SYSPARM(TEMPLATE)– The output is an HTML source

• The output is moved to a DFHHTML data set using IEBUPDTE

• You can pre-customise the HTML– Use your own DFHMSX macro– Add DFHWBOUT statements in the BMS source– A “normal” assembly for MAP or DSECT ignores these

statements– Unfortunately IBM’s SDF II product refuses to re-import

BMS source with DFHWBOUT macros• You can post-customise the HTML using a tool like

Dreamweaver to align tables

Page 53: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 53

• MACRO • DFHMSX • DFHMDX

MAPSET=CSCMMHD,MAP=*,BGCOLOR=WHITE,CODEPAGE=277,RESET=NO

• DFHMDX MAPSET=CSCMMHD,MAP=CSCMMHD,• TITLE='BASS/E Administration',• PF10='Acceptér',PF11='Fravær',PF12='Har givet',• ONLOAD='showImage()',• SUPPRESS=((1,1),(1,10),(23,*))• MEND

Customised DFHMSX Macro

All other PF-keysare suppressed

Fields at these positionsare suppressed

JavaScript to runwhen HTML isloaded

Page 54: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 54

• CSCMMHD DFHMSD TYPE=MAP,LANG=C,TRIGRAPH=YES,FOLD=UPPER,MODE=INOUT, SUFFIX=

• CSCMMHD DFHMDI SIZE=(24,80),CTRL=(FREEKB),MAPATTS=(COLOR,HILIGHT),DSATTS=(COLOR,HILIGHT),COLUMN=1,LINE=1,DATA=FIELD,TIOAPFX=YES,OBFMT=NO

• DFHWBOUT '<script language="JavaScript">' • DFHWBOUT '<!--' • DFHWBOUT 'function showImage(){' • DFHWBOUT 'var Naeste = '''';' • DFHWBOUT 'var Init = '''';' • DFHWBOUT 'if (Naeste ^= ''&&F040440002_NAESTE;'')' • DFHWBOUT ' Init = ''&&F040180003_INIT;'';' • DFHWBOUT 'else if (Naeste ^= ''&&F050440002_DFH0076;'')' • DFHWBOUT ' Init = ''&&F050180003_DFH0001;'';' • ...

BMS Macro (Part 1)

Col 4, row 44, length 2, field name NAESTE

Ugly? Perhaps.But it works

Page 55: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 55

BMS Macro (Part 2)• DFHWBOUT 'else if (Naeste ^= ''&&F190440002_DFH0090;'')' • DFHWBOUT ' Init = ''&&F190180003_DFH0015;'';' • DFHWBOUT 'if (Init.charAt(2) == '' '')' • DFHWBOUT ' Init = new String(Init.substring(0, 2));' • DFHWBOUT 'this.img.src = ''/cics/dmwg/cscwbget/'' + Init + ''jpeg.jpg'';'

• DFHWBOUT '}' • DFHWBOUT ' // -->' • DFHWBOUT '</script>' • DFHWBOUT '<meta name="author" content="Michael Erichsen">' • DFHWBOUT '<meta name="owner" content=”[email protected]">' • DFHWBOUT '<img name="img" src="/cics/dmwg/cscwbget/bbjpeg.jpg">'

Double Quotes,Not apostrophes

If the <img> tag is placed in the HTML body and not the header, the assembler will change it into &lt;img name=…

Page 56: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 56

Customised 3270 Bridge HMTL

Page 57: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 57

Adding SOAP Support

Page 58: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 58

The SOAP Request•<SOAP-ENV:Body><FindGiver><bassecontainer><giver> </giver><shortname> </shortname><mobile> </mobile><antalbasser>0</antalbasser><recnum>0</recnum></bassecontainer></FindGiver></SOAP-ENV:Body>

Page 59: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 59

Page 60: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 60

Page 61: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 61

The LINKable Subprogram CSCMMFGV• CSCMMFGV is a subprogram in the BASS/E application,

which returns the properties of the donor of the week and a count of how many people will be present

• In C the COMMAREA looks like this:–typedef struct BASSE_CONTAINER { char giver[8]; char shortname[16]; char mobile[8]; int antal_basser; int recnum; };

Page 62: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 62

The COMMAREA as a COBOL copy book• We can generate a COBOL XML converter using a tool in

WebSphere Studio Enterprise Developer, which comes with the SOAP for CICS feature

• To make it work, we need a COBOL copy book:– 01 BASSECONTAINER. 02 giver pic x(8) . 02 shortname pic x(16) . 02 mobile pic x(8) . 02 antalbasser pic s9(8) comp . 02 recnum pic s9(8) comp .

• Avoid hyphens and underscores in the name. They cause problems• It is extremely important to have the code pages set right both for

generation and for compilation. The generated code uses a hash table based on character values.

• National Language Characters like æ, ä, ø, ö, and å need special UTF-8/UTF-16 conversion, otherwise the message will be invalid

Page 63: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 63

WebSphere Studio Enterprise Developer

Page 64: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 64

WebSphere Studio Enterprise Developer

Must be righte.g. 277

Name usedin generated

COBOL source

Page 65: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 65

Generated COBOL converters and driver program• Three COBOL source files (.cbl) and two XML Schema files

(.xsd) are generated from the COBOL copybook• CSCMMFGI is the input XML-to-COMMAREA converter• CSCMMFGO is the output COMMAREA-to-XML converter

– Remove this source line “2 pic x(21) value '<?xml…”• CSCMMFGD is the converter driver, which calls the other

programs using a COBOL CALL– Let the LINK statement point to your own original program– Activate statements marked ”CICS” and remove the

corresponding batch statements• A number of other COBOL subprograms are imbedded in

the three source files• CSCMMFGG is an error handler

– Remove the ”<?xml…” statement from ERROR response

Page 66: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 66

The JCL needed to compile the converter• Upload all three files to the mainframe• Compile them in one deck of JCL using Enterprise COBOL at the

highest possible level– The driver program is the main program and should be compiled withPARM='LIST,NODYNAM,LIB,RENT,CICS(''COBOL3'')'

– The other programs are subprograms and should be compiled without the CICS option

– Reblock SDFHC370(DFHEILID) in a separate step– Link/bind with//SYSLIN DD DSN=&COPYLINK,DISP=(OLD,DELETE) // DD DSN=&OBJD,DISP=(OLD,DELETE) // DD DSN=&OBJI,DISP=(OLD,DELETE) // DD DSN=&OBJO,DISP=(OLD,DELETE) // DD * NAME CSCMMFGD(R)

Page 67: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 67

A Generic Message Adapter• The DFH$WSSS sample can easily be customised to call

any generated converter driver program– ASSIGN PROCESS() ACTIVITY()– RETRIEVE REATTACH EVENT()– GET CONTAINER("INPUT ") SET() FLENGTH()– LINK PROGRAM(converter_driver) COMMAREA() LENGTH()– DOCUMENT CREATE DOCTOKEN()– envelope := "<SOAP-ENV:Body><FindGiverResponse>"– DOCUMENT INSERT DOCTOKEN() TEXT() LENGTH()– DOCUMENT INSERT DOCTOKEN() FROM() LENGTH()– envelope := "</FindGiverResponse></SOAP-ENV:Body>"– DOCUMENT INSERT DOCTOKEN() TEXT() LENGTH()– DOCUMENT RETRIEVE DOCTOKEN() DATAONLY INTO() MAXLENGTH() LENGTH()

– PUT CONTAINER("OUTPUT ") FROM() FLENGTH()

Page 68: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 68

Debugging the SOAP Adapter and converter• A null in a message string will

give an error• There is a lot of pointer-and-

length errors lurking, like in the Web Interface at CICS 4.1

• An offset in an error message might be in the response rather than your request

• An AUXTRACE is the best way to understand the SOAP pipeline process, but you need some BTS understanding to interpret it

• On CICS 2.2 remember the required PTF's, which add new BTS features like MOVE CONTAINER and DEFINE PROCESS NOCHECK

• CODEPAGES IS ALWAYS AN ISSUE!

• We had a situation where the converter program abended, but the abend handling went into a loop

– It ate bunches of CPU, until we terminated it violently using TMON and it brought CICS down with it

• I would expect IBM to change the SOAP feature from BTS to standard EXEC CICS API at some future version

Page 69: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 69

An Application Transformation Scenario

BusinessProcessManager

Legacy IMS Application

DB2 Stored Procedure

HR/Payroll

Billing and Collection

SystemDiagnostics

DataTransformation

Database

SystemAdministration

Legacy CICS Application

BusinessService Directory

B2B Party Manager

Imaging

Document Production

Workflow

MIS

Business Administration

SmartCard WAP

PDA iDTV

VoiceXML …

Browser

Multi-channel adapter

Session manager

Security server

Screen flow managerContent management

External Party

External Party

Page 70: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 70

The New User Interfaces to the BASS/E Application

Page 71: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 71

Examining the CICS Application Transformation Toolbox

• Componentisation by hand (or by tool, if it exists)

• 3270 Bridge (Part of CICS)• Business Event Publisher

(Separately priced)• EXCI (External CICS Interface)

(Part of CICS)• CICS Transaction Gateway

(Separately priced)• CICS Web Support (Part of

CICS)• SOAP (Part of CICS)• Business Transaction Services

(Part of CICS)• And a large number of 3rd

party products

Page 72: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 72

In Conclusion• Legacy CICS applications can

be Web Enabled or adapted to an Enterprise Architecture using this toolbox

• You can save a lot of money and despair by transforming your valuable legacy this way instead of starting from scratch on a new platform

• You can do a lot with that toolbox

– If you are able to motivate and guide the developers

– And to convince management

Page 73: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 73

Some further reading• BTS

– CICS Business Transaction Services (Manual)– Deborin et al.: Business Process Model Implementation with CICS Business

Transaction Services• http://www.redbooks.ibm.com/redbooks/pdfs/sg245464.pdf

– Ian J. Mitchell: CICS Business Transaction Services - enabling robust extended transactions

• research.microsoft.com/~gray/ HPTS99/papers/Mitchell.pdf– Ibid.: CA1L: A WLM-enabled large request handler for CICS

• http://www-306.ibm.com/software/htp/cics/support/supportpacs• SOAP

– SOAP for CICS feature User’s Guide (Manual)• http://www.elink.ibmlink.ibm.com/public/applications/publications/cgibin/pbi.cgi

?CTY=US&FNC=SRX&PBL=SC34-6315– Teodoro Cipresso et al.: XML for the Enterprise - Providing an XML

Interface to a CICS Application• ftp://ftp.software.ibm.com/software/websphere/pdf/32511111.pdf

– David Clancy: CICS/TS 2.2 for z/OS• http://www.gse-nordic.org/secure/topics/cics/con2003/

Page 74: Automating the Donut Donation

CSC Proprietary 05/02/23 05:36 AM 5864_ER_WHITE.PPT 74

Any Questions?