Jazz Classical CICS Programming with Micro Focus

Jazz Classical CICS Programming with Micro Focus. 1

Getting Started. 1

Configuring Jazz. 1

Creating a CICS Menu. 1

Editing the Commarea. 1

Editing the screen. 1

Program Logic. 1

Adding MENU1 and some subprograms to TstSQL. 1

Testing Menu1. 1

Creating Files for the Customer Programs. 1

Creating Programs CICS1 and CICS2. 1

Testing programs CICS1 and CICS2. 1

Custf 1

Custf1. 1

FR.. 1

Test Program CICS1. 1

Creating Program CICS3. 1

Creating Test Data. 1

Parts. 1

Orders. 1

Creating CICS3, Part1. 1

Creating Program CICS3, Part 2 (Optional) 1

Troubleshooting. 1

Can’t create group MANAJAZZ. 1

Accessing VSAM from CICS AND Batch. 1

Troubleshooting Jazz-created COBOL programs. 1

Debugging with MFED.. 1

Jazz Program Structure. 1

Jazz Configuration Option : Generate Diagnostic Code. 1

Program JZABNDC.. 1

Various Response Codes. 1

Glossary. 1

Disclaimer:  This material is written by and represents the opinions of Jazz Software Ltd. The use of Micro Focus examples in this and related Help pages do not imply any contractual relationship between Micro Focus and Jazz Software, nor that Micro Focus supports or recommends Jazz.  

The previous chapter dealt with batch programming. This chapter builds on that foundation to create classical CICS programs, communicating with 3270 screens as in the initial video in the classical CICS series. 

Getting Started

Prerequisites: either

·         you will have completed the previous 2 chapters, Set Up Jazz with Micro Focus, and Jazz Batch Programming with Micro Focus, and you will have completed the Micro Focus Mainframe Tutorials Assembler and CICS (although you don’t yet need to complete the CICS tutorials dealing with Web Services).  In the CICS tutorial you set up a project called ACCT, with a Micro Focus Server called ESACCT.

Or

·         You will have created your own Micro Focus COBOL program with similar characteristics to the tutorial project ACCT 

This tutorial was written assuming that you’re using project TstSQL, and will use this project, adding various objects into it as we did in the previous chapter when batch objects were added into the MFJazz1 project.  Read this making mental substitutions for you own project and server names.  Micro Focus screen snaps were taken with MF Enterprise Developer 4.n, and may differ if you’re using another version of MFED.  A few snaps using an earlier project ACCT have not been replaced where the difference is not material. You may have already done some of the following tasks.

The first task is to configure Jazz appropriately.  Then we’ll cover these topics: -

·         Creating an initial CICS Menu

·         Single record enquiry and update

·         Parent-child record sets and screen scrolling

Configuring Jazz

Start Jazz, click [Configure].  Configure Jazz Workbench appears, with the Workbench Options tab open.  Set values similar to those below.

Now click [Check Paths]. The common path, project, and folders will be checked.  Actually, Jazz uses COBOL Copy Books only for Web Service messages, otherwise getting the information that it needs from Jazz copy books and generating data definitions directly into the COBOL data division, so for now you could leave COBOL Copy Library unset, but it is a good idea to set this up correctly from the start. 

If any folder doesn’t exist then the textbox is highlighted and a dialog appears to locate or create the missing or invalid folder: -

Click [Initialise Project] and select all objects. 

Now click the COBOL Tab.  COBOL Dialect should be Enterprise COBOL for z/OS. 

Creating a CICS Menu

This follows the process described here, which assumed that a z/OS system was being used for testing: -

1/         Create the [JazzGen] button, and select type Logic/CICS Program.  Fill in the form with data such as that shown: -

Click [Finish].  Jazz creates the Commarea, screen, and program, and then displays the program: -

Editing the Commarea

Menu1 will have three alternatives, and we’ll be asking the user to enter a number 1, 2, or 3.  We add a definition for a suitable field to the commarea: right-click Commarea to display Menu1C.  Add

            Function PIC '9' RANGE(1:3),

and click [Check]: -

Click [Exit] and reply [Yes] to the save message.  Jazz returns to the first workbench.

Editing the screen

Click [Screen] to open the Jazz 3270 screen editor.  At this stage the screen is blank, except for a few standard fields defined by a template.  Type the constant (= green) text, or something like it, into the screen. 

Click on [+] beside Menu1C to expand its definition:-: -

Now drag Function to the screen: -

Click [Process] to save screen MENU1S and to create the BMS Map.  The screen editor closes and you return to the Jazz workbench.

Program Logic

Write the program logic like this.  You don’t want the initial comments, either delete or overwrite them: -

Click [Process] to check the program and turn it into COBOL.  The program is checked and the button to the right of [Process] (named [Job Results] when MANASYS is configured for zOS, but here named [TstSQL] as this is the name of our project) turns green: -

Now click [TstSQL] to open the COBOL project to test our program and screen.  If you wish, you can [Exit] from Jazz: reply [Yes] to the save message.

Adding MENU1 and some subprograms to TstSQL

As in the previous chapter (batch programming), when we have created COBOL and related objects then they are already in the appropriate folders but we have to tell Visual Studio that they are included in the project.  Clicking [TstSQL] on the Jazz workbench will have opened this COBOL project in Visual Studio. 

 

Open the Solution Explorer window.  Right-click the TstSQL project and with Add/Existing item, add

            bms\MENU1S.bms

and

            cbl\Menu1.CBL

to the project.  Also, there are a number of COBOL support routines that might be used by CICS programs:  add these.  These may be used by Jazz-generated programs, and if they are not part of your solution the program will abend if it calls them. 

 

Right-click the solution and click Build Solution.  If should build cleanly, but you may get messages like this from BMS: -

If you do then you need to set the BMS directive allow long names. 

1.    Solution Explorer: double-click the project properties

2.    Click the BMS tab, and select Yes to Allow Long Macro Label Names: -

Then build the solution again.  

Testing Menu1

With a clean build we’re ready to test the solution.  With a z/OS system we’d next define the transaction code MNU1 and our MENU1 and MENU1S to CICS with command CEDA (see JazzUGOnline1), but with MF Enterprise Developer we use a Micro Focus tool, ESMAC

1.            In Visual Studio, open Server Explorer, Expand Micro Focus Servers, Start (if necessary) the server for the project.  In this example it has the same name as the project, TSTSQL: -

2.            Right-click Micro Focus Servers, click Administration to display the admin web page.  Locate this server: -

3.            Click [Details] under “Started”, or else click [Edit] for TSTSQL, and then the Control tab.  The Server/Control page has a button [ES Monitor and Control].  Click this: -

4.             ESMAC opens with a page like this: -

Note the value of SIT, which is highlighted on the snap above.  We’ll need this later.

5.            In Resources (panel at the left), change the combo to “by Group”.  Click [Groups]

6.            Click [New] to define a new group. Give details Name=MANAJAZZ, and details = MANASYS Jazz Testing, and click [Add].  The group appears and we can define our programs to CICS within this group: -


If the group does not appear, but instead you get an error message, see Troubleshooting/Can’t create group MANAJAZZ

7.            Click [PCT] to define trancode MNU1 to initiate program MENU1, as shown below. Click [Add].  A message Add successful appears: -

8.            Click [Add]  then [Install] (towards the bottom of the page: not shown on the screen snap) to install the PCT entry: -

9.            Click [Group List] to return to the CICS Group MANAJAZZ.  Define programs Menu1 and Menu1S (BMS Maps are considered programs) in the PPT table.  From the Group display, Click [PPT]

10.          Give a name and descriptions, click [Add]: -

Then click [Install].

11.          Click [Group list] to return to the previous display.  Repeat for Menu1S: [Add] and [Install].  As you work through this process the objects that you’re defining within group MANAJAZZ appear within the group display: -

12.          Navigate back to ESMAC.  Note the value of SIT, which was highlighted in #3 above as DEMOSIT.   In the ESMAC page, chose Resources=by Group and click SIT: -

13.          Get the name of the start-up list from this display (or from [Details]): SIT DEMOSIT uses startup list DEMOSTRT.  Click [Startup] in the Resources area at the left. A list of the start-up lists is displayed.  Click [Details] for list DEMOSTRT to display the list of groups started by this list.   Add MANAJAZZ in the blank position at the end, and click [Apply]  A message appears at the top, and MANAJAZZ is added to list DEMOSTRT: -


14.          Re-start TSTSQL. We’re almost ready to run our first CICS test.  Check the project properties to see that we have the correct Debug options. Visual Studio Solution Explorer: open the project properties.  Debug Tab: Debug Active settings should be set to CICS or Any: -

15.          Now a CICS test should run successfully.  To test a CICS program: -

·                     Without debugging: with the MF Server (TSTSQL) running, right-click the Server in Server Explorer, and click Enterprise Server/Mainframe TN3270 Display:-

·                     With debugging:  start debugging (Visual Studio, click Start). If the server (TSTSQL) is not already running you’ll be prompted to start it.  The TN3270 display should then appear automatically: if it does not start it as above.

·                     With or without debugging, the TN3270 display will start with this Signon to CICS screen: -

Click anywhere in this screen, then press ctrl-shift-Z or the F3 key to clear the screen.

·                     Type MNU1 at the top of the screen (where the cursor has been positioned). We have defined transaction code MNU1 to invoke program Menu1.

·                     Without debugging: our program MENU1 will be invoked and display screen MENU1S.

·                     With debugging: Visual Studio/Micro Focus will open program MENU1 and start stepping through it: -

Click Continue unless we want to step through the program: program Menu1 completes, displaying screen Menu1s.  We can test our logic by entering various values of function code: for now we should only enter invalid function codes like function 4, not “valid” function code of 1, 2, or 3 because we haven’t written programs CICS1, CICS2, or CICS3 yet, and so our program will fail when it attempts to execute one of the EXIT TO statements.

 

·                     If our program is set up correctly then at this stage we can enter an invalid function code into screen MENU1S, and press [Enter].  The program logic will display an error message: -

Creating Files for the Customer Programs

Programs CICS1 and CICS2 require a VSAM file Custf, while CICS3 also requires a related file called Orders.  You will also need file FR, as the definition of Custf includes

                Region DECIMAL(3) EXISTS FR.Region,     

Program CICS2 may update this value, in which case the new value is checked to ensure that it exists already within the reference file FR.

See https://www.jazzsoftware.co.nz/Docs/JazzUGTraining.htm for instructions on how to create these files.

Creating Programs CICS1 and CICS2

This 4 minute video shows how you write program CICS2, a program for CustF enquiry, addition, update, or deletion.  It uses an earlier version of Jazz and testing is with a z/OS mainframe, but while there have been changes to Jazz since the video was created the principles are the same: programs CICS1 and CICS2 are created with dialog [JazzGen] => choose Logic/CICS Program, with this form giving details: -

Click [Finish] and Jazz generates the screen, commarea, and program, then displays the program.  You will need to click [Check] again to handle inserted COPY statements.  Here is program CICS1

*# Last Updated by JAZZUSER at 7/03/2018 2:51:36 p.m.

PROGRAM CICS1 CICS INSCREEN(CICS1S) TRANSID(TRN1) COMMAREA(CICS1C) EXIT(Menu1);

COPY Custf;

ACCEPT (CICS1S.Account OR CICS1S.Name);

#562 I CICS1S.Error used as message field

DEFINE TS1 TS DATA(

    Account LIKE CustF.Account);

GET Custf KEY(CustF.Account OR CustF.Name) TS(1);

    #373 I GET statement returns one record at a time for Name

END GET CustF;

IF CustF.$Found = false THEN;

    CICS1S.Error = 'No Record Found';

END IF;

COPY JZSMth;

SEND Inscreen;

Click [Process] to create CICS1.cbl, then click [TSTSQL] to open the COBOL project and add CICS1.cbl and CICS1S.bms to it. Compile both these programs 

Program CICS2 is created exactly like CICS1 except for obvious name changes, and with Program Type set to 1 table Update.  Here is program CICS2: -

*# Last Updated by robertb at 24/02/2016 3:14:46 p.m.

PROGRAM CICS2 CICS INSCREEN(CICS2S) TRANSID(TRN2) COMMAREA(CICS2C) EXIT(Menu1);

ACCEPT (CICS2S.Function);

#562 I CICS2S.Error used as message field

CASE (CICS2C.Function);

    WHEN (Enquiry);

        ACCEPT (CICS2S.Account OR CICS2S.Name);

        #562 I CICS2S.Error used as message field

        DEFINE TS1 TS DATA(

            Account LIKE CustF.Account);

        GET Custf KEY(CustF.Account OR CustF.Name) SAVECOPY CICS2C.SAVE TS(1);

            #373 I GET statement returns one record at a time for Name

        END GET Custf RESETFUNCTION;

    WHEN (Update);

        GET Custf WHERE(CustF.Account=CICS2C.SAVE.Account) REWRITE CHECKCOPY(CICS2C.SAVE);

            COPY JZSMth;

            COPY JZMDays;

            ACCEPT (CICS2S.Region,CICS2S.District,CICS2S.Name,CICS2S.SalesThisMonth,CICS2S.SalesYTD,CICS2S.Billingcycle,CICS2S.DateCommenced);

            #562 I CICS2S.Error used as message field

        END GET Custf REWRITE RESETFUNCTION;

    WHEN (Add);

        CustF.Account = CustF.$LastKey + 1; [Will need to be changed if key is not a number

        #361 E Assignment to a key field

        GET Custf KEY(CustF.Account) CREATE;

            ACCEPT (CICS2S.Region,CICS2S.District,CICS2S.Name,CICS2S.SalesThisMonth,CICS2S.SalesYTD,CICS2S.Billingcycle,CICS2S.DateCommenced) SETMDT;

            #562 I CICS2S.Error used as message field

        END GET Custf CREATE RESETFUNCTION;

    WHEN (Delete);

        DELETE Custf WHERE(CustF.Account=CICS2C.SAVE.Account) CHECKCOPY(CICS2C.SAVE) RESETFUNCTION;

END CASE;

SEND Inscreen;

Similarly, after creating CICS2.jzz click [Process] and add CICS2.cbl and CICS2S.bms to project TSTSQL, and compile these programs.

Testing programs CICS1 and CICS2

Now the files used by programs CICS1 and CICS2 have been compiled, and the files that they use created. As with program Menu1, we need to add PCT entries to group MANAJAZZ for transactions TRN1 => CICS1 and TRN2 => CICS2, and PPT entries for CICS1, CICS1S, CICS2, and CICS2S.   But there is also a new feature: VSAM files Custf and FR. We have to make Custf and FR available to CICS before we can run programs CICS1 and CICS2.

Open ESMAC, click Resources/by Group, and click [Details] for group MANAJAZZ.

Click [PCT]: add PCT entries for transactions TRN1 => CICS1 and TRN2 => CICS2

Click [PPT]: add PPT entries for CICS1, CICS1S, CICS2, and CICS2S.  

Click [FCT]:  add FCT entries for Custf, Custf1 (its alternate index), and FR.

Custf

Fill in the Name, Description, and File Path, ensure that Read, Add, Browse, Delete, and Update are all checked.   Check Start Open.  Check Use Catalog

Custf1

Create another FCT, with the same options, for the alternate index, Custf1: -

Click [Add].  Click [Install].  

FR

Like Custf, without an alternate index.

Here is the MANAJAZZ group after this has been done: -

Test Program CICS1

We should now be ready to test programs CICS1 and CICS2.

Stop server TSTSQL.   Build solution.  Start server TSTSQL, right-click it, click Mainframe TN3270 Display.

Clear the screen (Ctrl-shift Z), enter transaction MNU1: -

Set function = 1, click enter: -

Enter account 1, click enter: -

or leave Account Number absent (or zero) and give a name: -

and program CICS1 will retrieve the first record with this name, and scroll through the rest with PF11 (next) and PF10 (previous): -

Program CICS2 adds a function code to the screen, and functions Update, Add, and Delete to the enquiry of CICS1.

Creating Program CICS3

Have a look at this 5 minute video demonstrating the functions of CICS3.   This video used an earlier version of Jazz with direct z/OS testing, but the development of program CICS3.jzz is exactly as described in JazzUGOnLine3 except for the way that the program is tested.

Creating Test Data

To do something similar within our MF COBOL project, we need to download some more training objects.  Program CICS3 uses a simplified Customers – Orders – Parts data model, like this.   We have already created the customer file, CustF, but we need to create the Parts and Orders files: -

Start Jazz, click [Configure], and click [Add Training].  Select these objects from the training library: -

Orders.jzc

OrdersW.jzz

Parts.jzc

PartsW.jzz

Parts

Parts.jzc looks like this: -

DEFINE Parts VSAM DATA(

    Partnbr SMALLINT KEY,

    PartName CHAR(30) VALUE 'Part Name Absent' DKEY 'Jazzuser.vsam.parts1',

    StandardPrice DECIMAL(7,2))

    DSNAME 'Jazzuser.vsam.Parts';

1.    First create a cluster, using [JazzGen] => Data => VSAM to create appropriate JCL.  Add this JCL to project ACCT, and submit it

2.    Now compile program PartsW.jzz to COBOL, and add Partsw.cbl and Partsw.jcl to project ACCT.  

3.    Edit Partsw.jcl to remove the unwanted //Parts1 DD …

4.    Build the ACCT solution, and then submit Partsw.jcl

5.    Use [JazzGen] => Data => VSAM to create JCL, this time clicking the AIX checkbox. 

6.    In project ACCT edit the JCL to remove the BLDINDEX command, which is not needed with Micro Focus.  Then submit the JCL

We have now created a small parts file, with parts numbered 1 to 10: -

Of course a real parts file would have many more records, and many more fields in each record, but this test data is sufficient for the demonstration.

Orders

Orders.jzc looks like this. 

COPY Custf;

COPY Parts ;

DEFINE Orders VSAM DATA(

    OrdNbr DECIMAL(5) DPIC '99999' KEY HEADING 'Order Number',

    OrdCustId LIKE CustF.Account DKEY 'jazzuser.vsam.Orders1' EXISTS CustF.Account ,

    ordDate DATE,

    OrdPart LIKE Parts.Partnbr DKEY 'jazzuser.vsam.Orders2' EXISTS Parts.Partnbr,

    OrdQty SMALLINT,

    OrdDiscount DECIMAL (3,1) HEADING 'Order Discount',

    OrdStatus CHAR(1) CODES(I:Initial, C:Confirmed,Q:'Part Shipped', S:Shipped, B:Billed, P:Paid))

    DSNAME 'jazzuser.vsam.Orders';

 

Note that it has TWO alternate indexes, one on OrdCustID so that we can look up orders by customer, and one on OrdPart so that we can look up orders by Part Nbr. Both of these are defined LIKE xxx EXISTS xxx, making it easy for us in writing the definition as it ensures that the corresponding fields in both files have the same format, and ensuring that values in Orders must be primary key values in the respective files.   With SQL organization this relationship would be checked when we write an Orders record, but with VSAM it is not checked unless we use an ACCEPT statement. 

Create VSAM file Orders following the same steps as for Parts, with the minor difference that there are two alternate indexes: -

1.    First create a cluster, using [JazzGen] => Data => VSAM to create appropriate JCL.  Add this JCL to project ACCT, and submit it

2.    Now compile program OrdersW.jzz to COBOL, and add OrdersW.cbl and OrdersW.jcl to project ACCT.  

3.    Edit OrdersW.jcl to remove the unwanted // Orders1 DD … and // Orders2 DD … and

4.    Build the ACCT solution, and then submit OrdersW.jcl

5.    Use [JazzGen] => Data => VSAM to create JCL, this time clicking the AIX checkbox. 

6.    In project ACCT edit the JCL to remove the BLDINDEX commands, which are not needed with Micro Focus.  Then submit the JCL

Creating CICS3, Part1

There is no generator for classical CICS programs that update a set of parent/child records, so we create program CICS3 and screen CICS3S by enhancing a single-file update program like CICS2.  This process is described in JazzUGOnLine3.htm.  Develop CICS3 to the heading “Testing our Program So Far – z/OS”.  At this stage program CICS3 contains enough logic to display orders and to prevent DELETE for CustF records with Orders.    Instead of using CEDA:-

1.            [Process] program CICS3. 

2.            Open project ACCT.  Add items CICS3.cbl, and CICS3S.bms, to the project.

3.            Open ESMAC, navigate to group MANAJAZZ.  Add and install: -

a.    FCT ORDERS, ORDERS1, and ORDERS2, PARTS and PARTS1.  Note: file names must be given in capitals, otherwise FileNotFound conditions will occur.

b.    PCT Trn3 => CICS3, Trn4 => CICS4

c.     PPT CICS3, CICS3S, CICS4, CICS4S

(Parts and CICS4 aren’t needed yet, and may be deferred if you’re not going to develop program CICS4.  For me it was convenient to install them at this time)

Details aren’t shown here as they are similar to previous FCT, PCT, and PPT entries.  When complete, group MANAJAZZ will look like this: -

4.            Stop server TSTSQL.  

5.            Build solution TSTSQL

6.            Start server TSTSQL

7.            To test program CICS3,

a.    Right-click server TSTSQL (Visual Studio: Server Explorer window), click option Mainframe TN3270 Display

b.    Clear the screen (ctrl-shift Z), enter transaction code TRN3, Click Enter

c.     Enter some data and a function code, click Enter.   Recommended data: leave Account Nbr blank, enter name “Barnes”.   With this data you’ll be able to scroll forward and back through several records, and scroll up and down through a list of orders.

Creating Program CICS3, Part 2 (Optional)

If you want to complete program CICS3 to the level where it invokes program CICS4 to process orders, continue the process described in JazzUGOnLine3.htm.  As you reach stages when you have some new function to test: -

·         When relevant, process the screen to create BMS

·         Process the Jazz program to create an updated COBOL program

·         Stop TSTSQL, Rebuild the solution, restart TSTSQL and test the program

Troubleshooting

Can’t create group MANAJAZZ

In order to create group MANAJAZZ and define programs, files, and other CICS objects the projects Resource Definition File Path must be validly defined, and this path must contain object dfhdrdat.

I was trying to set up a project called TstSQL to test SQL features of Jazz, and I thought that I’d set this up with a CICS template.  However, when I attempted to create group MANAJAZZ I got an error message: -

1.    Is the Resource Definition File Path correctly defined?

a.    Visual Studio, Server Explorer window.  Right-click Micro Focus Servers, click Administration.   The MF Servers should be stopped. 

b.    Click the relevant [Edit] button.  Navigate to Server/Properties/MSS/CICS

c.     Here Resource Definition File Path is blank.  Set this to a suitable path with your project. I have set it to C:\Tutorials\TstSQL, which is the base path for this particular project. Click [Apply]

d.    This path should contain object dfhdrdat.   (Check this with Windows Explorer).   If not, you can copy one from the tutorial templates.  I copied dfhdrdat from

C:\Users\Public\Documents\Micro Focus\Enterprise Developer\Samples\Mainframe\CICS\Classic\CWS\Requester\system

e.    Start the server (TS2SQL)

You should now be able to create group MANAJAZZ.

Accessing VSAM from CICS AND Batch

If CICS has control of a VSAM dataset, then batch processes are sometimes prevented from accessing it.  For example, I wanted to change Custf.Name from CHAR(40) to CHAR(30) so that Name would fit on the same line as Account, so I tried to re-create it by editing the Custf.jzc definition, then by running the Jazz VSAM function with option Recreate Cluster: -

I expected this to delete the dataset, which I would then re-fill by re-running program CustfW and then the 2nd stage of the VSAM function, as I did first time.  However ReCreate Cluster failed: -

                 DELETE JAZZUSER.VSAM.CUSTF CLUSTER
JCLAM0231E(08) - Unable to acquire exclusive lock on dataset "JAZZUSER.VSAM.CUSTF".

If a batch job needs exclusive access to a dataset that is also accessed by CICS, then the dataset must be closed and disabled before the batch job can run. The batch job may wait until this has been done before executing, it may fail as above.  If the batch job does not require exclusive access, there is no problem - it can access the dataset at the same time as CICS.  For example you can submit CustFR.jcl to print CustF records whether or not CustF is open in CICS.

There are several ways of letting the batch job acquire an exclusive lock: -

1.         From the TN320 screen, Use transaction CFMT to Close/Disable/Open/Enable files.  E.g.

CFMT DISABLE CUSTF 

3.         Run "casfile" CICS commands to close/ disable a dataset

After any of these, stop/start server ESACCT.

Of course, while Custf is not available to CICS any attempt to execute programs CICS1 or CICS2 will abend.

While CustF was unavailable to CICS I reran the job sequence

·         Jazz VSAM Function ReCreate Cluster

·         Jazz program CustfW.jzz

·         Jazz VSAM Function AIX

as before, using the updated CustF.jzc definition.

Troubleshooting Jazz-created COBOL programs

Debugging with MFED

With MANASYS configured to work with Micro Focus Enterprise Developer, COBOL, JCL, and BMS are written into appropriate folders shared between MANASYS and MFED, and with the server (TSTSQL) running you can run batch tests by submitting JCL, and classical CICS tests by using Mainframe TN3270 Display.  You can easily debug your COBOL CICS programs as easily as batch programsSimply start the project (TSTSQL, not to be confused with the server TSTSQL which, if it is not already running, will be automatically started when you start the project), then right-click server (TSTSQL) and click Mainframe TN3270 Display.   Now as soon as your program starts it will stop at the first procedural statement: -

005240 PROCEDURE DIVISION.                                              CICS1

005250     EXEC CICS                                                    CICS1

005260         HANDLE ABEND LABEL(JZ-Abend-Exit) RESP(JZ-RESPONSE)      CICS1

005270     END-EXEC.                                                    CICS1

005280     PERFORM CICS-CheckStatus.                                    CICS1

Click Continue and it will run normally until the program exits, or you encounter another checkpoint.  You can set a checkpoint on any statement.   When it is stopped, you can examine the data in your program in various MFED windows like Watch and Autos. 

Jazz Program Structure

Details differ depending on the logic of the program, but all Classical CICS programs are generated with a standard structure illustrated by program CICS1

The first statement is always HANDLE ABEND, as above.

The COBOL then contains some standard code.  Mostly the program will be invoked with both an input message (screen), and a commarea, but when the program is first invoked it will usually have neither.   If there is no Commarea the program invokes itself with an empty screen and an initialized commarea.  If it is invoked with a commarea but no screen, it invokes itself with the passed commarea and an empty screen.

 

With normal entry (both Commarea and screen), there is some general initialization, then the program will   

005660         PERFORM JZ-Main-Program-Logic                            CICS1

 

The program will normally execute through its logic, and terminate via Normal-Exit: -

007010 JZ-Normal-Exit.                                                  CICS1

007100     EXEC CICS                                                    CICS1

007110         RETURN TRANSID('TRN1') COMMAREA(CICS1C) RESP(JZ-RESPONSE)CICS1

007120     END-EXEC.                                                    CICS1

007130     GOBACK.                                                      CICS1

However if there is an abend, or an abnormal response code, then the program will exit through Abend-Exit: -

007150 JZ-Abend-Exit.                                                   CICS1

007160*    BR14 does nothing, but is useful for CEDF/CEDX debugging     CICS1

007170     EXEC CICS LINK PROGRAM('JZBR14  ') COMMAREA(JZ-Program-Info) CICS1

007180         END-EXEC.                                                CICS1

007190     CALL 'JZABNDC' USING DFHEIBLK DFHCOMMAREA JZ-Program-Info.   CICS1

If you are testing your program in debugging mode then you’d put a checkpoint on the first line in Abend-Exit, line #7170 in the above example, so that you can find out the cause of the failure by examining the program’s data.  In a production situation you won’t be able to do this, in which case you might have to rely on JZABNDC and on extra diagnostic code.

Jazz Configuration Option : Generate Diagnostic Code

When Jazz generates COBOL there is an option that will generate extra diagnostic code into your program.  From the Jazz workbench click [Configure], and then the COBOL tab.  If you want this diagnostic code then check Generate Diagnostic Code: -

With this checked, MANASYS will generate extra MOVE statements to put the text of the current Jazz statement, and the current CICS statement, into a diagnostic area that is available to program JZABNDC.  For example, with this option turned on the GET statement generates this COBOL code.  Lines #9120-30 are not generated if the option is off.

009100*    GET Custf KEY(CustF.Account OR CustF.Name) SAVECOPY          CICS1

009110*                                               CICS1C.SAVE TS(1);CICS1

009120     Move '000190 GET Custf KEY(CustF.Account OR CustF.Name) SAVECCICS1

009130-        'OPY CICS1C.SAVE TS(1);' TO JZ-Jazz-Stmt.                CICS1

009140     PERFORM JZ-27-GET.                                           CICS1

Also, wherever there are EXEC CICS statements the text of the Jazz statement is copied to JZ-CICS-Stmt if the option is on.  For example,

018770         MOVE '018760 READ FILE(''CUSTF'') INTO(JZ-CustF) RIDFLD(ACICS1

018780-            'ccount OF JZ-CustF)' TO JZ-CICS-Stmt                CICS1

018790         EXEC CICS                                                CICS1

018800             READ FILE('CUSTF') INTO(JZ-CustF) RIDFLD(Account OF  CICS1

018810                 JZ-CustF) RESP(JZ-RESPONSE)                      CICS1

018820         END-EXEC                                                 CICS1

 

If [  ] Generate Diagnostic Code is unchecked these MOVE statements are not generated, making your program smaller and faster, but since MOVE statements don’t require I/O or Operating System calls they are fast and you may feel that the overhead is worthwhile in order to have the extra debugging help.

Program JZABNDC

JZABNDC is called when a CICS program abends or returns an unexpected response code.   If the program has been generated with Generate Diagnostic Code then it will terminate with a display like this: -

Without the Generate Diagnostic Statements the Jazz Statement and CICS Statement sections are blank: -

Obviously JZABNDC is more useful when debugging code has been generated, but in both cases the response codes and abend code are displayed, and the CICS system can be restarted by typing a transaction code over XXXX.

Various Response Codes

During my testing I encountered these response codes: -

12/FILENOTFOUND I had defined an FCT for CustF, it should have been CUSTF.    CICS object names should always be in capitals, as CICS and Jazz will convert lower case to upper, but Micro Focus ESMAC doesn’t.

19/NOTOPEN            Both CUSTF and CUSTF1 had [ü] Start Open checked. Could be an incorrect DSNAME, or perhaps a recent IDCAMS job still had the file open for exclusive use.

21/ILLOGIC                I tried unchecking Start Open, I didn’t fix the NOTOPEN problem, instead I got this.

Glossary 

.NET

Microsoft’s development framework – a series of support classes used by programs generated with Visual Studio.

ACCT

Not an acronym, but the name of project set up in MFES with the MF CICS tutorial.

ESMAC

Enterprise Server Management and Control

IDE

Integrated Development Environment.   For example Visual Studio (Microsoft), Eclipse (Open Source)

MF

Micro Focus

MFED

Micro Focus Enterprise Developer

MFES

Micro Focus Enterprise Server

PCT

Program Control Table.   Relates a transaction code to a program, e.g. MNU1 => MENU1

SIT

System Initialisation Table.  Used by CICS to identify a list of groups to be started.

VS

Visual Studio

PPT

Processing Program Table.  Defines programs that may be invoked by transaction id’s in the PCT

FCT

File Control Table.  Defines files (and their attributes) that can be accessed by CICS