Tutorial 5

Database Access with CICS Tutorial overview

In Tutorial 4 we created a simple relational DB2 database. We now will create a CICS program that accesses this database. Our application program will again consist of 2 parts: a C-program for the business logic (assuming the existence of the database created in tutorial 4) and a BMS-program for the presentation logic (Tutorials 14 and 15 will demonstrate how to do the presentation logic in Java, generating a modern graphical user interface). The business logic will contain SQL calls. They will have to be converted into native DB2 API calls with the help of a precompiler prior to compiling the business logic program with a C compiler. These steps are shown in Fig. 1 .

JCL-Script Sourceprogram SQL-Precompiler Program with native DB2 API CICS-Precompiler Program with native CICS API C-Compiler Object program Link Executable binary
Fig. 1 : Individual steps to generate executable binaries We will create a source program in C "PRAKT20.CICSDB2.TEST01(CPROG020)" (business logic), which includes EXEC SQL-atatements. We will also generate 3 JCL scripts. The first JCL script PRAKT20.CICSDB2.TEST01(BMSJCL) (see Fig. 5 and 6) contains the presentation logic. It contails a single mapset "S01SET" with a single map "MAP001" (usually a mapset contains several maps, see tutorial 2, section 3). As shown in Fig. 1, the second JCL script "PRAKT20.CICSDB2.TEST01(PCOMPJCL)" implements a precompiler run. All EXEC SQL statements in the C program are replaced by native DB2 API calls. The third JCL script "PRAKT20.CICSDB2.TEST01(STARTJCL)" calls the C compiler. The CICSPrecompiler translates the EXEC CICS statements into native CICS API calls. The resulting pure C program is compiled and linked; the result are executable binaries. In our tutorial all steps are done using TSO.

PCOMPJCL

STARTJCL

Integration into CICS requires the following steps: 1. Define the mapset using "CEDA DEFINE MAPSET(S01SET) GROUP(PRAKT20)" 2. Define the C program using "CEDA DEFINE PROG(CPROG020) GROUP(PRAKT20)" 3. Define the name of the Transaction ID (TRID) using "CEDA DEFINE TRANS(D020) GROUP(PRAKT20)" 4. Define our DB2 data base and table using "CEDA DEFINE DB2ENTRY" 5. After these steps CICS knows the mapset S01SET with its map MAP001, the executable machine program which was generated using CPROG020, the TRID "D020", and the database and table which are to be accessed. CICS also knows that these are part of group "PRAKT20" (which was automatically generated during step 1 . We install these components using "CEDA INSTALL GROUP(PRAKT20)" . After we have done this we can call the CICS transaction using the TRID "D020" (see Fig. 40). Our transaction will be executed. It will read the columns "VORNAME" and "NACHNAME" from the table we created in tutorial 4 and output them on the users display. (see Fig. 41). Try to avoid doing the tutorial repeatedly. This may cause the "CEDA INSTALL GROUP(PRAKT20)" command to generate the error message "INSTALL UNSUCCESSFUL" . If this happens you will have to contact our system administrator.

Doing the Tutorial

We logon as a TSO user and open the DSLIST panel.

Menu Options View Utilities Compilers Help -----------------------------------------------------------------------------DSLIST - Data Sets Matching PRAKT20 Row 1 of 13 Command - Enter "/" to select action Message Volume ------------------------------------------------------------------------------PRAKT20 *ALIAS PRAKT20.CICS.TEST01 SMS001 PRAKT20.CICSDB2.TEST01 SMS001 PRAKT20.DBRMLIB.DATA SMS001 PRAKT20.ISPF.ISPPROF SMS001 PRAKT20.LIB SMS001 PRAKT20.SPFLOG1.LIST SMS001 PRAKT20.SPUFI.IN SMS001 PRAKT20.SPUFI.OUT SMS001 PRAKT20.TEST.C SMS001 PRAKT20.TEST.CNTL SMS001 PRAKT20.TEST.LOAD SMS001 ***************************** End of Data Set list ****************************

Command ===> F1=Help F3=Exit

Scroll ===> PAGE F5=Rfind F12=Cancel

Fig. 2 : DSLIST-Panel Fig. 2 shows what we will need. The data sets PRAKT20.CICSDB2.TEST01 PRAKT20.SPUFI.IN PRAKT20.DBRMLIB.DATA have been generated as part of tutorial 4. Data set "SPUFI.OUT" has been generated automatically by the SPUFI subsystem and contains the translated version of SPUFI.IN. The data set "PRAKT20.DBRMLIB.DATA" is still empty; it will be filled during execution of the SQL precompiler. "PRAKT20.CICSDB2.TEST01" is still missing and has to be allocated (please do so, use the same parameters as in tutorial 1, Fig. 21). In addition, PRAKT20.LIB may be too small. Please erase it and allocate it again, using the following parameters: Primary quantity: 34 Kbyte, Secondary quantity: 8 Kbyte, Directory blocks: 2, Record format: FB, Record length: 80, Block size: 320, Data set name type : PDS . To delete a dataset proceed as follows : ISPF Primary Options Menu -> (3) Utility Selection Panel -> (2) Dataset Utility, then mark the dataset to be erased with a D (Delete entire data set).

Menu RefList RefMode Utilities LMF Workstation Help -----------------------------------------------------------------------------Edit Entry Panel ISPF Library: Project . . Group . . . Type . . . Member . .

. . . .

PRAKT20 CICSDB2 TEST01 BMSJCL

. . .

. . .

. . .

(Blank or pattern for member selection list)

Other Partitioned or Sequential Data Set: Data Set Name . . . Volume Serial . . . (If not cataloged) Workstation File: File Name . . . . . Initial Macro . . Profile Name . . . Format Name . . . Data Set Password Command ===> F1=Help . . . . . . . . Options / Confirm Cancel/Move/Replace Mixed Mode Edit on Workstation Preserve VB record length

F3=Exit

F10=Actions

F12=Cancel

Fig. 3 : Generating Member "BMSJCL" Using the "Edit Entry Panel" we generate a new member "BMSJCL" (see Fig. 3) . Press Enter .
File Edit Confirm Menu Utilities Compilers Test Help ------------------------------------------------------------------------------EDIT PRAKT20.CICSDB2.TEST01(BMSJCL) - 01.00 Columns 00001 00072 ****** ***************************** Top of Data ****************************** ==MSG> -Warning- The UNDO command is not available until you change ==MSG> your edit profile using the command RECOVERY ON. '''''' '''''' '''''' '''''' '''''' '''''' '''''' '''''' '''''' '''''' '''''' '''''' '''''' '''''' '''''' '''''' Command ===> Scroll ===> PAGE F1=Help F3=Exit F5=Rfind F6=Rchange F12=Cancel

Fig. 4 : empty Edit-Entry-Panel Our CICS application is to consist of a BMS program (Mapset) for the "Presentation Logic" and a C program for the Business Logic. We start with the Mapset BMSJCL.

File Edit Confirm Menu Utilities Compilers Test Help ------------------------------------------------------------------------------EDIT PRAKT20.CICSDB2.TEST01(BMSJCL) - 01.00 Columns 00001 00072 ****** ***************************** Top of Data ****************************** ==MSG> -CAUTION- Profile changed to NUMBER OFF (from NUMBER ON STD). ==MSG> Data does not have valid standard numbers. ==MSG> -CAUTION- Profile changed to CAPS ON (from CAPS OFF) because the ==MSG> data does not contain any lower case characters. ==MSG> -Warning- The UNDO command is not available until you change ==MSG> your edit profile using the command RECOVERY ON. 000001 //PRAKT20B JOB (),CLASS=A,MSGCLASS=H,MSGLEVEL=(1,1),NOTIFY=&SYSUID 000002 //ASSEM EXEC DFHMAPS,MAPNAME='S01SET',RMODE=24 000003 //SYSUT1 DD * 000004 S01SET DFHMSD TYPE=MAP,MODE=INOUT,LANG=C,STORAGE=AUTO,TIOAPFX=YES 000005 * MENU MAP. 000006 MAP001 DFHMDI SIZE=(24,80),CTRL=(PRINT,FREEKB) 000007 DFHMDF POS=(9,13),ATTRB=(ASKIP,NORM),LENGTH=20, X 000008 INITIAL='VORNAME ' 000009 DFHMDF POS=(9,34),ATTRB=(ASKIP,NORM),LENGTH=20, X 000010 INITIAL='NACHNAME ' 000011 VNAM1 DFHMDF POS=(11,13),ATTRB=(ASKIP,NORM),LENGTH=20 000012 NNAM1 DFHMDF POS=(11,34),ATTRB=(ASKIP,NORM),LENGTH=20 Command ===> Scroll ===> PAGE F1=Help F3=Exit F5=Rfind F6=Rchange F12=Cancel

Fig. 5 : The BMS program, part 1 The complete BMS program uses two panels (screeens). Using the F8- or F7- keys we scroll between the two panels.
File Edit Confirm Menu Utilities Compilers Test Help ------------------------------------------------------------------------------EDIT PRAKT20.CICSDB2.TEST01(BMSJCL) - 01.01 Columns 00001 00072 000013 VNAM2 DFHMDF POS=(12,13),ATTRB=(ASKIP,NORM),LENGTH=20 000014 NNAM2 DFHMDF POS=(12,34),ATTRB=(ASKIP,NORM),LENGTH=20 000015 VNAM3 DFHMDF POS=(13,13),ATTRB=(ASKIP,NORM),LENGTH=20 000016 NNAM3 DFHMDF POS=(13,34),ATTRB=(ASKIP,NORM),LENGTH=20 000017 VNAM4 DFHMDF POS=(14,13),ATTRB=(ASKIP,NORM),LENGTH=20 000018 NNAM4 DFHMDF POS=(14,34),ATTRB=(ASKIP,NORM),LENGTH=20 000019 DFHMSD TYPE=FINAL 000020 END 000021 /* 000022 // ****** **************************** Bottom of Data ****************************

Command ===> SUB F1=Help F3=Exit

Scroll ===> PAGE F5=Rfind F6=Rchange F12=Cancel

Fig. 6 : The BMS program, part 2 The lines 7 to 10 define a heading which consists of 2 fields. The two fields are initialized with the values VORNAME and NACHNAME (I assume you guessed by now this means first name and last name in German). The lines 11 to 18 define 8 fields which will accept the first name and last name of 4 persons which we select from our DB2 data base.

We enter "SUB" on the command line and press Enter. In addition to the translation of the BMS program, a template will be stored in the member "PRAKT20.LIB (S01SET)" for use by our business logic program to be written in C.

13.32.50 JOB02043 $HASP165 PREPARE ***

ENDED AT N1

MAXCC=0 CN(INTERNAL)

Fig. 7 : Job processing Confirmation We wait until JES has translated our BMS program (maybe 30 seconds). Pressing Enter produces the panel showm in Fig. 7. "MAXCC=0" confirms the translation was successful. Pressing Enter returns the last screen. We press the F3 key two times. We take a look at the member "PRAKT20.LIB(S01SET)" . It is shown in Fig. 8. Depending on which code page your 3270 emulator uses, the presentation may look somewhat different (remember the Sqare Bracket anomaly, Fig. 3 in tutorial 3).

union { struct { char short int char char short int char char short int char char short int char char short int char char short int char char short int char char short int char char } map001i; struct { char short int char char short int char char short int char char short int char char short int char char short int char char short int char char short int char char } map001o; } map001; dfhms212; dfhms3; vnam1a; vnam1o20; dfhms4; nnam1a; nnam1o20; dfhms5; vnam2a; vnam2o20; dfhms6; nnam2a; nnam2o20; dfhms7; vnam3a; vnam3o20; dfhms8; nnam3a; nnam3o20; dfhms9; vnam4a; vnam4o20; dfhms10; nnam4a; nnam4o20; dfhms112; vnam1l; vnam1f; vnam1i20; nnam1l; nnam1f; nnam1i20; vnam2l; vnam2f; vnam2i20; nnam2l; nnam2f; nnam2i20; vnam3l; vnam3f; vnam3i20; nnam3l; nnam3f; nnam3i20; vnam4l; vnam4f; vnam4i20; nnam4l; nnam4f; nnam4i20;

Fig. 8 : Sceleton generated by submitting PRAKT20.CICSDB2.TEST01(BMSJCL)

This is the code stored in "PRAKT20.LIB(S01SET)". It covers 4 screens. The code includes a "Union", consisting of 2 "Structures" .We use it as a template for our C code business logic program. We call again the Edit Entry panel.
Menu RefList RefMode Utilities LMF Workstation Help -----------------------------------------------------------------------------Edit Entry Panel ISPF Library: Project . . Group . . . Type . . . Member . .

. . . .

PRAKT20 CICSDB2 . . . TEST01 CPROG020

. . .

. . .

(Blank or pattern for member selection list)

Other Partitioned or Sequential Data Set: Data Set Name . . . Volume Serial . . . (If not cataloged) Workstation File: File Name . . . . . Initial Macro . . Profile Name . . . Format Name . . . Data Set Password Command ===> F1=Help . . . . . . . . Options / Confirm Cancel/Move/Replace Mixed Mode Edit on Workstation Preserve VB record length

F3=Exit

F10=Actions

F12=Cancel

Fig. 9 : Generating the Member "CPROG020" We create an additional member "PRAKT20.CICSDB2.TEST01(CPROG020)" ( Fig. 9 ). It is to store our business logic. Press Enter .
File Edit Confirm Menu Utilities Compilers Test Help ------------------------------------------------------------------------------EDIT PRAKT20.CICSDB2.TEST01(CPROG020) - 01.01 Columns 00001 00072 ****** ***************************** Top of Data ****************************** ==MSG> -CAUTION- Profile changed to CAPS OFF (from CAPS ON) because data ==MSG> contains lower case characters. ==MSG> -Warning- The UNDO command is not available until you change ==MSG> your edit profile using the command RECOVERY ON. 000001 #include <memory.h> 000002 #include <stdlib.h> 000003 #include <//'PRAKT20.LIB(S01SET)'> 000004 000005 EXEC SQL INCLUDE SQLCA; 000006 EXEC SQL BEGIN DECLARE SECTION; 000007 char vname20; 000008 char nname20; 000009 EXEC SQL END DECLARE SECTION; 000010 000011 main() 000012 { 000013 EXEC SQL DECLARE C1 CURSOR FOR 000014 SELECT VNAME,NNAME FROM PRAKT20.TAB020; Command ===> Scroll ===> PAGE F1=Help F3=Exit F5=Rfind F6=Rchange F12=Cancel

Fig. 10 : Business Logic Program, Part 1

We enter the source code as shown in Fig. 10 and 11 . The code covers 2 screens. Using the F8 and F7 screens we scroll between the 2 screens.
File Edit Confirm Menu Utilities Compilers Test Help ------------------------------------------------------------------------------EDIT PRAKT20.CICSDB2.TEST01(CPROG020) - 01.01 Columns 00001 00072 000015 EXEC SQL OPEN C1; 000016 EXEC SQL FETCH C1 INTO :vname, :nname; 000017 memcpy(map001.map001i.vnam1i,vname,20); 000018 memcpy(map001.map001i.nnam1i,nname,20); 000019 EXEC SQL FETCH C1 INTO :vname, :nname; 000020 memcpy(map001.map001i.vnam2i,vname,20); 000021 memcpy(map001.map001i.nnam2i,nname,20); 000022 EXEC SQL FETCH C1 INTO :vname, :nname; 000023 memcpy(map001.map001i.vnam3i,vname,20); 000024 memcpy(map001.map001i.nnam3i,nname,20); 000025 EXEC SQL FETCH C1 INTO :vname, :nname; 000026 memcpy(map001.map001i.vnam4i,vname,20); 000027 memcpy(map001.map001i.nnam4i,nname,20); 000028 EXEC SQL CLOSE C1; 000029 000030 EXEC CICS SEND MAP("map001") MAPSET("s01set") ERASE; 000031 000032 000033 } Command ===> Scroll ===> PAGE F1=Help F3=Exit F5=Rfind F6=Rchange F12=Cancel

Fig. 11 : Business Logic Program, Part 2 Lines 000007 and Zeile 000008 in "PRAKT20.CICSDB2.TEST01(CPROG020)" contain again the special character "" . Depending on which code page your 3270 emulator uses, the presentation may look somewhat different (remember the Sqare Bracket anomaly. I suggest you consult Fig. 3 in tutorial 3, including the text below Fig. 3 . During the translation of the mapset PRAKT20.CICSDB2.TEST01(BMSJCL) the member "S01SET" in data set "PRAKT20.LIB" has been created, containg a template for our C program. In tutorial 3 we copied it manually into our C program. Here we do it differently. Line 000003 contains the statement: #include <//'PRAKT20.LIB(S01SET)'> It replaces the copying of the template code. After having entered all the code we return to the Edit-Entry-Panel

Prior to running the script in Fig. 11, two precompiler runs are necessary, see Fig. 1 .

Menu RefList RefMode Utilities LMF Workstation Help -----------------------------------------------------------------------------Edit Entry Panel ISPF Library: Project . . Group . . . Type . . . Member . .

. . . .

PRAKT20 CICSDB2 . . . TEST01 PCOMPJCL

. . .

. . .

(Blank or pattern for member selection list)

Other Partitioned or Sequential Data Set: Data Set Name . . . Volume Serial . . . (If not cataloged) Workstation File: File Name . . . . . Initial Macro . . Profile Name . . . Format Name . . . Data Set Password Command ===> F1=Help . . . . . . . . Options / Confirm Cancel/Move/Replace Mixed Mode Edit on Workstation Preserve VB record length

F3=Exit

F10=Actions

F12=Cancel

Fig. 12 : Creating the member PCOMPJCL The first precompiler run translates all EXEC SQL statements into native DB2 API calls. We generate a new member "PCOMPJCL" (Fig. 12) to store the JCL script which stores the precompiler call. Press Enter .

File Edit Confirm Menu Utilities Compilers Test Help ------------------------------------------------------------------------------EDIT PRAKT20.CICSDB2.TEST01(PCOMPJCL) - 01.02 Columns 00001 00072 ****** ***************************** Top of Data ****************************** ==MSG> -Warning- The UNDO command is not available until you change ==MSG> your edit profile using the command RECOVERY ON. 000001 //PRAKT20P JOB (),CLASS=A,MSGCLASS=H,MSGLEVEL=(1,1),NOTIFY=&SYSUID, 000002 // TIME=1440 000003 //PCOMP EXEC PROC=DSNZEY 000004 //DBRMLIB DD DSN=PRAKT20.DBRMLIB.DATA(CPROG020),DISP=OLD 000005 //SYSCIN DD DSN=PRAKT20.CICSDB2.TEST01(OUT),DISP=SHR 000006 //SYSLIB DD DSN=PRAKT20.CICSDB2.TEST01,DISP=SHR 000007 //SYSIN DD DISP=SHR,DSN=PRAKT20.CICSDB2.TEST01(CPROG020) ****** **************************** Bottom of Data ****************************

Command ===> SUB F1=Help F3=Exit

Scroll ===> PAGE F5=Rfind F6=Rchange F12=Cancel

Fig. 13 : DB2 Precompiler JCL Script We generate the JCL script shown in Fig. 13, which calls the EXEC SQL precompiler. The data set "PRAKT20.DBRMLIB.DATA" so far contains no member. Upon execution of the JCL script the precompiler will have generated a member "PRAKT20.DBRMLIB.DATA(CPROG020)" . We enter SUB on the command line. We wait for JES to complete the job and press Enter.

17.12.04 JOB02051 $HASP165 DB2PCOMP ENDED AT N1 ***

MAXCC=0 CN(INTERNAL)

Fig. 14 : Successful Job Completion "MAXCC=0" indicates, command execution was successful. Press Enter .

Menu RefList RefMode Utilities LMF Workstation Help -----------------------------------------------------------------------------Edit Entry Panel ISPF Library: Project . . Group . . . Type . . . Member . .

. . . .

PRAKT20 CICSDB2 . . . TEST01 STARTJCL

. . .

. . .

(Blank or pattern for member selection list)

Other Partitioned or Sequential Data Set: Data Set Name . . . Volume Serial . . . (If not cataloged) Workstation File: File Name . . . . . Initial Macro . . Profile Name . . . Format Name . . . Data Set Password Command ===> F1=Help . . . . . . . . Options / Confirm Cancel/Move/Replace Mixed Mode Edit on Workstation Preserve VB record length

F3=Exit

F10=Actions

F12=Cancel

Fig. 15 : Generating the Member "STARTJCL" Next we generate a member "STARTJCL" . It stores a JCL script that calls these functions: the CICS precompiler, the C compiler, and the linker. Press Enter.
File Edit Confirm Menu Utilities Compilers Test Help ------------------------------------------------------------------------------EDIT PRAKT20.CICSDB2.TEST01(STARTJCL) - 01.04 Columns 00001 00072 ****** ***************************** Top of Data ****************************** ==MSG> -Warning- The UNDO command is not available until you change ==MSG> your edit profile using the command RECOVERY ON. 000001 //PRAKT20S JOB (),CLASS=A,MSGCLASS=H,MSGLEVEL=(1,1),NOTIFY=&SYSUID, 000002 // TIME=1440 000003 //*************************** 000004 //* TRANSL/COMP/LINKEDIT 000005 //*************************** 000006 //COMP EXEC PROC=CTOCICS,REG=0M 000007 //TRN.SYSIN DD DISP=SHR,DSN=PRAKT20.CICSDB2.TEST01(OUT) 000008 //LKED.SYSIN DD * 000009 INCLUDE DB2LOAD(DSNCLI) 000010 NAME CPROG020(R) 000011 //********************* 000012 //* BIND 000013 //********************* 000014 //BIND EXEC PGM=IKJEFT01 000015 //STEPLIB DD DISP=SHR,DSN=DSN510.SDSNEXIT 000016 // DD DISP=SHR,DSN=DSN510.SDSNLOAD Command ===> Scroll ===> PAGE F1=Help F3=Exit F5=Rfind F6=Rchange F12=Cancel

Fig. 16 : JCL Script STARTJCL (Screen #1) "STARTJCL" covers 3 screens (Fig. 16 18). We use the F8 and F7 keys to scroll foreward and backward.

File Edit Confirm Menu Utilities Compilers Test Help ------------------------------------------------------------------------------EDIT PRAKT20.CICSDB2.TEST01(STARTJCL) - 01.04 Columns 00001 00072 000017 //DBRMLIB DD DISP=OLD,DSN=PRAKT20.DBRMLIB.DATA(CPROG020) 000018 //SYSPRINT DD SYSOUT=* 000019 //SYSTSPRT DD SYSOUT=* 000020 //SYSUDUMP DD SYSOUT=* 000021 //SYSTSIN DD * 000022 DSN S(DBA1) 000023 BIND PLAN(PR1) MEMBER(CPROG020) ACTION(REP) RETAIN ISOLATION(CS) 000024 END 000025 //******************** 000026 //* GRANT 000027 //******************** 000028 //GRANT EXEC PGM=IKJEFT01 000029 //STEPLIB DD DISP=SHR,DSN=DSN510.SDSNLOAD 000030 //SYSPRINT DD SYSOUT=* 000031 //SYSTSPRT DD SYSOUT=* 000032 //SYSUDUMP DD SYSOUT=* 000033 //SYSTSIN DD * 000034 DSN SYSTEM(DBA1) 000035 RUN PROGRAM(DSNTIAD) PLAN(DSNTIA51) Command ===> Scroll ===> PAGE F1=Help F3=Exit F5=Rfind F6=Rchange F12=Cancel

Fig. 17 : JCL Script STARTJCL (Screen #2) Fig. 17 : The SQL precompiler generated a member "CPROG020" within data set "PRAKT20.DBRMLIB.DATA" (line 000017). The execution of our program "CPROG020" unter CICS requires a pointer to the data base table to be accessed (DB2 calls a table a PLAN). We name this pointer "PR1" (line 000023). It will be reused in Fig. 37 . We enter the code as shown in Fig. 16 18. A reference to PLAN PR1 reappears in line 000039. F3 saves the member.

File Edit Confirm Menu Utilities Compilers Test Help ------------------------------------------------------------------------------EDIT PRAKT20.CICSDB2.TEST01(STARTJCL) - 01.04 Columns 00001 00072 000036 LIBRARY('DSN510.RUNLIB.LOAD') 000037 END 000038 //SYSIN DD * 000039 GRANT EXECUTE ON PLAN PR1 TO PUBLIC 000040 /* ****** **************************** Bottom of Data ****************************

Command ===> F1=Help

Scroll ===> PAGE F3=Exit F5=Rfind F6=Rchange F12=Cancel

Fig. 18 : JCL Script STARTJCL (Screen #3)

You can reuse this script for similiar tasks by changing the names in lines 000007, 000010, 000017, 000023 (2 times)and 000039. For convenience, these names are underlines in red in Fig. 19, which reproduces the script.

//PRAKT20S JOB (),CLASS=A,MSGCLASS=H,MSGLEVEL=(1,1),NOTIFY=&SYSUID, // TIME=1440 //*************************** //* TRANSL/COMP/LINKEDIT //*************************** //COMP EXEC PROC=CTOCICS,REG=0M //TRN.SYSIN DD DISP=SHR,DSN=PRAKT20.CICSDB2.TEST01(OUT) //LKED.SYSIN DD * INCLUDE DB2LOAD(DSNCLI) NAME CPROG020(R) //********************* //* BIND //********************* //BIND EXEC PGM=IKJEFT01 //STEPLIB DD DISP=SHR,DSN=DSN510.SDSNEXIT // DD DISP=SHR,DSN=DSN510.SDSNLOAD //DBRMLIB DD DISP=OLD,DSN=PRAKT20.DBRMLIB.DATA(CPROG020) //SYSPRINT DD SYSOUT=* //SYSTSPRT DD SYSOUT=* //SYSUDUMP DD SYSOUT=* //SYSTSIN DD * DSN S(DBA1) BIND PLAN(PR1) MEMBER(CPROG020) ACTION(REP) RETAIN ISOLATION(CS) END //******************** //* GRANT //******************** //GRANT EXEC PGM=IKJEFT01 //STEPLIB DD DISP=SHR,DSN=DSN510.SDSNLOAD //SYSPRINT DD SYSOUT=* //SYSTSPRT DD SYSOUT=* //SYSUDUMP DD SYSOUT=* //SYSTSIN DD * DSN SYSTEM(DBA1) RUN PROGRAM(DSNTIAD) PLAN(DSNTIA51) LIBRARY('DSN510.RUNLIB.LOAD') END //SYSIN DD * GRANT EXECUTE ON PLAN PR1 TO PUBLIC /*
Fig. 19 : JCL Script STARTJCL We enter SUB on the command line. We wait for JES to complete the job and press Enter.

18.53.21 JOB02053 $HASP165 CICSPRE ***

ENDED AT N1

MAXCC=4 CN(INTERNAL)

Fig. 20 : JES Output "MAXCC=4" indicates the compile and link runs were successful. We now have created all required programs for our CICS - DB2 transaction. As a next step they have to be installed in the CICS subsystem. We open a 2nd 3270 emulator session and access jedi.informatik.uni-leipzig.de.

TCPIP MSG10 ==> SOURCE DATA SET = SYS1.LOCAL.VTAMLST(USSTCPIP) 03/01/01 W E L C O ME T O 19:20:39

SSSSSS // 3333333 9999999 0000000 SS // 33 33 99 99 00 00 SS // 33 99 99 00 00 SSSS // 33333 9999999 00 00 SS // 33 99 00 00 SS // 33 33 99 99 00 00 SSSSSSS // 3333333 9999999 0000000

YOUR TERMINAL NAME IS :

YOUR IP ADDRESS IS : 217.002.103.061

APPLICATION DEVELOPMENT SYSTEM OS/390 RELEASE 2.7.0 ===> ENTER "L " FOLLOWED BY THE APPLID YOU WISH TO LOGON TO. EXAMPLE "L TSO" FOR TSO/E OR "L C001" FOR THE CICSC001 CICS APPLICATION. L C001

Fig. 21 : Logon-Screen We logon with "L C001" (Fig. 20) and press Enter.
Signon to CICS --------------- WELCOME AT UNIVERSITY OF LEIPZIG --------------BITTE TRANSAKTION <CESF LOGOFF> ZUM AUSLOGGEN BENUTZEN! APPLID A06C001 -JEDI-CICS-

Type your userid and password, then press ENTER: Userid . . . . PRAKT20 Password . . . ******* Language . . . New Password . . . Groupid . . .

DFHCE3520 Please type your userid. F3=Exit

Fig. 22 : Signon to CICS User ID and password are the same as under TSO. Enter .

DFHCE3549 Sign-on is complete (Language ENU). CEDA DISPLAY GROUP(*) 10:41:29 IBM-3278-2

Fig. 23 : Calling the CEDA Shell Pressing the TAB key once causes the cursor to jump to the bottom line We enter the " CEDA DISPLAY GROUP(*) " command. Enter .

CEDA DEFINE MAPSET(S01SET) GROUP(PRAKT20) ENTER COMMANDS GROUP AOR2TOR ARTT ATC CBPS CEE CICREXX CSQ CSQCKB CSQSAMP CTA1TCP C001EZA C001TCP DAVIN4 DAVIN8 DAVIN85 DAVIN9 + DAVIN94 SYSID=C001 APPLID=A06C001 RESULTS: 1 TO 17 TIME: 00.00.00 DATE: 01.060 PF 1 HELP 3 END 4 TOP 5 BOT 6 CRSR 7 SBH 8 SFH 9 MSG 10 SB 11 SF 12 CNCL

Fig. 24 : The existing Groups Der " CEDA DISPLAY GROUP(*) " command displays all groups that exist so far ( Fig. 24). We define our BMS program S01SET" for the new group "PRAKT20" . We press Enter 3 times.

The group name can have any value but can exist only once. I recommend you use your user ID.
CEDA DEFINE MAPSET(S01SET) GROUP(PRAKT20) OVERTYPE TO MODIFY CEDA DEFine Mapset( S01SET ) Mapset : S01SET Group : PRAKT20 Description ==> REsident ==> No No | Yes USAge ==> Normal Normal | Transient USElpacopy ==> No No | Yes Status ==> Enabled Enabled | Disabled RSl : 00 0-24 | Public

CICS RELEASE = 0530

I New group PRAKT20 created. DEFINE SUCCESSFUL PF 1 HELP 2 COM 3 END SYSID=C001 APPLID=A06C001 TIME: 00.00.00 DATE: 01.060 6 CRSR 7 SBH 8 SFH 9 MSG 10 SB 11 SF 12 CNCL

Fig. 25 : Definition of S01SET Definition was successful, the new group has been created.
CEDA DEFINE PROG(CPROG020) GROUP(PRAKT20) OVERTYPE TO MODIFY CEDA DEFine Mapset( S01SET ) Mapset : S01SET Group : PRAKT20 Description ==> REsident ==> No No | Yes USAge ==> Normal Normal | Transient USElpacopy ==> No No | Yes Status ==> Enabled Enabled | Disabled RSl : 00 0-24 | Public

CICS RELEASE = 0530

I New group PRAKT20 created. DEFINE SUCCESSFUL PF 1 HELP 2 COM 3 END SYSID=C001 APPLID=A06C001 TIME: 00.00.00 DATE: 01.060 6 CRSR 7 SBH 8 SFH 9 MSG 10 SB 11 SF 12 CNCL

Fig. 26 : C Program Definition Now we define the C program. Enter .

CEDA DEFINE PROG(CPROG020) GROUP(PRAKT20) OVERTYPE TO MODIFY CICS RELEASE = 0530 CEDA DEFine PROGram( CPROG020 ) PROGram : CPROG020 Group : PRAKT20 DEscription ==> Language ==> Le370 CObol | Assembler | Le370 | C | Pli RELoad ==> No No | Yes RESident ==> No No | Yes USAge ==> Normal Normal | Transient USElpacopy ==> No No | Yes Status ==> Enabled Enabled | Disabled RSl : 00 0-24 | Public CEdf ==> Yes Yes | No DAtalocation ==> Below Below | Any EXECKey ==> User User | Cics COncurrency ==> Quasirent Quasirent | Threadsafe REMOTE ATTRIBUTES DYnamic ==> No No | Yes + REMOTESystem ==> SYSID=C001 APPLID=A06C001 TIME: 00.00.00 DATE: 01.060 6 CRSR 7 SBH 8 SFH 9 MSG 10 SB 11 SF 12 CNCL

DEFINE SUCCESSFUL PF 1 HELP 2 COM 3 END

Fig. 27 : Parameter Selection We select Le370 as Language, although it is really a development environment (Fig. 27), see also Fig. 22 in tutorial 3 . Enter .The message "DEFINE SUCCESSFUL" appears. Press F3 .
CEDA DEFINE TRANS(D020) GROUP(PRAKT20) STATUS: SESSION ENDED

Fig. 28 : Session ended Finally we define the name (TRID) of the new transaction. We choose "D020 and enter the command "CEDA DEFINE TRANS(D020) GROUP(PRAKT20)" . You remeber, this has to be a 4 character name, and it has to be unique. Enter .

DEFINE TRANS(D020) GROUP(PRAKT20) OVERTYPE TO MODIFY CICS RELEASE = 0530 CEDA DEFine TRANSaction( D020 ) TRANSaction ==> D020 Group ==> PRAKT20 DEscription ==> PROGram ==> CPROG020 TWasize ==> 00000 0-32767 PROFile ==> DFHCICST PArtitionset ==> STAtus ==> Enabled Enabled | Disabled PRIMedsize : 00000 0-65520 TASKDATALoc ==> Below Below | Any TASKDATAKey ==> User User | Cics STOrageclear ==> No No | Yes RUnaway ==> System System | 0 | 500-2700000 SHutdown ==> Disabled Disabled | Enabled ISolate ==> Yes Yes | No Brexit ==> + REMOTE ATTRIBUTES S PROGRAM OR REMOTESYSTEM MUST BE SPECIFIED. SYSID=C001 APPLID=A06C001 PF 1 HELP 2 COM 3 END 6 CRSR 7 SBH 8 SFH 9 MSG 10 SB 11 SF 12 CNCL

Fig. 29 : Defining our Application Program We enter "CPROG020" in the line labeled "PROGram" as shown in Fig.29. Enter .
OVERTYPE TO MODIFY CEDA DEFine TRANSaction( D020 ) TRANSaction : D020 Group : PRAKT20 DEscription ==> PROGram ==> CPROG020 TWasize ==> 00000 PROFile ==> DFHCICST PArtitionset ==> STAtus ==> Enabled PRIMedsize : 00000 TASKDATALoc ==> Below TASKDATAKey ==> User STOrageclear ==> No RUnaway ==> System SHutdown ==> Disabled ISolate ==> Yes Brexit ==> + REMOTE ATTRIBUTES CICS RELEASE = 0530

0-32767

Enabled | Disabled 0-65520 Below | Any User | Cics No | Yes System | 0 | 500-2700000 Disabled | Enabled Yes | No

DEFINE SUCCESSFUL PF 1 HELP 2 COM 3 END

SYSID=C001 APPLID=A06C001 TIME: 00.00.00 DATE: 01.060 6 CRSR 7 SBH 8 SFH 9 MSG 10 SB 11 SF 12 CNCL

Fig. 30 : Defining the Transaction "DEFINE SUCCESSFUL" . Press Enter.

CEDA INSTALL GROUP(PRAKT20) STATUS: SESSION ENDED

Fig. 31 : Group Installation Now that we have defined the BMS MAP, the C program and the Transaction ID, we have to install everything in group "PRAKT20", using the command "CEDA INSTALL GROUP(PRAKT20)" (Fig. 29) . Enter .
INSTALL GROUP(PRAKT20) OVERTYPE TO MODIFY CEDA Install All Connection ==> DB2Conn ==> DB2Entry ==> DB2Tran ==> DOctemplate ==> Enqmodel ==> File ==> Journalmodel ==> LSrpool ==> Mapset ==> PARTItionset ==> PARTNer ==> PROCesstype ==> PROFile ==> PROGram ==> + Requestmodel ==> SYSID=C001 APPLID=A06C001 TIME: 00.00.00 DATE: 01.060 6 CRSR 7 SBH 8 SFH 9 MSG 10 SB 11 SF 12 CNCL

INSTALL SUCCESSFUL PF 1 HELP 3 END

Fig. 32 : Successful Installation Installation of group "PRAKT20" was successful. Press F3 .

D020 STATUS:

SESSION ENDED

Fig. 33 : Calling the Transaction In Tutorial 3 we were finished at this point and could call the transaction by entering the TRID on the command line. Let us try the same. Enter the TRID on the command line (see Fig. 33) and press Enter.

DFHAC2220 20:49:29 A06C001 The coordinator system has indicated that the current unit of work is to be backed out. Transaction D020 has been abnormally terminated with abend ASP3.

Fig. 34 : Error Message We receive an error message (see.. Fig. 34). On your screen it possibly may have a somewhat different format. The description of error code ASP3 can be found in an on-line handbook http://www.s390.ibm.com/bookmgr-cgi/bookmgr.cmd/BOOKS/DFHWG400/ 2%2e3%2e606?ACTION=MATCHES&REQUEST=asp3 &TYPE=FUZZY&SHELF=&searchTopic=TOPIC&searchText=TEXT&searchIndex= INDEX&rank=RANK&ScrollTOP=FIRSTHIT#FIRSTHIT

We search for error code ASP3 and find the following: Explanation: The abnormal termination occurs because a remote system on which the unit of work depends fails to take a syncpoint. The transaction cannot commit its changes until all coupled systems to which function has been transmitted also commit. This may be because the syncpoint protocol for transaction to transaction has been violated by failing to be in send mode for all sessions for which syncpoint has not been received. User Response: Check why the remote system failed to respond to the request. We remember: TSO, CICS and DB2 are separate OS/390 subsystems, running in separate virtual address spaces. The CICS group "PRAKT20" needs a definition to find our data base and table.

DFHAC2220 20:56:06 A06C001 The coordinator system has indicated that the DFHAC2001 03/02/01 20:56:29 A06C001 Transaction '' is not recognized. Check that the transaction name is correct. CEDA DEFINE DB2ENTRY

Fig. 35 : Calling the Database Definition For the definition we use the CEDA command "CEDA DEFINE DB2ENTRY" (see Fig. 35). Press Enter.

DEFINE DB2ENTRY OVERTYPE TO MODIFY CEDA DEFine DB2Entry( DB2Entry ==> Group ==> DEscription ==> THREAD SELECTION ATTRIBUTES TRansid ==> THREAD OPERATION ATTRIBUTES ACcountrec ==> None AUTHId ==> AUTHType ==> DRollback ==> Yes PLAN ==> PLANExitname ==> PRIority ==> High PROtectnum ==> 0000 THREADLimit ==> THREADWait ==> Pool MESSAGES: 2 SEVERE

CICS RELEASE = 0530 )

None | TXid | TAsk | Uow Userid | Opid | Group | Sign | TErm | TX Yes | No

High | Equal | Low 0-2000 0-2000 Pool | Yes | No SYSID=C001 APPLID=A06C001

PF 1 HELP 2 COM 3 END

6 CRSR 7 SBH 8 SFH 9 MSG 10 SB 11 SF 12 CNCL

Fig. 36 : DEFINE DB2ENTRY Panel The "DEFINE DB2ENTRY-Panel" appears (Fig. 36). We provide the missing entries in Fig. 37 and Fig. 38.
define DB2ENTRY OVERTYPE TO MODIFY CEDA DEFine DB2Entry( DB2Entry ==> D020 Group ==> PRAKT20 DEscription ==> THREAD SELECTION ATTRIBUTES TRansid ==> D020 THREAD OPERATION ATTRIBUTES ACcountrec ==> None AUTHId ==> AUTHType ==> DRollback ==> Yes PLAN ==> PR1 PLANExitname ==> PRIority ==> High PROtectnum ==> 0000 THREADLimit ==> THREADWait ==> Pool MESSAGES: 2 SEVERE

CICS RELEASE = 0530 )

None | TXid | TAsk | Uow Userid | Opid | Group | Sign | TErm | TX Yes | No

High | Equal | Low 0-2000 0-2000 Pool | Yes | No SYSID=C001 APPLID=A06C001

PF 1 HELP 2 COM 3 END

6 CRSR 7 SBH 8 SFH 9 MSG 10 SB 11 SF 12 CNCL

Fig. 37 : DB2ENTRY Parameter, Part 1 The DB2- access (DB2Entry) receives the name "D020" , to be part of group. "PRAKT20". Our transactions-ID (TRID) is "D020".

Let us recall: We generated a JCL-Script "STARTJCL" , which translated our C program . At two locations of this script we defined a pointer for our database table (Plan) and called it "PR1" , see Fig. 18 and 19. In Fig. 37 we establish the link to the data base table using the value PR1.
define DB2ENTRY OVERTYPE TO MODIFY CEDA DEFine DB2Entry( DB2Entry ==> D020 Group ==> PRAKT20 DEscription ==> THREAD SELECTION ATTRIBUTES TRansid ==> D020 THREAD OPERATION ATTRIBUTES ACcountrec ==> TXid AUTHId ==> AUTHType ==> Sign DRollback ==> Yes PLAN ==> PR1 PLANExitname ==> PRIority ==> High PROtectnum ==> 0000 THREADLimit ==> 0003 THREADWait ==> Yes MESSAGES: 2 SEVERE

CICS RELEASE = 0530 )

None | TXid | TAsk | Uow Userid | Opid | Group | Sign | TErm | TX Yes | No

High | Equal | Low 0-2000 0-2000 Pool | Yes | No SYSID=C001 APPLID=A06C001

PF 1 HELP 2 COM 3 END

6 CRSR 7 SBH 8 SFH 9 MSG 10 SB 11 SF 12 CNCL

Fig. 38 : DB2ENTRY Parameter, Part 2 We enter the 4 parameter marked in Fig. 38. Press enter .
OVERTYPE TO MODIFY CEDA DEFine DB2Entry( D020 DB2Entry : D020 Group : PRAKT20 DEscription ==> THREAD SELECTION ATTRIBUTES TRansid ==> D020 THREAD OPERATION ATTRIBUTES ACcountrec ==> TXid AUTHId ==> AUTHType ==> Userid DRollback PLAN PLANExitname PRIority PROtectnum THREADLimit THREADWait ==> ==> ==> ==> ==> ==> ==> Yes PR1 High 0000 0003 Yes CICS RELEASE = 0530 )

None | TXid | TAsk | Uow Userid | Opid | Group | Sign | TErm | TX Yes | No

High | Equal | Low 0-2000 0-2000 Pool | Yes | No SYSID=C001 APPLID=A06C001 TIME: 00.00.00 DATE: 01.061 6 CRSR 7 SBH 8 SFH 9 MSG 10 SB 11 SF 12 CNCL

DEFINE SUCCESSFUL PF 1 HELP 2 COM 3 END

Fig. 39 : Successful Definition The definition was successful. Press the F3 key.

CEDA INSTALL GROUP(PRAKT20) STATUS: SESSION ENDED

Fig. 40 : Installating the Group Now the defined modification has to be installed. We enter the command "CEDA INSTALL GROUP(PRAKT20)" (see Fig. 40) . Press Enter.
INSTALL GROUP(PRAKT20) OVERTYPE TO MODIFY CEDA Install All Connection ==> DB2Conn ==> DB2Entry ==> DB2Tran ==> DOctemplate ==> Enqmodel ==> File ==> Journalmodel ==> LSrpool ==> Mapset ==> PARTItionset ==> PARTNer ==> PROCesstype ==> PROFile ==> PROGram ==> + Requestmodel ==> SYSID=C001 APPLID=A06C001 TIME: 00.00.00 DATE: 01.061 6 CRSR 7 SBH 8 SFH 9 MSG 10 SB 11 SF 12 CNCL

INSTALL SUCCESSFUL PF 1 HELP 3 END

Fig. 41 : Successful Installation Installation was successful. Press the F3 key.

D020 STATUS:

SESSION ENDED

Fig. 42: Starting the Transaction To call our transaction we enter the TRID "D020" on the command line (Fig. 40). Press Enter .

VORNAME HEINO BORIS SEBASTIAN FRITZ

NACHNAME BAUER FAERBER RICHTER SCHULTE

Fig. 43 : The Content of the Database Table is displayed. Success !!! The database content is displayed on the screen (Fig. 41). You have successfully finished tutorial 5 .

Let us review what we have done so far. You have written your first programm in C (tutorial 2). You have written your first CICS transaction in C (tutorial 3). You have created a DB2 relational database, albeit a very simple one (tutorial 4). And you have written a CICS transaction that accesses this database (tutorial 5). You should now be able to write a more ambitious application on your own, and we would like to encourage you to do so. TSO, SPUFI and ISPF have under OS/390 an equivatent function as the c-shell, bourne-shell or bashshell under Unix. As a competent programmer you have to know these tools, and you will be occasionally in a situation where you need them. Some fanatics swear by them. Most of the times you will probably use a more modern environment, and the same is true for OS/390. The following tutorials 6 15 will show you the use of modern OS/390 tools. These are in particular: Tutorial 11 contains a simple REXX demo. Tutorial 6. Writing a simple Java Servlet under OS/390 WebSphere. Tutorial 14 installs Eclipse, a JDBC driver and DB2Connect on a Windows 2000 system. Tutorial 15 accesses our OS/390 DB2 Data base via both JDBC and DB2Connect, using a simple Java application. Tutorials 8 and 9 do the same using the Visual Age for Java Integrated Development Environment. Tutorial 10 ports this Java code to OS/390 Unix System Services, executes it as Byte code or alternatively translates it with the High Performance Java Compiler, and runs it . Tutorial 7 writes a simple MQSeries application. Tutorial 12 installs a MQSeries Server on a Windows 2000 client and accesses OS/390. We have installed a Cobol Credit Card Authorisation application on our system. It can be accessed with a BMS presentation logic by entering the TRID NACT under CICS. Tutorial 13 does the same with a Java presentation logic. It accesses the Credit Card Authorisation application via COMMAREA and the MQSeries CICS Gateway, using a simple Java Front end. In addition we ported some existing IBM servlet samples, which include source code. They can be viewed at jedi.informatik.uni-leipzig.de/IBMWebAS/samples (attention: this URL is case sensitive). We are working to generate student exercises based on this material. We have a OS/390 Wap Server demo monitoring system performance with a handy. See http://jedi.informatik.uni-leipzig.de/docs/wap.pdf .

Aufgabe: Bereiten Sie unter CICS die Transaktion vor, die auf die DB2-Datenbank zugreift (benutzen Sie die CICSGruppe "prakt<Ihre Gruppen-Nr>") und fhren Sie diese aus. Die DB2-Datenbank soll die Namen der bungsteilnehmer Ihrer Gruppe enthalten. Benutzen Sie als Transaktions-ID "D<Gruppen-Nr>". Sind Sie z.B. Gruppe 20, dann wre Ihre Transaktion-ID "D020". Aufgabe: Gehen Sie vom CUSTOMPAC MASTER APPLICATION MENU aus in die System Display and Search Facility. Im erscheinenden SDSF PRIMARY OPTION MENU whlen Sie die Option ST. Lschen Sie alle angezeigten Jobs, die sich in der PRINT-Queue befinden, indem Sie links neben einen jeden Jobnamen "p" (purge) eintragen und anschlieend die Eingabetaste (mehrfach) drcken. Einen Job drfen Sie natrlich nicht lschen: Den einen, der sich in der EXECUTION-Queue befindet. Denn das ist der Job, mit dem Sie zur Zeit eingeloggt sind.