Training Objects: Creating Test Data
for Jazz Tutorials
Running your job, and viewing the
output
Jazz videos
and Users’ Guide tutorials use various files to demonstrate Jazz features. It is recommended that new users use this
section as initial training, working through creating and printing at least
some of the files, in order to develop initial familiarity with MANASYS Jazz before
exploring more sophisticated programming than basic file reporting.
Training
objects, shipped with Jazz and downloaded when you click [Add Training] from
the Configuration form, create these files. This Users’ Guide section tells you
how to use these objects to create the files.
You can download these items selectively as you need them, or simply
select and download them all.
The files
are very small, only 300 Customers, 10 Regions, only a few Parts and
Orders. This is enough to demonstrate a
variety of situations like look up a record, look up a record that isn’t there,
handle page overflow etc, but not enough to demonstrate large-scale processing
or do stress testing. They are designed
to help you with Jazz training, where small (and quick) tests are better than
processing production-scale data sets that typically just repeat the same
demonstration thousands of times.
To download
the training objects,
1. Open the Jazz Workbench and click
[Configure]
2. Click [Add Training]. This opens a Windows Explorer showing the
objects available for download
3. Select the items you want to
download. To select all, select the
first, and then with Shift pressed select the last.
4. Click [Open]. In this context this means “Select” and the
selected objects are downloaded into the appropriate Jazz folders.
You don’t
need to do every step of this topic in order: for example, if you don’t want
file FR you can skip that section.
However, to create file CUSTF you must have created file IN1. Such dependencies are noted. Material specific to Micro Focus will be in Appendix 1: Micro Focus, and material specific
to z/OS will be in Appendix 2: Z/OS so that
irrelevant material does not get in your way.
Start with the next section, Create Sequential File IN1, as this illustrates creating files with both zOS and Micro Focus. Later this chapter mostly uses Micro Focus projects called CWSProject, ACCT, or TstSQL. Wherever this chapter refers to (for example) “The ACCT button” or “The ACCT project”, then substitute the name of your own MF Project. In the graphic directly below this is the button [CWSProject]. If you’re using zOS the button will be [Job Results].
File IN1 is
used in some examples: it is a basic sequential file containing 300
records. Program IN1W.jzz, one of the
objects available within the folder of Training Objects, will create this file
for you. Open program IN1W, click
[Check]:-
Message
#378 warns us that we may have to change the JCL. With Micro Focus Enterprise Developer(MFED)
we change the JCL within the Micro Focus COBOL project. If z/OS is our test
system, then this is done before the job is fully processed. Refer to
Generating the file – MFED
or Generating the file – z/OS
If you want
to independently print the file you’ve just created, there is a program
IN1R.jzz downloaded with the training objects.
If you want to do this, open Jazz program IN1R and [Process] it.
With z/OS,
when the [Job Results] button turns green click it to see the job output. With MFED this button will have a project
name ([MFJazz1] in the example above).
Click this to open the MF Cobol Project, add IN1R.CBL and IN1R.JCL to
it, build the solution, then submit the JCL.
Results will look something like this: -
Play around
with the program, for example, try changing the record order. Change the list of fields printed. Make a mistake, and see what happens, then
correct the mistake (you may have already done this by now 😊)
This is
similar, using programs FRW to write the file and FRR to read it, but a difference
is that FR is a VSAM file so a VSAM cluster is needed.
The record
FR has already been defined to Jazz (FR.jzc is one of the items downloaded when
you clicked [Add Training]): -
DEFINE FR VSAM DATA(
Region PIC '999'
Name CHAR(30) VALUE('No Record found')
HEADING 'Region
Name',
Fill CHAR(47))
DSNAME 'JAZZUSER.VSAM.Region';
Creating a
VSAM cluster from a Jazz definition is easy.
From the Jazz Workbench, click [New] and Select /Data/VSAM to open the
VSAM form: -
Click
[Browse] and browse to the definition fr.jzc.
It’s in the \Jazz_CopyDefs subfolder of your project folder
Check
[ ] Cluster
Set the number
of 1ry records you expect to have in the file.
FR is very small, 10 will do.
Click
[JCL]. The button changes to [Review],
allowing you to see and edit the JCL, and the middle button becomes
active. Click it to create the cluster:
-
Micro
Focus
z/OS
Open
program FRW. Click Process]: -
With z/OS,
when the [Job Results] button turns green click it to see the job output. With MFED this button will have a project
name ([TstSQL] in this example). Click
this to open the MF Cobol Project, add FRW.CBL and FRW.JCL to it, build the
solution, then submit the JCL and examine the job output.
Repeat this
process with program FRR to print the file: -
As above, with
z/OS, when the [Job Results] button turns green click it to see the job output. With MFED this button will have a project
name ([TstSQL]). Click this to open the
MF Cobol Project, add FRW.CBL and FRW.JCL to it, build the solution, then
submit the JCL.
Here is the report printed in the job output, showing that we’ve created the test data as expected: -
Now the file FR exists it can be used in batch programs. Go back to program IN1R, and add statements to print the region name as well as fields from IN1. You’ll write GET FR … somewhere in your program: use Help to figure out what you actually need to write. What happens with a Region value of 7?
In the Classical CICS and Web Services tutorials, the earlier example programs require a VSAM file Custf, while the later programs also require a related file called ORDERS. Both are VSAM files, but unlike FR they both have alternate indexes. This makes the VSAM definition a three step process.
1. We use New/Data/VSAM to define the cluster.
2. A program (CustFW, OrdersW) is run to load data into them.
3. After they have been loaded a second VSAM function is used to create the alternate indexes.
Before CustF can be loaded we must have created sequential file IN1. Although this is not used in the CICS programs, the program Custfw.jzz that writes data into Custf is based on logic to copy IN1 to Custf, so it is needed in step Load Custf.
Here is the definition of CustF (from the Jazz Copy Books folder, included from Jazz with training objects). Note that as well as the primary key Account there is a duplicate key on Name. This will require an alternate index to be created. However VSAM doesn’t allow us to create an alternate index until we’ve initialised the cluster by writing some data into it.
First, we define a VSAM cluster as we did for FR.
· From the Jazz Workbench select Data/VSAM.
· Browse to the \Jazz_CopyDefs\Custf.jzc, and check Cluster.
· Set 1ry to 300, and click [JCL].
Jazz will have created this JCL to create the VSAM cluster: -
//JAZZUSER JOB ,CLASS=A,MSGCLASS=A
//JZVSAM2 EXEC PGM=IDCAMS Manage VSAM Data Sets
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
DEFINE CLUSTER (NAME (JAZZUSER.VSAM.CUSTF) -
RECORDS(300 30) -
RECORDSIZE(53 53) KEYS(6 0) INDEXED)
/*
This JCL is processed exactly as described for
FR, and from the job output we check that the cluster was created as expected.
Program CustFW, which is included in the Training objects, will create an initial 300 records.
Open program CustFW: -
Like FRW we can compile and run this program to load initial data into the cluster, but unlike FRW we must first edit the JCL. The JCL has been generated including a DD for the alternate index, but the alternate index doesn’t exist yet.
//*** Run BATCH PROGRAM in IDE with
Micro Focus Enterprise Developer
//JAZZUSER JOB
,CLASS=A,MSGCLASS=A
//GO EXEC PGM=CUSTFW,TIME=(0,10)
//SYSOUT DD SYSOUT=*
//PRTERR DD SYSOUT=*
//SNAP DD SYSOUT=*
USED BY JZSTXIT
//* Inserted DD statements based on
program
//FR DD DSNAME=JAZZUSER.VSAM.REGION,DISP=SHR
//CUSTF DD DSNAME=JAZZUSER.VSAM.CUSTF,DISP=SHR
//CUSTF1 DD
DSNAME=JAZZUSER.VSAM.CUSTF1,DISP=SHR
//IN1 DD DSNAME=JAZZUSER.FILES.IN1,DISP=SHR
//REPNBR1 DD SYSOUT=*
Remove the line //CUSTF1 DD …
and save CusftW.JCL.
With this change made, compile program CustfW and submit CustfW.JCL. The output shows the 300 created records.
Now return to Jazz, invoke Data/VSAM, this time checking the AIX checkbox.
If the bottom-left button has caption [Review], not [JCL], click [Review] to change it back to [JCL], then continue …
Click [JCL] to create it. If you review it, you’ll see that CUSTF.JCL will now create the alternate index and path: -
//JAZZUSER JOB ,CLASS=A,MSGCLASS=A
//JZVSAM3 EXEC PGM=IDCAMS Manage VSAM Data
Sets
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
/* AIX ON FIELD CUSTF.NAME */
DEFINE AIX (NAME(JAZZUSER.VSAM.CUSTF1.AIX) -
RELATE(JAZZUSER.VSAM.CUSTF) -
RECORDS(300 30) -
KEYS(30 10) NONUNIQUEKEY UPGRADE REUSE)
DEFINE PATH(NAME(JAZZUSER.VSAM.CUSTF1) -
PATHENTRY(JAZZUSER.VSAM.CUSTF1.AIX) UPDATE)
BLDINDEX INDATASET(JAZZUSER.VSAM.CUSTF) -
OUTDATASET(JAZZUSER.VSAM.CUSTF1.AIX)
/*
With Micro Focus you don’t need the BLDINDEX command so you can remove it if you like. However it will be ignored with a harmless message if you don’t. Submit this JCL
Now that the alternate index is created, you can use CustF like FR in batch programs, both for sequential processing (PROCESS), and direct lookup (GET) using either Account or Name as key field.
Program
CICS3 and some of the later Web Service objects use 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: -
The notes
below are illustrated using Micro Focus project TstSQL, which was used for Web
Service and DB2 testing. Explanations
can be relatively brief, as you can refer back to CustF to see screen snaps.
Parts.jzc
looks like this: -
DEFINE Parts VSAM DATA(
Partnbr INTEGER KEY,
PartName CHAR(30) DKEY 'ibmuser.vsam.parts1',
#647 W CAPS/LOWER option recommended
StandardPrice DECIMAL(7,2))
DSNAME 'ibmuser.vsam.Parts';
You may
ignore message #647, as it is not likely to cause problems for our use of Parts
in Jazz training. Message #647 is
produced when CHAR keys are
used in a key (KEY, DKEY, or UKEY) as
mixed-case keys are difficult to use, for example you’ll find the first record
with “8M Tape Measure”, but not with “8m tape measure”.
2.
Start
dialog Data/VSAM
3.
Browse
to Parts in the Jazz Copybooks folder, and ignore messages about Jazz Messages
Present.
4.
Click
Cluster, and allow for 15 records.
5.
Click
[JCL]. Process the JCL with MFED or
z/OS to create the cluster
Now that
the cluster exists, we use program PartsW to load it. As with CustFW that loaded CustF, MANASYS
will generate JCL assuming the alternate index exists so we need to edit the
JCL before it is run.
1.
Open
PartsW.jzz with MANASYS, and Process it to produce COBOL and JCL
2.
Edit
Partsw.jcl to remove the unwanted //Parts1 DD …
3.
Process
the COBOL and JCL with your test system (MFED or z/OS), running program PartsW
with the modified JCL
4.
Results
will look like something like this: -
1.
As
we did with CustF, we create the alternate index on PartName using Data/VSAM
again, this time checking the AIX checkbox.
2.
Click
[JCL], and submit it to the test system (MFED or z/OS)
Check that
the job ran correctly, with Condition Code 0000
We have now created a small parts file, with parts numbered 1 to 10, and an
alternate index on PartName. 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 a demonstration.
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 when
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.
Because of
these relationships, we’ve left Orders to last, as we cannot create the Orders cluster
and indexes until we have created both CustF and Parts.
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 Data/VSAM to create appropriate JCL. Allow for 300 records
2.
Open
program OrdersW.jzz in MANASYS, and process it to produce COBOL and JCL
3.
Edit
OrdersW.jcl to remove the unwanted // Orders1 DD … and // Orders2 DD …
4.
Compile
the COBOL, and submit OrdersW.jcl to run it
5.
Use
Data/VSAM again to create JCL, this time clicking the AIX checkbox.
6.
Submit
this JCL to run it
We have now done enough to use CustF, Parts, and Orders in batch programs. For Classical CICS and CICS Web services we need to create appropriate table entries: FCT to identify files, PCT for transaction codes, and so on, and to understand the logic of these programs and how to write them. To learn how to do this, have a look at the relevant Users’ Guide pages (https://www.jazzsoftware.co.nz/Docs/jazzUG1.htm).
Start with Jazz On Line Programming - Introduction
For Classical CICS (3270), users should continue with
Or Jazz Classical CICS Progamming with Micro Focus
For web services, start with Service Oriented Architectures and Web Services: Introduction
Then continue with
Or Web Services with MANASYS Jazz and Micro Focus
There was no need to provide any test data for DB2, because IBM supply a sample database as a downloadable option with DB2 LUW (Linux, Unix, and Windows), and presumably with DB2 ZOS, and this was used for our examples and testing. See Working with SQL (DB2 and other relational databases) for more information. I added a couple of fields to the Employee table for my own testing, these are not present in the original Sample database and you won’t need them.
DEFINE EMPLOYEE SQL DATA(
…
CURRENCY CHAR(3), [Test COBOL reserved word in SQL Table
DEPTMGR BOOLEAN); [Test handling of CHAR(1) as BOOLEAN
This
appendix contains material that is relevant when MANASYS Jazz is configured to
work with Micro Focus Enterprise Developer (MFED). Links in the main text will bring you to the
relevant section, at the end of each section “Return to main text” will take
you the next topic in the main text.
Click
[Process]. Jazz generates COBOL and JCL,
and the project button ([CWSProject] in this example) turns green. Click this to open the MFED COBOL project in
Visual Studio. Look at the Solution
Explorer window. Although we have just
generated COBOL into the \cbl folder, there’s no sign of it, nor of the
JCL.
They need
to be added to the project. Right-click
the project, and choose Add/Existing item. A FileOpen dialog appears. Open the .cbl subfolder. You will see a number of .cbl files that are
not in the project: -
Select IN1W
and all the JZxxxx routines. JZxxxx
routines are general-use routines: for example, JZDT01 formats a date on a
printed report, JZDTAR is used if your program contains DATE arithmetic. It can be difficult for you to know when they
are used, it’s easiest to just include them all in your project.
To add the
JCL, again right-click the project and choose Add/Existing item. This time navigate to the Jazz_LocalJCL
folder, and select IN1W.JCL.
In Visual
Studio/Solution explorer, our project now looks like this when we expand cbl
and Jazz_LocalJCL: -
Double-click IN1W.JCL to open it, and edit it as described above for
z/OS: -
Change the
//IN1 DD statement from
//IN1 DD DSNAME=JAZZUSER.FILES.IN1,DISP=SHR
to
//IN1
DD DSNAME=JAZZUSER.FILES.IN1,DISP=(NEW,CATLG),
// SPACE=(TRK,(1,1))
Save this.
Right-click
the project and click Build.
If your project has been defined like TSTSQL with SQL enabled you may
get error messages like this: -
for program IN1 and the JZ modules.
This is because we haven’t yet completed SQL setup, and the SQL switch
routines aren’t yet available. None of
these modules require SQL, so you can get rid of these messages by setting the
properties of the individual COBOL programs: -
·
Right-click
the object, say IN1W.CBL, click Properties
·
Click
the SQL tab. Check [P] Set explicitly no SQL.
You may get
errors because the project contains objects have been created with COBOL
dialect Micro Focus, but the Jazz objects expect COBOL dialect IBM Enterprise
COBOL. The supplied training programs
include code like this which is invalid with other COBOL dialects.
000350 FILE-CONTROL. IN1W
000360 SELECT IN1 ASSIGN TO IN1 IN1W
000370 FILE STATUS IS IN1-STATUS. IN1W
000380 SELECT RepNbr1 ASSIGN TO RepNbr1 IN1W
000390 FILE STATUS IS RepNbr1-STATUS. IN1W
Change the
project’s COBOL dialect to IBM Enterprise COBOL and rebuild. Now the errors disappear from IN1W.cbl, but
there may now be errors with previous programs.
For example, in project LoanDemo there were errors with book.cbl.
Right-click
book1.cbl, click Properties. Set the
COBOL dialect for this to Micro Focus.
Rebuild. Now the project builds
cleanly.
We could
have done this the other way around, leaving the project’s COBOL dialect as
Micro Focus and changing IN1W to use IBM Enterprise COBOL. I have chosen to change the project default
because there will be more Jazz programs added to it.
If you have previously run batch programs from this project then you can
now run program IN1W. If this is the
first time you’ve run a batch job in this Micro Focus project, you may need to
enable JES.
If this is
the first time that you have attempted to run batch programs the output will
show messages like this: -
Submit JCL file starts ...
Submit JCL file to TSTSQL
completed
CASBJ0050E JES support not
enabled; Job rejected 10:08:07
Processed
"C:\tutorials\TstSQL\Jazz_LocalJCL\IN1W.JCL"
To enable
JES: -
·
Open
ESMAC (right-click Micro Focus Servers in Visual Studio/Server Explorer, click
Administration)
·
Click
[Edit] corresponding to the server
·
Navigate
to Server/Properties/MSS/JES, and check Job Entry Subsystem enabled: -
·
Click
[Apply]. Close ESMAC, return to Visual
Studio
·
Server
Explorer: restart server LoanDemo
Run your job from the MF Project by: -
·
Solution
Explorer, right-click IN1W.JCL. The Job
is submitted and run, and the Output window shows
·
Clicking
the link shows the job output
·
Program
IN1W writes a report to file REPNBR1.
Click this link to see the 300 records written to the file
Return to
main text – Print file IN1 (Optional)
On clicking [JCL] the VSAM form closes and you’re returned to the Jazz workbench, with a dummy program JZVSAM. The [TstSQL] button will be highlighted.
· Click this to open your COBOL project. The newly-created object, FR.jcl, is in not in the project unless you’re doing this again, so right-click the project in Solution Explorer, and click Add/Existing item. Browse to FR.JCL, and click [Add].
· Solution Explorer: Right-click FR.JCL, click Submit JCL
·
Click the link from the output page to review
the job output.
·
Click SYSPRINT to confirm that the cluster has
been defined
Return to
main text – Create Test Data for FR
This
appendix contains material that is relevant when MANASYS Jazz is configured to
work z/OS directly. Links in the main
text will bring you to the relevant section, at the end of each section a link
“Return to main text” will take you the next topic in the main text.
Right-click [Process] and then click [JCL]. Jazz runs the first three steps: [Check],
[COBOL], and [JCL], but then stops with the Process form displayed and the
button [Find JCL] changed to [Review JCL].
Click [Review JCL] and change the //IN1
DD statement from
//IN1 DD DSNAME=JAZZUSER.FILES.IN1,DISP=SHR
to
//IN1 DD DSNAME=JAZZUSER.FILES.IN1,DISP=(NEW,CATLG),
// SPACE=(TRK,(1,1))
Save the
edited IN1W.JCL, then click [Submit] to submit the compile and go job. You are returned to the Jazz Workbench. When
the job has run [Job Results] turns green.
Click this to see the job output.
Return to
main text – Print file IN1 (Optional)
The [JCL] button changes to [Review], and the [Submit] button will be activated. You can review the job and edit it if you wish.
Click [Submit] to submit the job to z/OS. The VSAM form closes and you’re returned to
the Jazz Workbench. When the [Results]
button turns green you can view the job output.
Return to
main text – Create Test Data for FR