Microsoft Word - CRSE0302.docx

Extending)a)CICS)Web)application)using)JCICS)

This%course%provides%Java%application%developers%with%a%guide%to%CICS%services,%demonstrating%how%to%

access%them%using%the%JCICS%API.%Topics%covered%include:%

• Fundamentals%of%using%the%JCICS%API%

• Using%JZOS%to%map%native%record-based%language%structures%to%Java%data%types%

• Communicating%with%other%CICS%programs%using%a%COMMAREA%

• LINKing%to%a%Java%application%deployed%in%Liberty%

• Accessing%CICS%resources,%for%example%VSAM%and%temporary%storage%queues%

• Managing%unit%of%work%scope%in%Java%

• Handling%errors%in%Java%

Students%should%be%familiar%with%the%concepts%and%techniques%discussed%in%"Developing%a%RESTful%

Web%application%for%Liberty%in%CICS"%before%taking%this%course.%

http://www.redbooks.ibm.com/abstracts/crse0302.html?Open%

) )

Section)1)Lecture)1)

Hello%and%welcome%to%the%CICS%Java%course%to%extend%a%CICS%web%application%using%the%JCICS%API.%My%

name%is%Ian%Burnett%and%I’m%part%of%the%CICS%development%team,%based%in%the%IBM%Hursley%lab%in%the%

UK.%

This%course%will%show%you%how%to%extend%your%knowledge%of%Java%development%in%CICS,%in%order%to%

produce%feature-rich%application s%that%u se%a%ra nge %of%CIC S%fea ture s.%

We%will%build%upon%knowledge%gained%in%the%“Developing%a%RESTful%Web%application%for%Liberty%in%

CICS”%course,%and%use%your%existing%development%environment%to%produce%more%complex%Java%

applications.%

We%will%start%the%course%by%looking%at%the%fundamental%concepts%you%need%to%understand%as%a%Java%

developer%when%interacting%with%CICS.%Using%these%fundamentals,%we%will%create%a%simple%piece%of%

code%to%invoke%C IC S%p ro g ra ms%from%th e %L ibe rt y%e n viro n ment.%%

After%we%have%understood%the%principles%of%invoking%other%CICS%programs%to%manipulate%data,%we%will%

look%at%se v era l%re s ou rc e s%a va ila b le%in %C IC S %an d %s tu d y%t h e%A P Is %u se d %to %in te ra ct %w ith %t ho s e %res o u rce s %

directly%from%Java.%

Another%aspect%of%CICS%applications%is%that%they%adhere%to%the%ACID%properties%of%a%transaction,%and%

the%ability%to%delineate %resou rce %up da tes%into %units%o f%wo rk%is%also%av ailab le%to%Java %app lication s.%W e %

will%look%at%how%CICS%provides%unit-of-work%support,%and%also%how%that%fits%with%the%JCICS%API.%

Developing%applications%that%are%enterprise-ready,%requires%ro bu st%pro gramming%practic es%to%

gracefully%handle%application%and%system%errors.%Our%final%topic%will%be%to%cover%the%concepts%and%

practicalities%of%handling%error%conditions%using%Java.%%

Our%code%samples%are%available%from%the%CICSdev%Github%repository%and%provide%fully-working%

examples%of%using%the%JCICS%APIs%that%we%will%be%discussing,%along%with%additional%supporting%

material.%

The%repository%show n %con tains %m an y%Java %sou rce%files%th at%us e%the %JAX-RS%interface,%in%order%to%

provide%a%simple%mechanism%of%invoking%Java%code%in%a%CICS%environment.%All%the%examples%use%the%

HTTP%GET%verb,%and%return%JSON%data.%RESTful%applications%would%typically%use%a %va rie ty %o f%H T T P %

verbs,%however%the%sample%code%is%not%intended%as%a%reference%for%the%development%of%RESTful%

applications,%but%merely%to%allow%easy%testing%using%a%simple%web%browser.%

During%this%course,%we%will%assume%that%you%have%a%Liberty%JVM%server%runn ing %in%CIC S.%Th e%sa m p le%

code%provided%requires%use%of%facilities%defined%by%the%JAX-RS%specification,%therefore%your%Liberty%

server.xml%file%should%be%configured%to%include%this%feature.%

We%will%also%assume%your%workstation%is%configured%with%a%development%environment%that%contains%

the%necessary %JCICS %Java%libra ries.%A%dy na m ic%we b%p rojec t%is%sufficient%to %pack age %the %cod e%sam p les,%

and%for%simplicity,%the%Liberty%drop-ins%directo ry%c an %b e %u se d %fo r%d e p loy ment,%altho u g h %CIC S %b u n d les %

may%be%used%if%required.%

Refer%to%the%“Developing%a%RESTful%Web%application%for%Liberty%in%CICS”%course%if%you%need%further%

informa tio n %o n %co n fig u rin g %Ja va %in %yo u r%C IC S %en v iro n m e n t.%

Thank-you%for%watching%this%course.%

Section)2)Lecture)1)

The%ability%for%programs%written%in%different%languag es%to %com m u nica te%an d %share %reso urce s%w hilst%

running%as%a%sing le%task%is%a%ke y%stren gth %of%CIC S.%As%w e%d iscu ssed %in%a%pre viou s%co urse %the %interfa ce%

to%a%CICS%program%is%defined%using%eithe r%a%CO M MAREA,%or%Ch an ne ls%and %Co ntain ers.%

Different%language s%de fine%th e%layo u t%of%the %CO M MAREA%or%co n tain er%us ing%lan gu a ge%sp ec ific%

structures.%%%

The%C%language%allows%fields%to%be%defined%with%data%types%such%as%characters,%integers%and%floating%

points.%

COBOL%programs%define%storage%layout%using%fields,%repre se n te d %b y%p ic tu re %cla u se s ,%to %sp e cify %th e %

different%numeric%and%character%data%types.%%%

Usually%these%language%structures%are%separated%out%into%a%source%file%referred%to%as%a%copybook%in%

COBOL,%or%as%a%header%file%in%the%C%language.%%In%practical%terms,%a%copy%book%often%represents%an%

entity%such%as%an%employee%or%a%stock%item.%

As%well%as%describing%interfaces,%a%language%structure%can%also%be%used%to%describe%the%layout%of%data%

stored%in%sequential%records%such%as%VSAM%files%or%Temporary%Storage%Queu es.%

To%interface%with%existing%programs%from%Java%we%need%a%means%of%accessing%data%within%structured%

records.%

When%using%the%JCICS%API%to%link%to%a%CICS%program%COMMAREA%data%is%passed%as%a%byte%array.%%

Using%the%standard%Java%language%constructs,%it%is%possible%to %c o ns tr uc t,%p o p u lat e,%a n d %re ad %fro m%this%

byte%array%directly.%However,%there%are%several%problems%with%this%approach.%

Firstly,%manual%byte%array%manipulation%is%time%consuming%to%develop%and%error%prone.%

Secondly,%a%record%may%contain%an%element%in%a%format%that%is %n o t%n at ive ly %su p p o rte d %b y%th e %

standard%Java%libraries.%For%example,%packed%decimal%fields%are%common%on %z/OS,%but%have%no %Java%

data%type%equivalent.%

Finally,%manipulation%of%individual%bytes%within%a%byte%array%does%not%fit%very%well%with%the%object-

oriented%programming%model%of%Java.%

The%solution%to%these%problems%is%to%generate%a%Java%bean%from%the%copybook%with%accessor%methods%

which%get%and%set%the%fields%automatically%converting%data%as%required.%%

The%generated%bean%provides%a%mapping%between%the%object-oriented%Java%programming%model,%and%

the%record%orien tate d%pro gra m m ing%m o de l.%%

We%will%cover%the%generation%of%these%beans%in%a%following%lecture.%

During%this%course,%it%will%be%useful%to%use%a%sample%copybook%to%demonstrate%how%and%where%byte%

arrays%are%used%in%the%JCICS%API.%%

The%sample%materials%provide%an%example%COBOL%copybook%that%defines%several%fields%in%an%80-byte%

record.%%

The%record%represents%an%entry%in%a%stock%warehouse.%In%our%application,%a%file%is%used%to%hold%

thousands%of%these%records,%representing%the%total%stock%inventory%for%a%warehouse.%

As%we%explore%the%JCICS%API%in%this%course,%we%will%be%using%the%sample%record%to%demonstrate%

communication%between %various%application%componen ts.% %

Looking%in%more%detail%at%the%80-byte%record%defined%in%the%sample,%we%can%see%several%fields.%

Firstly,%an%8-byte%field%is%used%as%the%part%ID,%it%represents%the%unique%key%for%this%record%within%the%

stock%database.%No%two%parts%within%the%database%ha ve%the%same %part%ID.%

A%second%8-byte%field%is%used%to%represent%the%ID%of%the%supplier%of%that%part.%This%would%likely%

reference%an%e ntry%in %ano the r%file,%wh ich%co n taine d%a %list%of%all%the%sup plie rs%use d.%

Each%part%has%a%unit%price,%that%is%defined%using%the%packed%decimal%format.%

Two%dates%are%stored%in%the%record%–%the%last%time%an%ord er%w as%pla ced ,%and %the %nex t%time%a n%ord er%

will%be%placed%for%this%part.%

A%numeric%field%contains%information%about%the%number%of%these%parts%that%are%currently%held%in%the%

warehouse.%

Finally,%a%description%of%this%part%is%stored%in%the%second%half%of%the%record%in%text%format.%

The%supporting%material%contains%another%sample%copybook%to%represent%a%supplier.%This%will%be%

useful%later%when%demonstrating%cases%where%relationships%exist%between%records.%

In%the%next%lecture,%we%will%look%at%the%JZOS%toolkit%and%how%the%record%generator%component%can%be%

used%to%map%from%our%sample%COBOL%copybook%to%an%object-oriented%Java%class.%

% %

Section)2)Lecture)2)

Java%records%are %use d%to %m ap %nativ e%rec ord %bas ed %lang ua ge %structures%to%Java%data%types.%%IBM%

supplies%two%Java%record%generation%tools.%

One%option%is%the%J2C%record%importer%provided%with%IBM%Developer%for%z%Systems%Enterprise%Edition%

within%the%J2C%feature.%

The%other%option%is%the%JZOS%Record%Generator%which%we%will%describe%in%th is%c o u rse .%

The%JZOS%record%generator%creates%a%Java%class,%based%on%a%copybook%from%COBOL%or%a%DSECT%from%

assembler.%In%our%example,%we%will%generate%a%Java%class%from%the%stock%part%copybook%that%we%

looked%at%in%the%previous%lecture.%Generating%a%Java%record%is%a%two-stage%process.%

The%first%stage%is%to%compile%the%COBOL%program%specifying%the%ADATA%parameter%to%generate%the%

ADATA%file.%

The%second%stage%is%to%run%the%JZOS%record%generator%using%the%ADATA%file%as%input,%to%generate%a%

Java%source%file%

The%Java%source%file%can%be%included%in%a%java%project%or%can%be%compiled%directly%into%a%Java%library.%

Includin g %th e %g enerated%Ja v a%s o u rc e %file%in%the%Java %ap p lic a tio n %p r o jec t%is %u se fu l%when%th e %ge n e ra te d %

code%needs%further%customization%such%as%ch anging%encod ings%for%specific%fields.%To%do%that%requires%

importin g %th e %g en e ra te d %Ja va %so u rc e %file%in t o %yo u r%E clip s e %de v elo p ment%env iro n m e n t,%a n d %th en %

adding%the%JZOS%library%to%the%project%b uild%p ath .%However,%if%the%COBOL%copybook%changes%and%

record%needs%to%be%regenerated%-%this%will%require%develo pm e nt%effo rt%to%u pd ate%th e%so urce %in%the %

Eclipse%development%environment.%%

An%alternative%approach%is%to%compile%the%generated%source%file%and%package%it%into%a%Java%archive,%or%

jar%file,%whic h %ca n %b e%in c lu d ed%with%the%Java%application.%This%use%of%a%compiled%jar%file%avoids%the%

requireme nt%to %add %the %JZO S%librarie s%to%the %Eclip se%w ork spa ce%a nd %allow s%m u ltiple%re cord s%to%b e%

packaged%within%a%single%library.%Another%advantage%of%this%approach%is%that%it%can%be%automated%and%

the%JAR%file%placed%in%a%re po sitory%fo r%dep en de nc y%m an ag em en t.%

The%sample%application%that%accompanies%this%course%follows%the%“compile%and%JAR”%approach.%It%

supplies%a%library%jar%file%containing%a%compiled%record%class%that%corresponds%to%the%stock%part%

copybook.%

In%this%section,%we%have%looked%at%how%the%interface%to%CICS%programs%can%be%defined,%and%how%Java%

applications%can%use%record%generators%to%map%to%this%interface.%We%then%showed%how%the%JZOS%

record%genera tor%co u ld%be %use d%to%b uild%a%Java%record%from%the%compiler%ADATA.%Finally,%we%showed%

how%to%package%the%Java%record%into%a%library%for%distribution%to%developers.%

In%the%n ex t%s e ct io n ,%w e %w ill%look%at%us in g%t h is%g e n er a te d %re co r d %w h e n %lin k in g %to %a %C IC S %C O B O L %

program%from%a%Java%application.%%

For%more%details%on%these%steps,%including%a%worked%example%with%complete%JCL,%have%a%look%at%the%

“Building%Java%records%from%COBOL%with%IBM%JZOS”%on%the %CICS %de velo pe r%cen ter. %

Thank%you%for%watching.%

% %

Section)3)Lecture)1)

In%the%“Developin g %a %RESTful%Web%application%for%Liberty%in%CICS”%course,%we%looked%at%the%concept%

of%a%CICS%program.%

A%program%is%a%unit%of%compiled%code%that%provides%application%logic,%and%can%be%developed%using%one%

of%many%languages%supported%in%the%CICS%environment,%including%Java.%%%

The%terminology%used%when%calling%from%one%CICS%program%to%another%is%known%as%a%link.%The%link%

command%passes%control%to%the%target%program%and%waits%for%it%to%complete.%

A%link%differs%from%a%Java%method%call%in%that%the%target%program%can%be%implemented%in%any%language%

supported%by%CICS%and%can%also%reside%on%a%different%CICS%system.%%

A%Java%method%call%however%is%considerably%more%lightweight%than%a%link%command%

When%using%the%JCICS%API,%first%create%an%instance %of%the %Prog ram%class,%and%spec ify%the%n am e %of%the%

target%program %usin g%the %setN am e ()%method.%%

To%issue%the%link%simply%invoke%the%link%method%on%the%program%object.%%Here%we%do%not%pass%any%

arguments%on%the%link%method%so%no%data%is%passed%to%the%target%program.%

When%communicating%from%one%program%to%another,%there%are%two%main%ways%to%pass%data%---%either%

through%the%u se%o f%a%com marea%-%or%through%the%use%of%channels%and%containers.%%

Now%let’s%look%at%passing%a%commarea%on%a%link%command%

A%commarea%is%an%area%of%memory%used%to%pass%data%between%two%programs.%%

From%a%CICS%perspective,%a%commarea%is%just%a%sequence%of%bytes,%CICS%does%not%attempt%to%format%

the%data%structu re%an d%just%fa cilitates%the %trans fer%of%the %data%between%the%programs.%%

The%data%structure%is%described%using%an%interface,%where%the%fields%are%defined%using%a%language%

specific%structure%such%as%a%COBOL%copybook%as%w e%discussed%in%the%previous%lecture.%%

For%a%Java%application%to%communicate%with%an%application%written%in%another%language%we%can%use%a%

byte%array%to%represent%the%commarea%and%to%hold%the%data%to%be%transferred.%As%noted%in%the%

previous%section,%generated%Java%classes%can%be%used%to%more%easily%construct%the%required%byte%

array.%

In%this%example,%we%look%at%passing%a%single%record%from%ou r%Java%application%into%an%existing%CICS%

program%using%the%COMMAREA%interface.%This%record%is%defined%by%the%standard%stock%part%record%

format%cove red %earlie r.%

When%using%the%JZOS%record%generator%tooling,%we%called%our%generated%class%“StockPart”.%So,%our%

first%task%is%to%create%an%ins tan ce%o f%this%clas s,%and %po p ulate %it%with %releva nt%d ata .%

The%JZOS%record%generator%tooling%defines%getter%and%setter%methods%in%the%Java%class,%the%names%of%

these%meth od s%correspond%to%the%fields%of%the%original%COBOL%copybook.%

Getter%and%Setter%methods,%otherwise%known%as%“accessor”%methods,%allow%a%Java%developer%to%use%

an%object-oriented%approach%when%building%a%record.%

Once%the%Java%object%has%been%instantiated,%we%can%convert%it%into%a%byte%array%using%the%

getByteBuffer()%method.%This%returns%a%serialized%version%of%the%structured%record%defined%in%the%

original%copybook.%

Now%that%we%have%the%data%ready,%we%can%use%this%to%link%to%the%target%program .%

We%create%a%new%instance%of%the%Program%class,%and%specify%the%name%of%the%target%program%that%we%

wish%to%LINK%to%using%the%setName()%method.%%

We%then%invoke%the%link%method%on%our%program%object%-%this%time%passing%the%StockPart%byte%array%%

On%successful%return%from%the%target%program,%any%updates%to%the%commarea%will%be%reflected%in%the%

byte%array.%%

Here,%we%take%the%updated%byte%array%and%construct%a%new%StockPart%object%to%represent%the%

returned%data .%Sub se qu en t%cod e%m a y%the n%rea d%va lue s%from %this%ne w ly-constructed%object%using%the%

accessor%methods.%

A%commarea%is%a%bidirectional%transfer%mechanism,%and%programs%can%use%this%area%to%send%any%

format%of%data %in%eith er%dire ction .%O ur%pre vio us %example%sent%a%record %in%the %Sto ckP art%format,%and%

received%a%record%in%the%same%format.%

%With%a%large%enough%data%area,%any%record%format%can%be%returned.%

In%this%ex a m p le ,%we%use%a%S to c kP a rt %o b jec t%t o %co n s tr u ct %a%b y te %a rra y %th a t%will%be%pas se d %to %a %ta rg e t%

program.%When%called,%that%program%will%look%up%the%sup plier%record%and%pop ulate%the%com ma rea%

with%a%record%format%detailing%the%supplier%of%that%part.%

Having%previously%created%a%suitable%JZOS%class%to%map%the%record%for%a%supplier%-%when%the%link%

method%completes%-%we%can%generate%a%new%instance%of%the%supplier%object%from%the%returned%byte%

array.%The%resulting%object%can%be%queried%for%the%supplier%information.%

CICS%offers%an%optimization%on%a%link%command%by%specifying%the%size%of%the%data%to%the%target%

program%-%a%benefit%also%available%from%the%JCICS%API.%%

As%an%example,%a%part%lookup%routine%may%only%need%a%8-byte%part%number%as%input,%but%will%require%

an%80-byte%commarea%to%return%the%data.%Specifying%the%optional%int%parameter%after%the%byte%array%

allows%the%caller%to%specify%the%data%length%used%on%the%send.%

In%this%ex a m p le ,%a %b yt e%a rr ay %o f%le n g th %8 0 %is %cre a te d %b y %th e %ca llin g %p ro g ra m,%but%the%datalength%is%

specified%as%8.%When%CICS%passes%control%to%the%target%program,%only%the%first%8%bytes%are%

transmitted.%Th e%remainder%of%the%80 -byte%commarea%is%padded%with%zeroes.%When%the%target%

program%returns,%all%80-bytes%are%sent%back%to%the%calling%program.%

This%optimization%can%be%used%to%reduce%CPU%and%response%times,%especially%where%large%commareas%

are%required%for%return%values%or%where%links%flow%between%CICS%systems.%

Recall%that%the%other%method%of%passing%data%from%one%program%to%another%is%by%Channels%and%

Containers.%A%channel%is%a%conduit%between%programs,%it%typically%holds%one%or%more%containers%to%be%

passed%between%the%programs.%A%container%is%a%named%block%of%data.%

Channels%and%containers%offer%the%advantage%that%more%than%32%KB%of%data%can%be%passed.%By%

contrast,%commareas%are%confined%to%a%32%KB%limit.%

Multiple%containers%can%be%passed%between%programs%within%a%channel.%A%channel%is%therefore%

analogous%to%a%parameter%list.%

A%worked%example%of%using%channels%and%containers%in%JCICS%is%available%in%the%“Developing%a%RESTful%

Web%application%for%Liberty%in%CICS”%course.%The%sample%materials%for%this%course%also%contain%an%

example%of%using%channels%and%containers%to%pass%data.%

This%lecture%has%looked%at%the%ways%in%which%the%JCICS%API%can%be%used%to%LINK%to%another%CICS%

program.%

The%sample%source%code%provided%with%this%course%has%examples%of%all%the%JCICS%commands%covered%

in%this%lect u re.%%

The%next%lecture%will%lo o k %at %h ow%we%can %lin k%fr o m %a %C IC S % program%into%a%Java%component%in%a%Liberty%

JVM%server %

% %

Section)3)Lecture)2)

WebSphere%Liberty%provides%a%Java%Enterprise%Edition%or%Java%EE %p la tfo rm,%and%is%d es ig n ed %to %h e lp %

developers%create%large-scale%enterprise%applications.%

Using%Link%to%Liberty,%any%CICS%program%can%now%call%Java%EE%applications%in%a%Liberty%JVM%server.%%

The%CICS%LINK%command%can%invoke%Plain%Old%Java%Objects%(POJOs)%that%have%been%deployed%inside%a%

Web%application...just%as%if%they%were%any%CICS%program.%%

To%achieve%this%seamless%LINK,%a%CICS%defined%Java%annotation%is%applied%to%a%Java%method%within%the%

Liberty%application.%The%annotation%indicates%that%the%method%should%be%exposed%as%the%entry%point%

for%a%CICS%Java%pro gra m%

When%the%application%is%installed%CICS%will%detect%the%annotation%meta-data%and%automatically%create%

and%install%a%PROGRAM%resource%for%each%entry%point%detected.%

Once%these%PROGRAM%resources%have%been%created,%then%a%CICS%application%written%in%any%language%

can%use%the%LINK%command%and%invoke%the%desired%Java%method%pass ing %a %ch a n n el%a s %th e %int e rfa ce .%

Note%that%a%commarea%cannot%be%passed%in%this%scenario.%

In%this%ex a m p le ,%we%have%a %cla ss %o r%P OJO%in%a%Web%application%that%exposes%the%getSupplierInfo()%

method%as%an%entry%point.%The%@CICSProgram%annotation%is%used%to%indicate%this%method%should%be%

made%available%as%a%PROGRAM%resource.%When%the%application%is%installed,%a%CICS%program%resource%

named%GETSUPPL%is%automatically%created,%and%is%ready%to%be%invoked.%

Data%is%passed%between%calling%program%and%the%Liberty%application%using%Channels%and%Containers.%%

Within%the%target%Java%method,%JCICS%is%used%to%get%a%reference%to%the%current%channel%and%to%obtain%

the%data%from %con tain ers%pro vid ed%b y%the %caller.%

Our%sample%code%provides%a%complete%implementation%of%the%get%supplier%info%method.%The%sample%

code%could%be%extended%to%use%Java%EE%capabilities%such%as %JAX-RS%client%API%to%request%information%

from%a%supp lier%us ing %a%rem o te,%RE ST ful%w eb %serv ice.% %

From%the%perspective%of%the%calling%COB O L%ap plica tion ,%it%has%used %th e %C IC S%L IN K %c o m mand%to %in vo ke %

a%named%program%passing%in%data%via%a%container,%and%received%a%re spo nse %usin g%a%CO B O L%struc ture .%%

The%POJO%component%in%the%web%application%was%able%to%receive%and%process%the%containers%and%

exploit%Java%EE7%functionality.%

In%this%se ct io n,%we%have%looked%at%how%we%can%link%to%other%CICS%programs%using%methods%on%the%

JCICS%Program%class.%%

Using%our%generated%record,%we%passed%data%to%existing%CICS%applications%using%the%commarea%

interface .%T he %a lte rn a tive %method%o f%p a s sin g %d at a%b e tween%pro gr ams%-%the %CICS %cha nn els%an d%

containers%support%-%was%covered%in%the%“Developing%a%RESTful%Web%application%for%Liberty%in%CICS”%

course.%

Finally,%we%looked%at%how%CICS%can%make%Liberty%applications%available%to%traditional%pro g ra ms,%using%

the%Link%to%Liberty%cap ab ility.%

In%the%n ex t%s e ct io n, %we%will%look%at%how%to%access%other%CICS%resources%using%the%JCICS%API.%

% %

Section)4)Lecture)1)

CICS%provides%access%to%a%range%of%resource%types.%Some%of%these%resources%like%Temporary%Storage%

Queues%are%unique%to%CICS,%while%others%such%as%VSAM%files%are%common%across%z/OS.%In%this%section,%

we%will%be%looking%at%accessing%these%resources%using%the%JCICS%API.%

We'll%come%to%the%CICS-specific%resources%shortly,%but%first%let’s%start%with%VSAM%files.%

In%CICS,%d a ta %management%ser vic es %a re %tra d it io n ally %k n o w n %a s %C ICS%file%control.%CICS%file%control%

offers%you%access%to%data%sets%that%are%managed%by%the%Virtual%Storage%Access%Method,%or%VSAM.%

Basic%direct-access%method,%or%BDAM,%data%sets%are%not%supported%by%the%JCICS%API,%so%this%lecture%

will%focus%on%VSAM%files.%

CICS%file%control%lets%you%read,%update,%add,%delete,%and%browse%data%in%VSAM%data%sets.%You%can%also%

access%CICS%shared%data%tables%and%coupling%facility%data%tables%using%the%file%control%APIs.%%

Files%may%be%shared%by%applications%within%a%CICS%region,%or%across%the%wider%z/OS%sysp lex.%

A%CICS%application%program%reads%and%writes%its%data%in%the%form%of%individual%records.%Each%read%or%

write%request%is%made%by%a%CICS%command.%%

To%access%a%record,%the%application%program%must%identify%both%the%record%and%the%data%set%that%

holds%it.%

There%are%several%methods%that%can%be%used%to%identify%a%record%–%which%one%to%use%depends%on%the%

type%of%VSAM%file%in%use.%We%will%look%at%the %differe nt%typ es%o f%VSA M %file%later.%

An%application%uses%a%CICS%file%resource%to%identify%a%data%set.%This%file%resourc e%ha s%a%u niq ue %name%

within%the%CICS%region,%allowing%the%application%to%remain%agnostic%of%the%underlying%dataset%name.%

It%is%not%n e ce ss a ry%f o r%a n %a p p lica tio n %t o %o p e n %o r%c lo se %a %file %ex p lic itly ,%C IC S%manage s%t h e%r es o u r ce %o n %

behalf%of%all%applications.%

In%this%dia g ra m,%an%app lica t io n %ac ce s se s%a %V S A M%file%using %C IC S %file %co n t ro l.%

The%application%identifies%the%data%set%to%be%used%by%referencing%the%CICS%FILE%resource%named%

STOCK1.%

The%STOCK1%file%resource%is%defined%to%reference%the%MVS%dataset%TEST%dot%DATA%dot%STOCK.%

The%application%could%later%be%deployed%into%a%different%system,%where%a%file%resource%of%the%same%

name%references%a%different%MVS%dataset.%

CICS%supports%access%to%the%following%types%of%VSAM%data%set:%

• Key-sequenced%data%set,%or%KSDS%

• Entry-sequenced%data%set,%or%ESDS%

• and%Relative%record%data%set,%or%RRDS%

A%key-sequenced%data%set%has%each%of%its%records%identified%by%a%key.%The%key%of%each%record%is%a%field%

in%a%pred ef ine d %p o sit ion %within%the %rec o rd .%E a ch %ke y %m u s t%be%unique%in%the%data%set.%

An%entry-sequenced%data%set%is%one%in%which%each%record%is%identified%by%its%relative%byte%address%or%

offset.%

A%relative%record%data%set%has%records%that%are%identified%by%their%relative%record%number%or%order.%

The%VSAM%datasets%topic%in%the%IBM%K n o w le d g e%C e n te r%h a s%a %more%com p re h e ns iv e%d e sc rip tio n %o f%

these%different%V SA M %da ta%sets .%

Our%example%will%use%a%key-sequenced%data%set.%%

Before%we%can%use%VSAM%files,%we%need%to%define%the%dataset%using%the%z/OS%utility%IDCAMS.%

The%example%shows%some%sample%input%to%the%IDCAM S%utility%to%define%a%VSAM%file%named%

TEST.DATA.STOCK.%We%will%use%this%dataset%in%our%example%to%store%stock%information%from%the%

StockPart%record%we%generated%using%JZOS%earlier.%

The%records%keyword%indicates%the%amount%of%space%that%the%disk%subsystem%needs%to%reserve%for%the%

data%set,%while%the%INDEXED%keyword%specifies%the%VSAM%data%set%is%to%be%used%for%key-sequenced%

data.%

The%KEYS%keyword%specifies%that%each%record%has%a%unique%key%that%is%eight%bytes%in%length%and%begins%

at%offset%zero.%This%matches%the%STOCK%PART%record%we%defined%earlier.%

Finally,%the%RECORDSIZE%keyword%specifies%that%on%average,%each%record%will%be%eighty%bytes%in%

length,%w it h%a %maximu m %le n g th %o f%e igh ty %b yt es .%While%VSA M%files%supp o rt %va ria ble-le ng t h%r ec o rd s,%

our%simple%application%only%uses%fixed-length %re co rd s .%

For%the%full%example,%see%the%accompanying%sample%project%materials%in%Github.%

As%described%earlier,%a%CICS%application%is%abstracted%from%the%physical%datasets%it%uses%by%means%of%a%

CICS%FILE%resource.%In%order%to%use%our%sample%application,%you%will%need%to%define%and%install%a%FILE%

definition%into%the%CICS%region.%

For%this%example,%most%of%the%defaults%will%be%suitable,%with%some%exceptions.%

The%file%resource%definition%requires%a%name%of%up%to%eight%characters%–%the%samp le%cod e%u ses%th e%

SMPLXMPL%name.%%

If%you%do %n ot%specify%the%file%as%a%D D %s ta te ment%in%yo u r %C IC S %st ar tu p %jo b ,%y o u %w ill%n e e d %to %s p e cify %th e %

physical%dataset%name%using%the%DSNAME%attribute%on%the%definition.%

To%fully%demonstrate%the%JCICS%file%control%API,%you%should%set%all%of%the%add,%browse,%delete,%read,%

and%update%attributes%to%yes,%otherwise%CICS%will%throw%an%exception%when%the%application%attempts%

to%perform%an %op era tion%th at%is%no t%perm itted .%

Now%we%are%going%to%develop%the%we b%ap plicatio n%to %acce ss%the %VS AM %file.%

The%sample%class%VSAM%KSDS%file%resource%provides%a%number%of%methods%to%demonstrate%the%

various%aspects%of%accessing%a%VSAM%file.%

The%simplest%of%these%methods%is%the%“write%new%record”%method%which%creates%a%new%stock%part%and%

adds%it%to%the%VSAM%file.%

As%with%the%examples%in%the%“Developing%a%RESTful%Web%application%for%Liberty%in%CICS”%course,%we%

use%a%simple%RESTful%interface%to%invoke%the%Java%code.%

The%CICSApplication%class%specifies%a%base%application%path%of%“rest”,%therefore%any%RESTful%resources%

accessed%in%this%web%application%will%use%this%string%as%a%root%URI.%

The%VSAM%KSDS%file%resource%c la ss %sp e cifie s %a%relative%resource%URI%of%ksds%using%the%Path%

annotation,%while%the%write%new%record%method%specifies%a%path%of%“write”%relative%to%the%parent%

resource.%

For%the%write%new%record%method,%we%would%therefore%use%the%URI%“rest/ksds/write”%relative%to%the%

base%URI%of%the%application%when%installed%into%CICS.%

Only%the%HTTP%GET%verb%is%recognized%in%this%application,%as%indicated%by%the%GET%annotation%on%the%

method.%

The%write%new%record%method%returns%a%Stock%Part%Co llection %ob ject,%w hic h%is%serialize d%to %JSO N%as %

directed%by%the%Produces%annotation%on%the%class.%The%Stock%Part%Collection%object%is%a%simple%

wrapper%object%that%contains%a%list%of%Stock%Part%objects.%

To%create%a%record%suitable%for%insertion%into%the%VSAM%file,%the%generate%method%in%the%stock%part%

helper%class%creates%an%instance%of%the%JZOS-generated%Stock%Part%class%and%po pu la te s %it%w it h %sa mple%

data.%

The%write%new%record%method%takes%the%generated%record%and%converts%this%to%a%byte%array%using%the%

JZOS%get%byte %bu ffer%m eth o d. %

Another%method%in%the%stock%part%helper%class%extracts%the%record%key%as%a%byte%array.%Recall%that%the%

key%for%the%stock%part%record%is%eight%bytes%in%length%and%begins%at%offset%zero.%The%helper%class%

obtains%the%byte%array%from%the%Stock%Part%object%and%extracts%the%first%eight%bytes%as%a%new%byte%

array.%

In%this%ex a m p le ,%we%are%accessing%a%key-sequenced%dataset,%or%KSDS%file.%%To%reference%this%file%using%

JCICS,%we%create%an%instance%of%the%KSDS%class%and%specify%the%name%of%the%CICS%file%resource.%

The%write%method%on%the%KSDS%class%takes%two%byte%arrays%as%parameters%–%the%key%and%the %reco rd%

for%writing.%

The%CICS%transaction%would%automatically%be%committed%on%normal%completion%of%the%CICS%task,%but%

as%a%simple%demonstration%of%managing%units%of%work,%the%sample%application%uses%the%Task%commit%

method%to%explicitly%complete%the%current%unit%of%work.%%

Finally,%th e %q u er y%file %method%is %in vo ke d ,%w h ic h %ret u rn s%a n %in st an c e%o f%t h e%s to c k%p a rt%c o llec tio n %c las s. %

The%query%file%method%performs%a%file%browse%operation,%starting%at%the%very%first%record%in%the%file,%

and%reading%each%record%into%memory.%Each%record%is%converted%to%a%stock%part%object%and%added%to%

the%stock%part%collec tion%ins tan ce.%W h en %serialized%to%JSO N ,%this%prov ides%a%sim p le%m ea ns%o f%view ing%

the%contents%o f%the%sa m ple %VSA M %file%an d%ho w %it%is%affected %by%ea ch %file%contro l%op eratio n.%

For%clarity,%the%necessary%error-handling%logic%has%not%been%included%here,%but%is%provided%in%the%

sample%code.%We%will%cover%error-handling%later%in%the%course.%

The%updateRecord()%method%provides%an%example%of%updating%a%record%in%a%VSAM%file.%

Firstly,%the%KSDS%file%is%referenced%by%creating%a%new%instance%of%the%KSDS%class,%as%previously%done%in%

the%write%new %reco rd%m e tho d.%

To%read%data%from%a%file,%a%record%holder%object%is%required.%The%read%for%update%method%on%the%KSDS%

class%is%then%called,%passing%in%three%param ete rs.%

The%first%parameter%is%the%key%of%the%record%that%we%wish%to%read%from%the%VSAM%file.%In%this%case,%we%

supply%a%key%of%all%zeroes,%created %u s in g %a %method %in %t h e %st o c k %p a rt %h e lp e r%c la s s .%A %k e y %o f%a ll%z e roes%is%

used%in%our%application,%simply%to%obta in %th e %firs t%re co rd %in %th e %a b se n ce %o f%re a l%da t a.%

The%second%parameter%specifies%that%the%application%will%read%the%record%with%a%key%equal%to,%or%

greater%than,%the%key%supplied.%

The%final%parameter%is%the%record%holder%instance,%which%will%be%used%to%receive%the%data%that%results%

from%the%VS AM%file%read%operatio n. %

On%successful%completion%of%the%read%for%update%method,%the%record%holder%instance%will%contain%a%

byte%array%representing%the%record%in%the%data%set,%as%located%by%the%specified%key.%The%get%value%

method%extracts%this%byte%array,%and%it%is%passed%to%the%constructor%of%the%generated%stock%part%class.%

A%second%stock%part%instance%is%created%using%the%generate%method%we%covered%earlier.%The%part%id,%

or%key,%from%the%read%record%is%copied%into%the%newly-generated%record.%This%step%is%used%as%a%simple%

demonstration%of%where%business%logic%would %a m e n d %va lu e s%in %a %re al - world%application.%

We%then%update%the%record%in%the%VSAM%file%by%calling%the%rewrite%method,%supplying%the%full%record%

as%a%byte%array.%

Note%that%for%a%rewrite%operation,%we%do%not%need%to%supply%the%key,%as%this%was%established%on%the%

previous%read%for%update%operation.%

Finally,%we%explicitly%call%the%task%commit%method%to%release%any%locks%we%hold%against%the%file.%

When%executing%the%sample%code,%repeatedly%accessing%the%rest/ksds/update%method%by%pressing%

refresh%in%your%bro w ser%w ill%sho w %the%first%rec ord %in%the %file%bein g%up da ted %with %new %sa m p le%da ta.%

The%delete%record%method%in%the%VSAM%KSDS%file%resource%class%provides%an%example%of%de le tin g %a%

record%in%a%VSA M %file.%

The%flow%of%the%method%is%very%similar%to%the%update%record%example,%with%a%read%for%update%

operation%finding%the%correct%record,%and%then%the%delete%method%being%called%to%delete%the%record%

from%the%file.%

In%this%lecture,%we%have%looked%at%how%w e%can%use%the%JCICS%API%to%access%VSAM%KSDS%files,%using%our%

generated%JZOS%class%to%provide%an%object-oriented%means%of%accessing%structured%records%on%disk.%

Many%of%the%concepts%covered%here%are%equally%applicable%to%ESDS%and%RRDS%files.%See%the%JCICS%

Javadoc%do cu m en tatio n%fo r%a%complete%referenc e%on %the %synta x%req u ired%to %acce ss%th es e%typ es%o f%

VSAM%files.%

In%the%n ex t%le c tu re ,%we%will%loo k%a t%h ow%Java%a p p lica tions%can%a cc e ss %C IC S %te m porary%sto r ag e %q u e u es .%

% %

Section%4%Lecture%2%

CICS%temporary%storage%queues,%or%TSQs,%are%a%means%of%storing%a%sequence%of%data%items.%

Data%in%a%TSQ%can%be%stored%in%main%memory,%on%disk,%known%as%auxiliary%TSQs,%or%shared%via%the%

sysplex%coupling%facility.%

The%data%items%in%a%TSQ%%have%a%maximum%size%of%just%under%thirty%two%kilobytes,%and%can%be%accessed%

in%any%ord e r %

TSQs%are%referenced%using%a%name%of%up%to%16%characters%in%length.%%They%can%be%defined%as%being%

recoverable%o r%no n-recoverable%CICS %reso urce s.%

Temporary%storage%queues%do%not%need%to%be%defined%in%advance%of%an%application%using%them,%and%

can%be%used%to%share%data%across%applications.%

Support%for%temporary%storage%queues%is%provided%in%the%JCICS%API%by%using%the%TSQ%class.%

In%our%sa mple%we %ar e %u sin g %a %T SQ%from%w it h in %a %C IC S%Liberty%Web-application%and%because%HTTP%

requests%are%state less,%w e'll%nee d%so m e%m e an s%of%p ersisting %the%T SQ %na m e%ac ross %m ultiple %HT TP%

requests.%

To%provide%a%simple-to-use%method%of%accessing%the%same%temporary%storage%queue%from%a%browser%

across%multiple%requests,%the%queue%n am e %is%stored %in%an %HT TP%se ssion %ob ject.%

Every%time%a%browser%issues%a%G ET %requ es t%against%the%temporary%storage%resource%class,%the%get%

queue%method%extracts%the%queue%name%from%the%HTTP%session%object,%and%returns%a%JCICS%TSQ%

object%that%corresponds%to%th e%co rrect%q ue ue %for%tha t%brow s er%sess ion.%

Examining%the%flow%in%more%detail,%the%first%time%a%browser%accesses%the%sample%application,%it%issues%

an%HTTP%GET%request%against%the%rest%slash%tsq%slash%write%URI,%and%has%no%cookie%token%to%send%to%

the%server.%The%ge t%que ue %m eth od %in%the%a pp lication %finds%n o%co ok ie%has %bee n%se nt,%and %he nc e%no %

HTTP%session%is%present.%

The%generate%queue%name%method%is%invoked%to%create%a%new,%unique%queue%name.%This%queue%

name%is%stored%in%an%HTTP%session%object,%which%is%persisted%automatically%by%the%Liberty%runtime.%

The%write%new%record%method%will%write%an%element%to%this%new%queue,%and%then%return%to%the %client.%

When%the%Liberty%container%sends%the%JSON%response%back%to%the%browser,%it%also%includes%an%HTTP%

session%cookie%as%part%of%the%flow.%

Subsequent%requests%from%the%browser%will%flow%this%HTTP%session%cookie%to%the%application,%and%this%

cookie%is%used%by%the%Liberty%server%as%a%key%to%retrieve%the%HTTP%session%object%that%corresponds%to%

the%browser%instance%making%the%request.%

Before%we%examine%the%JCICS%API%in%detail,%let’s%take%a%brief%look%at%some%of%the%sample%code’s%helper%

methods.%

The%name%of%the%queue%used%by%our%sample%application%is%created%by%the%generate%queue%name%

method.%This%creates%a%queue%name,%bas ed%o n%a%kn o w n%pre fix%and %the %curre nt%tim e.%

The%sample%temporary%storage%resource%class%provides%examples%of%accessing%a%TSQ%using%the%JCICS%

API,%%

The%write%new%record%method%demonstrates%how%to%write%a%single%element%to%a%temporary%storage%

queue.%%

Here%we%use%the%get%queue%method%to%obtain%an%instance%of%the%JCICS%TSQ%class.%

This%TSQ%object%references%the%CICS%temporary%storage%queue%that%is%in%use%by%the%current%browser%

session,%using%the%mechanism%described%earlier.%

A%sample%record%is%created%using%the%stock %part%h elp er%class %we %cove red %w he n%loo kin g%at%VS AM%file%

access,%and%a%byte%array%is%obtained%using%the%JZOS%get%byte%buffer%method.%

Writing%a%single%element%to%a%TSQ%is%achieved%by%simply%calling%the%write%item%method,%passing%the%

data%to%be%written%as%a%byte%array.%

In%a%simila r %m a n n e r%t o %th e %V S A M%examp le s ,%a%s to c k%p a rt %co lle c tio n %o b je ct %is%r et u rn e d %b y %th e %method ,%

and%is%serialised%by%the%Liberty%server%as%a%JSON%response.%

This%collection%object%is%created%by%the%query%queue%method,%which%performs%a%browse%across%the%

queue,%adding%each%queue%element%to%the%collection.%

There%are%two%important%points%to%note%from%the%query%queue%method.%

%The%first%is%that%elements%in%a%temporary%storage%queue%are%numbered%from%element%one,%unlike%

many%constructs%you%may%be%used%to%in%Java.%

The%second%is%that%items%are%read%from%a%TSQ%using%an%Item%Holder%instance.%This%item%holder%object%

performs%a%similar%function%to%the%record%holder%we%discussed%earlier%for%VSAM%files.%

As%in%the%previous%VSAM%e x ample,%the%u p d a te %rec o rd %method%will%update %th e %firs t%e lement%in%th e %

queue.%

The%get%queue%method%is%again%used%to%obtain%the%TSQ%corresponding%to%the%current%browser%

session,%and%a%new%sample%stock%part%record%is%created%using%the%stock%part%helper%class.%

The%TSQ%is%updated%through%the%use%of%the%rewrite%item%method%in%the%TSQ%class,%which%takes%two%

parameters%–%the%item%index%and %the%n ew %da ta%to%w rite%to %the%q ueu e.%

After%updating%the%queue,%our%query%queue%method%is%called%to%return%the%contents%of%the%queue%as%a%

JSON%respo n se.%

Individu a l%e lements%ca n n o t%b e %d e le te d %fro m%a%temp orary%stor ag e %q u e u e%–% it %is%o n ly %po s sib le %to %d e le te %

an%entire%queue.%

The%delete%method%in%the%TSQ%class%takes%no%arguments%and%deletes%the%corresponding%temporary%

storage%queue.%

The%delete%queue%method%in%our%sample%code%gives%a%simple%example%of%obtaining%a%TSQ%object%and%

then%deleting%the %un de rlying%q ue ue.%

In%this%lec tu re %we%have%c o ve re d %t h e%b a s ic%c o n ce p t s%o f%a %te mporary %st o ra ge %q u e u e ,%an d%looked %at %h o w%

we%can%use%the%JCICS%API%to%access%these%queues%from%Java.%

Thank%you%for%watching.%

Section%4%Lecture%3%

One%of%the%fundamental%concepts%of%transaction%processing%is%that%resource%updates%adhere%to%the%

atomicity,%consistency,%isolation,%and%durability%principles,%commonly%known%as%the%ACID%properties%

of%a%transaction.%

Resources%accessed%by%a%program%are%managed%within%a%transactional%scope%known%as%a%unit%of%work.%

All%recoverable%resources%accessed%within%a%single%unit%of%work%are%updated%according%to%the%ACID%

principles.%

A%unit%of%work%may%either%complete%successfully,%known%as%a%commit,%or%unsuccessfully,%known%as%a%

roll%back.%

In%a%CICS %ta s k,%a n %ac tiv e %u n it%o f%work%is%alw a y s%p r es e n t.%

A%unit%of%work%begins%automatically%at%the%start%of%a%CICS%task,%before%control%is%passed%to%the%

application.%Upon%successful%completion%of%a%CICS%task,%the%unit%of%work%is%automatically%committed.%

If%a%CICS%ta s k%t er m inates%abn o r mally,%then %th e %ac tiv e %u n it%o f%work%is%ro lled-back%and%any%updates%to%

recoverable%re sou rce s%are%u nd on e.%

Updates%to%recoverable%CICS%resources%made%from%Java%applications%will%be%subject%to%the%same%unit%

of%work%constraints%as%other%CICS%programs.%

It%is%also%p o ss ib le %fo r%a n %a p p lica tion%to%ma n g e %th e %u n it%o f %w o r k%b o u n daries.%

The%JCICS%commit%and%rollback%methods%in%the%Task%class%can%be%used%to%complete%the%current%unit%of%

work%and%update%resources%accordingly.%

Once%the%current%unit%of%work%has%been%completed%in%CICS,%a%new%unit%of%work%is%automatically%

created,%ensuring%that%any%resource%updates%always%occur%within%a%unit%of%w o rk.%

Where%large%numbers%of%resources%are%being%updated%in%long-running%tasks,%if%the%a pp licatio n%de sign %

permits,%it%is%recommended%that%units%of%work%are%committed%periodically.%This%will%reduce%the%

number%of%outstanding%locks%that%are%held%by%the%application,%and%potentially%improve%overall%system%

throughpu t.%

The%write%new%record%method%in%our%VSAM%sample%shows%an%example%of%explicitly%committing%the%

current%CICS%unit%of%work.%

In%this%se ct io n ,%w e %h a ve %lo o k ed %a t%t h e %ch a ra ct e rist ics %o f%several%CICS%resources,%and%ho w%to%access%

them%using%th e%JCIC S%AP I.%

In%this%lec tu re %we%covere d %t h e%C IC S %s u p p o rt %fo r%u n it s%o f %w o r k,%a n d %h o w%applicat io n s%c a n %co n t ro l%t h e%

scope%of%updates%to%recoverable%resources.%

In%the%n ex t%s e ct io n ,%w e %w ill%look%at%ho w%Java%applications%ca n%su cce ssfu lly%ha nd le%ap plica tion %an d%

system%errors,%in%order%to%produce%more%robust%app lications.%

Our%sample%application%code%provides%examples%of%accessing%key-sequenced%VSAM%files,%CICS%

temporary %storag e%qu eu es ,%and%a lso%CIC S%tran sient%data%queues%using%JCICS.%

Thank%you%for%watching.%

Section%5%Lecture%1%

It%is%impo r ta n t%to %provide%g o o d %e rro r-handling%logic%in%enterprise-class%software%to%gracefully%handle%

a%range%of%application%and%system%problems.%

In%this%se ct io n ,%w e %w ill%look%at%how%Java%handles%errors%in%general,%then%apply%that%knowledge%to%the%

JCICS%API.%

During%execution%of%an%application,%various%error%conditions%may%arise.%These%error%conditions%may%

have%many%root%causes,%but%fundamentally%they%can%be%categorised%into%three%main%types:%expected%

errors,%unexpected%errors,%and%fatal%errors.%

Expected%errors%are%conditions%that%can%be%reasonably%foreseen%by%an%application%developer.%For%

example,%attempting%to%read%a%non-existing%record%from%a%VSAM%file%is%likely%to%be%a%condition%that%

the%application%is%exp ec ted %to%ha nd le.%

Unexpected%errors%are%conditions%that%may%occur,%but%are%not%normally%expected%to%be%handled%by%

the%application.%Fo r%exa m p le,%a%prog ram %m ay %attem p t%to%ac cess %an%ele m en t%of%a%Java %array %wh ich %

does%not%exist.%This%proba bly %re p re se n ts %a%p ro g ra mming%er ro r,%an d %a s%a %re su lt ,%th e%a p p lica tio n %is %

likely%to%be %in %a n%in d e te rminate%sta te .%

Fatal%errors%are%the%most%serious%of%all%error%conditions,%and%usually%represent%a%situation%from%which%

an%application%is%unlikely%to%be%able%to%recover.%An%example%of%a%fatal%error%occurring%would%be%if%the%

Java%virtual%mac hin e%faile d%to%lo ad %a%Java %class %requ ired %by%an %ap plica tion .%

Error%conditions%in%the%Java%language%are%managed%using%the%exception%mechanism.%

If%a%Java%m e th o d %e n c ounters%an%error%condition,%then%a%special%Java%obje ct%called %a%Th row ab le%is%

created%to%capture%the%state%of%the%current%thread%at%the%time%of%the%error,%and%this%object%is%

propagated%to%the%caller%of%the%current%method%–%a%process%known%as%throwing%an%exception.%

Correspondingly,%handling%the%error%condition%is%known%as%catching%an%exception.%A%calling%method%

uses%a%try%keyword%to%indicate%the%scope%of%the%error%handling%logic.%

The%Java%language%specifies%that%the%objects%used%when%propagating%exceptions%must%be%instances%of%

a%type%which%extends%the%Throwable%class.%The%Throwable%class%itself%has%two%direct%subclasses%–%

Exception%and%Error.%There%are%many%sub-classes%of%Exception.%However,%the%RuntimeException%

subclass%is%a%special%case%and%is%not%classified%as%a%checked%exception%as%it%represents%unexpected%

runtime%erro rs.%

Together,%the%checked%exception,%runtime%exception,%and%error%classes%represent%error%conditions%in%

Java%code%tha t%corre sp on d%to %the%ex pe cte d,%un exp ec ted ,%and %fatal%erro r%cate go ries %that%we%covered%

earlier.%

In%Java’s%e rro r %h a n d lin g %m e c h an is m,%expecte d %e rr o rs %ex te n d %t h e%E x ce p t io n %cla s s,%a n d %ar e %kn o wn%as%

checked%exceptions.%

The%Java%language%specifies%that%any%method%which%can%throw%a%checked%exception%must%declare%this%

as%part%of%the%method%signature,%using%the%throws%keyword.%

Any%Java%code%which%calls%a%method%declared%as%throwing%a%checked%exception%must%either%provide%

logic%to%ca tc h %th e %ch e ck e d%e x ce p tio n ,%o r%ad d %t he %e xc e pt io n %to %it’s%o wn%meth o d %sig n a tu re ,%in%o r de r%t o %

propagate%the%exception%further%up%the%stack.%

The%constraints%on%checked%exceptions%are%enforced%at%compile%time,%and%failure%to%adhere%to%the%

specification%will%result%in%a%compilation%error.%

Unexpected%error%conditions%are%represented%by%Java%classes%which%extend%the%Runtime%exception%

class,%and%are%known%as%unchecked%exceptions.%

Unchecked%exceptions%are%not%subject%to%the%compile%time%checking%mandated%for%checked%

exceptions,%although%they%can%be%caught%if%required.%

Fatal%error%conditions%are%represented%by%Java%classes%wh ic h%e x te n d %th e%E r ro r%cla ss .%It%is %co n s id ere d %

poor%programming%practice%to%catch%any%exceptions%that%are%subclasses%of%the%Error%class,%as%these%

rarely%represent%a %con ditio n%from%which%the%ap plica tion %w ill%be%ab le%to%rec ove r.%

Now%lets%take%a%look%at%how%CICS%error%handling%is%managed%for%COBOL%and%other%high%level%

languag e s.%%

These%languages%that%use%the%EXEC%CICS%API%have%three%choices%when%handling%error%conditions:%on%a%

per-command%basis,%using%a%condition%handler,%or%using%an%abend%handler.%

If%a%CICS%com m a nd %pro du ce s%an %erro r,%then %it%will%first%try%to%return %a%resp o ns e%co de %to%the %

application%using%the%data%area%supplied%in%the%RESP%parameter%of%the%CICS%command.%

If%a%RESP %p ar a m e te r%has%not%b e en%supplie d ,%th e n %C IC S %w ill%s e ar ch %fo r %a n %ac tiv e%condition%handler.%

Condition%handlers%are%registered%in%advance%using%the%EXEC%CICS%HANDLE%CONDITION%command,%

and%perform%some%form%of%application-specific%recovery%operation.%

If%no%activ e %co n d it io n %h a n d ler %is%f o u n d ,%th e n %C IC S %w ill%a b n o r m a lly %en d ,%o r %abend%the%task.%There%are%

many%types%of%CICS%abends%defined,%each%corresponding%to%a%specific%error%condition,%and%abends%are%

classified%by%their%four-character%abend%code.%

When%an%abend%occurs,%CICS%will%search%for%an%active%abend%handler%that%matches%the%generated%

abend.%Similar%to%condition%handlers,%an%abend%handler%routine%is%registered%in%advance%using%an%

EXEC%CICS%HANDLE%ABEND%command.%

If%an%active %a b e n d %h a n d ler %ca n n o t %b e%located,%th e n %C IC S%will%abno rmally%term in a te %th e %c u rre n t %ta sk ,%

which%in%turn%will%rollback%any%unc om mitted%update s%to%reco ve rab le%reso urc es%in%th e%cu rren t%unit%o f%

work.%

Now%lets%consider%how%CICS%errors%map%to%the%JCICS%API.%

The%JCICS%exception%hierarchy%includes%unchecked%exceptions,%checked%exceptions,%and%fatal%errors.%%

The%key%to%the%mapping%between%CICS%errors%and%the%JCICS%exception%hierarchy%is%understanding%

where%these%exceptions%could%be%thrown,%how%they%map%to%the%CICS%response%codes,%and%what%

action%you%should%take%as%an%application%developer.%%

Let's%start%by%looking%at%checked%exceptions.%

Here%we%see%the%key%classes%involved%in%the%JCICS%exception%hierarchy.%Most%JCICS%methods%are%

defined%as%throwing%checked%exceptions,%and%these%checked%exceptions%represent%the%majority%of%

conditions%that%an%application%may%be%expected%to%handle.%

Each%error%condition%from%a%CICS%command%is%ma p pe d %to %a n %e xc ep t ion ,%and %this%exception%is%a%

subclass%of%the%CICS%condition%exception.%

As%an%example,%the%CICS%command%to%read%an%element%from%a%temporary%storage%queue%may%return%

an%ITEMERROR%condition%to%indicate%the%queue%did%not%contain%the%element%requested.%

In%the%JC IC S %A P I,%an %e le m e n t %is%re a d %from%the%T S Q %u s in g %th e %re a d %ite m %method.%This%method%

signature%declares%it%may%throw%(amongst%others)%an%Item%Error%Exception ,%which%is%the%JCICS %AP I%

equivalent%of%the%ITEMERROR%condition.%

See%the%query%queue%method%in%the%temporary%storage%resource%sample%class%to%see%how%the%

ITEME R R O R %a n d %Q IDERR%co n d itio n s %a re %h an dled%as%ex p ec te d %e rr o rs ,%w h ile %any%other%e rr o r%c o n d itio n %

results%in%a%failure%of%the%request,%

There%are%only%a%few%unchecked%exceptions%in%the%JCICS%API,%and%they%all%extend%the%CICS%runtime%

exception%class.%

All%of%these%exceptions%represent%conditions%within%CICS%that%should%not%be%handled%by%an%

application.%%

Java%code%run nin g%in %C IC S %sh o u ld %n o t%ca tc h %th e se %e xc ep t io ns ,%e ith er %ex p licit ly%in %a %ca tc h %b loc k ,%or%

implicitly%b y %ca tc h in g%a %s u pe rc la ss %of %th e se %ex c ep tio n s .%In st ea d ,%th e y%s ho u ld %b e %allo wed%to%pro p a ga t e%

out%of%the%Java%environment%and%back%to%CICS,%where%the%unit%of%work%can%be%rolled%back.%

Note%included%in%this%list%is%the%AbendException%which%represents%an%abend%of%a%CICS%task,%and%should%

only%be%caught%if%you%wish%to%develop%your%own%abend%handling%routine.%

It%impo rta n t %to %st re ss %th a t%having%a%tr y%b lo c k%t h a t%ca t ch e s%a n y %superclass%of%the%java%dot%lang%dot%

exception%class%should%not%be%used%when%invoking%the%JCICS%API.%

It%impo rta n t %to %st re ss %th a t%having%a%tr y%b lo c k%t h a t%ca t ch e s%a n y %su p e rc la ss %o f%th e %ja va %d o t %lan g%dot%

exception%class%should%not%be%used%when%invoking%the%JCICS%API.%

<<Note%to%video%team.%You%will%probably%need%to%pause%the%speaker%here%for%a%short%while%–%the%

complexity%of%this%slide%wasn’t%really%thought%about%when%preparing%the%script.%Thankfully%I%am%o ff-

screen.>>%

The%Java%Error%class%represents%a%fatal%error%condition%in%the%JVM%that%should%not%be%caught%by%an%

application.%

The%same%applies%to%the%CICS%error%class,%which%extends%java%dot%lang%dot%error.%An%application%

should%not%attempt%to%handle%a%fatal%CICS%error,%but%instead%allow%the%exception%to%propagate%back%to%

the%CICS%environ m e nt%to%a llow %full%recove ry%to%ta ke%p lace.%

If%a%Java%ex ce p t io n %su c h %a s%a %n u ll%p o in t er %ex c ep t io n %is%a llo wed%to%p ro p a g at e%out%of%the %Ja v a%c o d e %an d %

back%to%the%JVM%server%runtime,%this%is%generally%surfaced%as%one%of%the%CICS%abends%starting%with%AJ.%

Most%commonly,%an%uncaught%exception%will%result%in%an%AJ04%abend,%and%the%current%unit%of%work%

will%be%rolled-back.%

It%is%also%p o ss ib le %fo r%a %Ja va %a p p lica t io n %to %is su e %a n %abend%dire c tly ,%u sin g %o n e %o f%th e %a b e n d %o r%fo r ce %

abend%methods%in%the%Task%class.%%This%is%similar%in%concept%to%the%throwing%of%Java%exception,%as%it%

can%allows%a%CICS%abend%handler%to%take%control%of%error%processing.%

The%various%forms%of%the%abend%method%allow%an%application%to%optionally%specify%an%abend%code%or%if%

a%dump%is%required.%

The%force%abend%methods%provide%the%same%options%as%their%equivalent%abend%methods,%but%are%

equivalent%to%specifying%the%CANCEL%keyword%on%the%EXEC%CICS%ABEND%command.%Invoking%a%force%

abend%method%will%always%terminate%the%task%abnormally,%and%overrides%any%existing%abend%handlers%

that%have%bee n%es tablis he d %fo r%t he %t as k.%

In%our%sa mple%Vsa mKsdsFile R es o u rc e %%cla ss %we%use%th e%f o llo w in g %t ry%c a tc h %b lo ck %to %h a n d le %C IC S %er ro r %

conditions%when%deleting%items%from%a%VSAM%file%

%The%RecordNotFoundException%is%a%checked%exception%but%is%a%normal%situation%on%the%initial%

browse,%as%so%can%be%ignored%when%browsing%the%file.%

All%other%CICS%condition%exception%are%un%expected,%and%in%this%situation%we%throw%the%JAX-RS%

Interna lSe rv e rE rr o rE x ce p tio n%which%will%cause%a %H T T P %s er ve r%e rr o r%to%be%retu rn e d %to %t h e%c a ller .%

This%lecture%has%introduced%the%concept%of%checked%and%unche cked%exception s%in%Java,%along%with%the%

throwing%an d%ca tchin g%m ec han ism %use d%to %pro pag ate %the%ex cep tion %ob jects.%%

We%have%seen%how%the%JCICS%API%maps%CICS%error%condition%values%to%exceptions,%and%how%CICS%

abends%are%processed.%

Remember%it%is%acceptable%for%an%application%to%catch%and%handle%CICS%condition%exceptions,%but%it%

strongly%recommend ed%that%CICS%runtim e%exception s%are%allowed%to%propag ate%back%to%the%CICS%

environment.%

Finally,%we%looked%at%how%Java%exceptions%are%mapped%to%abends%in%CICS%programs,%along%with%the%

APIs%required%to%issue%abends%directly%from%Java%code.%

Thank%you%for%watching.%

Section%6%Lecture%1%

In%this%co u rs e ,%w e %h a ve %e xt en ded%our%k n o wledge%o f%Ja va %d evelopm ent%in%CICS.%

We%covered%some%of%the%fundamental%concepts%you%need%to%understand%as%a%Java%developer%when%

interactin g %w ith %C IC S ,%an d %t hen%used%these%fundamentals%to%invoke%CICS%program s%fro m %the%Lib erty%

environment.%

We%then%looked%at%the%use%of%the%JCICS%API%to%access%CICS%resources%including%VSAM%files%and%TSQs,%

and%examined%how%Java%applications%can%participate%in%CICS%unit%of%work%support.%

Finally,%we%looked%at%the%concepts%and%practicalities%of%handling%error%conditions%using%Java.%%

Many%code%samples,%including%the%ones%used%in%this%course,%are%available%on%our%CICS%Dev%git%hub%

site.%

This%concludes%our%course%around%extending%a%CICS%web%application%using%JCICS.%

Thank-you%for%watching.%