Automating the Donut Donation

CSC Proprietary 11/19/15 07:00 PM 5864_ER_WHITE.PPT 1
S31CV. Automating the Donut
Donation. A CICS BTS Prototype
Michael Erichsen, CSC Denmark, merichse@csc.com
GSE Nordic Technical Conference, May 2004, Stockholm, Sweden

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

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

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

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

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

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

The Business Problem

The Original Business Process Mapping
DFHINITIAL
Define Input
Events
Define
Timer1
TIMER1
POPPED
Find Giver
Timer1
GIVER
FOUND
Send Mail1
MAIL1
SENT
Wait for
acceptance
Timer2
BASSFILE
Lookup
TIMER2
POPPED
Send Mail2
SMTP Server
BASS/E
Main Panel
SMTP Server
MAIL2
SENT
Wait for
Completion
BASSE
GIVEN
Complete
Process
BASS/E
Main Panel
BASS/E
Absence Panel
AbsenceHandler
GIVER
ACCEPTED
Define
Timer2
BASS/E
Main Panel

The Activity Structure
Mapping to CICS Transaction Programs
Root
Activity
Find
Giver
Send Mail
Thursday
Send Mail
Friday
Absence
Panel
Main
Panel
Start
Process
• 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

Version 1, 1995: A Manual System

Version 2, 1997: A CICS VSAM 3270 Application

Version 3, 1999: CICS Web Support and 3270 Bridge

Version 4, 2003: BTS and e-mails

Version 5, 2004: SMS added

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

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

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();

The Main Loop maps the Business Process
DFHINITIAL
Define Input
Events
Define
Timer1
TIMER1
POPPED
Find Giver
Timer1
GIVER
FOUND
Send Mail1
MAIL1
SENT
Wait for
acceptance
Timer2
BASSFILE
Lookup
TIMER2
POPPED
Send Mail2
SMTP Server
BASS/E
Main Panel
SMTP Server
MAIL2
SENT
Wait for
Completion
BASSE
GIVEN
Complete
Process
BASS/E
Main Panel
BASS/E
Absence Panel
AbsenceHandler
GIVER
ACCEPTED
Define
Timer2
BASS/E
Main Panel

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();

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

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

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;

The Donor is required to Accept Responsibility
Link to BASS/E
Web Page
(CICS 3270 Bridge)
E-mail sent
from CICS

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();

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

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;

Pseudo-Conversations and BTS Processes
Pseudo-conversation BTS Process
If no commarea is passed
Send an empty map
If DFHINITIAL
Define input events
Start first activity
Else if PF3
Clear screen and return control
to CICS dispatcher
Else if all activities have ended
Complete the process by
cleaning up and return control to
Scheduler Services
Else
Receive a map with input data
Process data using business
logic
Send a map with output data
Else
Check activity
Get container
Process data using business
logic
Put container
Run another activity

This was the Sequential Flow through the Process
DFHINITIAL
Define Input
Events
Define
Timer1
TIMER1
POPPED
Find Giver
Timer1
GIVER
FOUND
Send Mail1
MAIL1
SENT
Wait for
acceptance
Timer2
BASSFILE
Lookup
TIMER2
POPPED
Send Mail2
SMTP Server
BASS/E
Main Panel
SMTP Server
MAIL2
SENT
Wait for
Completion
BASSE
GIVEN
Complete
Process
BASS/E
Main Panel
BASS/E
Absence Panel
AbsenceHandler
GIVER
ACCEPTED
Define
Timer2
BASS/E
Main Panel

But What if the Donor Used the Absence Panel?
• The Absence Panel has been
made BTS-aware by adding
these statements
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();

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

DFHINITIAL
Define Input
Events
Define
Timer1
TIMER1
POPPED
Find Giver
Timer1
GIVER
FOUND
Send Mail1
MAIL1
SENT
Wait for
acceptance
Timer2
BASSFILE
Lookup
TIMER2
POPPED
Send Mail2
SMTP Server
BASS/E
Main Panel
SMTP Server
MAIL2
SENT
Wait for
Completion
BASSE
GIVEN
Complete
Process
BASS/E
Main Panel
BASS/E
Absence Panel
AbsenceHandler
GIVER
ACCEPTED
Define
Timer2
BASS/E
Main Panel
An Absence Notification makes us jump Backwards

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.

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 Reattached by event TIMER1_POPPED
• ....BAS3 20040317064848 Activity FIND_GIVER
• ....BAS2 20040317064849 Next event: GIVER FOUND
• ....BAS2 20040317064849 Reattached by event GIVER_FOUND
• ....BAS4 20040317064850 Activity SEND_MAIL1
• ....BAS2 20040317064853 Next event: MAIL 1 SENT

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
BROWSETOKEN();
– EXEC CICS ENDBROWSE
PROCESS BROWSETOKEN();
PROCESSTYPE("BASSE ");
– EXEC CICS CANCEL
ACQPROCESS;

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

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.

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.

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.

Lesson Learned:
Be careful with the Local Request Queue

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

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

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

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

Adding Bridge Support

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

• 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-keys
are suppressed
Fields at these positions
are suppressed
JavaScript to run
when HTML is
loaded

• 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

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=”xxxx@xxx.com">'
• 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
<img name=…

Customised 3270 Bridge HMTL

Adding SOAP Support

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>

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;
};

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

WebSphere Studio Enterprise Developer

WebSphere Studio Enterprise Developer
Must be right
e.g. 277
Name used
in generated
COBOL source

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

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 with
PARM='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 *

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()

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

An Application Transformation Scenario
Business
Process
Manager
Legacy IMS ApplicationLegacy IMS Application
DB2 Stored ProcedureDB2 Stored Procedure
HR/PayrollHR/Payroll
Billing and CollectionBilling and Collection
System
Diagnostics
System
Diagnostics
Data
Transformation
Data
Transformation
DatabaseDatabase
System
Administration
System
Administration
Legacy CICS ApplicationLegacy CICS Application
Business
Service Directory
Business
Service Directory
B2B Party ManagerB2B Party Manager
ImagingImaging
Document ProductionDocument Production
WorkflowWorkflow
MISMIS
Business AdministrationBusiness Administration
SmartCardSmartCard WAPWAP
PDAPDA iDTViDTV
VoiceXMLVoiceXML ……
BrowserBrowser
Multi-channel adapter
Session manager
Security server
Screen flow manager
Content managementContent management
External PartyExternal Party
External PartyExternal Party

The New User Interfaces to the BASS/E Application

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

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

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/

Any Questions?

Automating the Donut Donation

Recommended

Recommended

More Related Content

Viewers also liked

Viewers also liked (15)

Similar to Automating the Donut Donation

Similar to Automating the Donut Donation (20)

More from Michael Erichsen

More from Michael Erichsen (11)

Recently uploaded

Recently uploaded (20)

Automating the Donut Donation