This Help page tells you how to install and configure Jazz so that you can run it as in the examples shown in the videos. Click here to see these set up instructions as a video.
To run Jazz your organisation will have arranged for a licence that permits you and others to download and run Jazz from the Jazz Software web site, and your Jazz administrator will have given you a password with which to log on to the Jazz web site. Use your email plus this password to log on.
Log on, then click the button [Run Jazz]. This downloads a copy of Jazz to your computer, installs it, and puts an icon on your desktop to run it again. You can save the Jazz icon on your desktop or taskbar and continue running it by clicking this icon. This diagram shows what will happen: -
When you run Jazz from the icon: -
1. If you are connected to the Internet then Jazz will check with the website to see if there is a later version, and down load this if necessary.
2. If you are not connected to the Internet then Jazz will run anyway for about a month. However if it is longer than this then you need to go online again to refresh your licence, and to check that you have the latest version.
3. Of course running Jazz from the [Run Jazz] button is like running Jazz from the icon while you’re on line.
1. Jazz requires a Windows computer with an Internet connection. Tests have verified that it can be installed into Windows-XP, Windows-7, and Windows-10, and Windows environments on a Macintosh or Linux computer. This computer might be a stand-alone computer or laptop, or be part of a LAN.
2. To install Jazz the software is downloaded from the Internet using Microsoft ClickOnce technology. This installs the software into a “sandbox” where it does not interfere with any other programs. The install will also install the correct version of the .Net framework if it is not already installed. This framework will already be present with Windows-7 or later.
3. The browser that you use to install Jazz must have the Microsoft Clickonce extensions installed. This is standard with Internet Explorer and Edge, but with Firefox, Chrome, etc you may need to install an AddIn. Google xxxx ClickOnce (e.g. “Chrome ClickOnce”). If you have problems (see Trouble-Shooting Installation) try installing Jazz with Internet Explorer or Edge: you do not have to make them your default browser: once installed Jazz will run from the Jazz icon whether or not your default browser supports ClickOnce.
The first time that you run Jazz you will need to set it up.
1. First, decide where you will store your Jazz programs. If you’re working on your own this will probably be within your “My Documents” folder. If there are several members of your project team who will be using Jazz this should be on a common server and the reference to it should be the same for each of you, so that you can share various project files.
2. Start up Jazz by opening the JazzSoftware web page with a Microsoft Browser (Internet Explorer or Edge) or another browser with ClickOnce Add-in enabled and clicking the button [Run Jazz]. This will download a copy of Jazz into a temporary folder, check for pre-requisites (ASP.NET 4.0) and download them if necessary, and then start running Jazz. See Trouble-Shooting Installation if Jazz doesn’t start. You may see a screen like this: -
Click [Install] and this screen will appear as Jazz is installed: -
3. Define Windows Folders
Jazz then starts up, and immediately discovers that it is not configured correctly so instead of starting the Jazz Workbench it opens the Configuration form: -
To run Jazz you will need a folder that your Windows computer can access where Jazz can save programs, copy books, and so on. This may be on your own computer, or be on a shared LAN drive. The first set-up task is to define this Jazz folder (called the “common path”). Click [Locate] and you can browse to the folder you want, or create a new one. Here I followed the heirarchy from my Windows userid => My Documents where I located an existing folder called “Jazz”: -
Click [OK] and the common path is defined into my Jazz configuration. Jazz then checks that there this common path contains the required subfolders (which may all have the same name). If the folder already exists (which will be common if we are sharing a Jazz Folder with other Jazz users) Jazz will skip to the next subfolder. Here Jazz has found that my /Jazz folder contains Jazz_Programs, but doesn’t contain Jazz_CopyDefs.
If we are creating new subfolders we’ll probably just click [Create] to create a subfolder of that name, although we might use [Locate] to choose another subfolder within the common folder. In my case I used [Locate] to set it to Jazz_Programs.
NB: although Microsoft’s Browse for Folder dialog will let you navigate to a folder anywhere on your Windows system, Jazz requires that the subfolders be directly within the common path. There will be error messages if you select a folder anywhere else.
4. Initialise the Jazz Folders.
When the folders are created then Jazz will copy a number of standard objects – Jazz programs etc. – into the folders. If your Jazz folders are shared with other users then these will already exist, and you’ll get messages like this whenever Jazz finds a object already present: -
You’ll probably click [Ignore] or [Ignore All]. [Replace] or [Replace All] may replace objects which have been locally customised: check with your Jazz Site Admin.
Following Step 1 Jazz will display the Jazz Workbench. At this stage we run a very basic Jazz test to prove that we’ve configured it correctly so far: -
Jazz has analysed your program, colouring keywords and references, indenting statements to show logic, and reporting errors. If you were to look at PFirst.jzz with Notepad it would look like this: -
*# Last Updated by IBMUSER at 5/06/2017 9:26:29 a.m.
PROCESS PFirstR WHERE (PFirstR.Field1 = 'X' | PFirstR.Field1 = 'Y');
1.1. With PFirst displayed in the workbench as above, right-click “Program”. A web page will open telling you the rules of the PROGRAM statement. This shows you that Help is working correctly.
1.2. Change the program to introduce an error: for example changing “Program” to “Prgrm”. Click [Check]. Jazz will react to the error with a number of error messages. Right-click one of these errors: this will give you information about the error and how to correct it.
1.3. Click the Help menu item. You will see some Help Options: -
Explore these options to see what’s available under each option. Other than About, the options open Help pages from the Jazz web site.
We have completed basic set up, and Jazz is now able to check your program and (if it’s valid) generate COBOL. If we stop here we could use Jazz to create COBOL programs but we would have to manually submit the COBOL and relevant JCL to our zOS system if we want the programs to be compiled and run. The next stage is to set up Jazz so that it will do this automatically for us. We can edit our configuration at any time by clicking [Configure].
When we click [Configure] the form opens on the first tab, looking like this. This and the other configuration panels are fully described elsewhere. In this section we’ll briefly go through the Configure options, skipping over details that we don’t need yet. You can re-read this Help at any time by clicking F1 when the Configure form has focus.
You probably won’t change anything here, and you can always come back and change it later.
Some options that you may want to change from time to time: -
a. Error level. As Jazz processes your programs it will produce message when it detects conditions that are, or might be, errors. Error severity may be
· T Terminal error: Jazz can’t continue
· S Severe Error: Jazz can’t generate a correct COBOL program
· E Error: Jazz has made a correction that might result in a correct COBOL program
· W Warning: Jazz has detected a condition that might be an error. The program is probably correct
· I Information: This isn’t a problem, just something that Jazz thought you should know.
On the Language tab you can choose one of a maximum level: if Jazz reports errors of this severity level or greater then it won’t generate any COBOL. Occasionally you might want to change this from “E” to “S” to allow Jazz to generate some COBOL anyway, you won’t want to allow Terminal errors, nor will you want to disallow Warnings or Information
b. Include Jazz Program as Comments. Almost certainly you’ll leave this checked, as its only cost is a few extra comment lines in the COBOL ENVIRONMENT division.
c. Show dictionary entries in Jazz Program. Leave this unchecked: the extra comments are not useful at this stage. This is included for future development
d. Create Diagnostic Code. With this checked Jazz will generate statements to help with debugging in the event of error: you’ll usually be able to sort out what’s gone wrong from Jazz, without having to drill down to the level of COBOL. There is a slight cost to this, so you may choose to uncheck this to generate slightly smaller and more efficient programs. This is NOT recommended: the extra cost is minimal, and if you uncheck this and then your program fails you’ll have no option but understanding the COBOL logic. Probably the relative cost of the extra statements will be repaid many times over even if you only make one error in your Jazz-programming lifetime.
e. 3270 Screen Template. If you create your own standard 3270 screen template, then put its name here.
f. CICS Mapping Level. Set this to 3 or 4 depending on your CICS mapping level. The CICS Mapping Level affects the format of web service messages that have variable repeating sections: with 4 or greater Jazz will generate COBOL definitions with OCCURS nn DEPENDING ON xxx so that varying-length messages are handled. With less than 4 full-length messages are transmitted even if only a few occurrences are actually present.
Here’s where you describe your z/OS set up. So that Jazz can submit jobs for you: -
· Enter your mainframe userid. IBMUSER is my personal ID at my zOS test facility: Change this!
· Enter your mainframe password and repeat it. Passwords must be repeated exactly. Even if your z/OS system doesn’t care, here the password and its copy are regarded as different if one uses a capital where the other does not.
NOTE: These Mainframe Credentials are HELD ON YOUR LOCAL PC, they are NEVER transmitted back to Jazz Software or elsewhere outside your secure environment
Edit the JOB Statement. This will become the
//name JOB … statement at the start of your job. The default job statement is
//@Jobname JOB ,CLASS=A,MSGCLASS=H,NOTIFY=&SYSUID,COND=(8,LT)
Note that this has a job name of @Jobname: this is an example of a Jazz Symbolic Parameter, and will be replaced when the job is submitted. Read Jazz Symbolic Parameters if you want to understand more about these.
The JZL templates are written in the expectation that the condition code parameter, COND=(8,LT), is present, so if you edit the JOB statement then you should not remove it.
· To the right of the pro-forma job statement is a list of options for the way in which your jobs will be named: -
· @Userid + next suffix. If I had given my userid in #1 above as “Robertb”, then jobs will be named “Robertb1”, “Robertb2”, to “Robertb0”, then “RobertbA” to “RobertbZ”, then restart at “Robertb1” again.
· @Userid + [ ]. You can enter a character here: blank, 0 to 9, or A to Z.
· Program Name. This is the name of the program (or CICS Map) that is being compiled. For example, if you set this option and you’re compiling a program name “PFirst”, then the job will be called “PFirst”.
As written. If you choose this option you should
also edit the pro-forma Job statement to replace @JobName with the name that
you want to use. Every job you submit will have this name.
· Set the values that you use as your default Project, Group, and Type in your mainframe ISPF sessions.
· Give your ISPF and zOS library names according to your local standards, using @Parameters when relevant. For example here the source library is defined as “@Project.@Group.SRCLIB” which becomes “IBMUSER.MANAJAZZ.SRCLIB”.
· Give the IP address of your zOS system so that Jazz can use FTP to submit jobs. 220.127.116.11 is a dummy address, but without a real address that will recognize the IBM Userid and password Jazz can’t communication with your zOS system. Ask your system programmer for the appropriate IP address and Port number for FTP access to your z/OS system. If this setup is incorrect or if the zOS FTP system is not available when you click [Submit] then Jazz will create JCL but will not submit it.
· If you are developing web service programs, set the details in this section as described in the relevant users’ guide page. You might prefer to come back to this after your initial Jazz setup
You won’t need to set the Web Services section of this tab yet.
We’ve used [Check] to get Jazz to check our program for mistakes. Now we’re ready to generate a COBOL program and compile it. Right-click the [Process] button. The Process form appears: -
Uncheck “Show this form on left click” so that in the future we can simply click [Process] and have Jazz automatically create COBOL, JCL, submit the job, and then retrieve the output. Of course it is often convenient to right-click, and then take the process step-by-step from [Check] to [Submit]
1.1. Click [Generate] and Jazz will create a COBOL program, PFirst.CBL. [Find COBOL] will change to [Review COBOL]
1.2. Click [Review COBOL] to see the COBOL program that Jazz has generated for us. If you do not have a COBOL compiler on your PC then it may not recognise files with a .CBL extension, in which case the Windows dialog will ask you to select a program for such files. Select Notepad.
With the correct IP address and Port to access your z/OS system, and your Userid and Password entered, you should now have done enough to compile and run batch programs. Try this out with program PFirst. We can’t run it because file PFirstR doesn’t exist on the mainframe, but we should be able to submit and compile the program: -
1. Open the Jazz Workbench with program PFirst, as above.
2. Right-click [Process] to display the Process form
3. Click [Compile] This will
· re-check the program,
· generate COBOL,
· create appropriate JCL,
When the button [Job Results] turns green we can click this to see the output. If everything is set up correctly we’ll see a job that has compiled and linked our COBOL program.
This will have tested template JZCompilebatch.jzl. Other templates haven’t been tested yet. We might need to edit the JZL (Jazz-format JCL) templates.
When you click [Process] from the Jazz Workbench, or right-click [Process] and then click [Submit] button on the Process form, Jazz will create a job stream to compile [and run] your job. It uses JZL templates to do this: these templates were installed when you clicked the [Initialize Project] button in Set Up, Step 1. Configure Jazz above. JZL templates have extension “.jzl”, they are normal z/OS JCL except that
1. They may contain Jazz symbolic parameters, names like “@Jobname” that start with “@” and are known to Jazz. They may also include normal z/OS symbolic parameters: these start with “&”.
2. They may be longer than the 72-character maximum length of standard z/OS JCL. When Jazz converts them to JCL to create a job it will handle continuation characters and break the over-length line at an appropriate point.
Probably the templates won’t need much changing at this stage (you can always change them later), but in case you want to review them here is a list: -
Compile (assemble) a BMS map. This is automatically done from the Jazz screen editor when you click [Process]
JCL for compiling and linking a batch program
JCL for compiling and linking a batch program that uses SQL (DB2, Oracle, etc). See Note 1
JZL for compiling and linking a CICS program
JZL for compiling and linking a CICS program that uses SQL (DB2, Oracle, etc). See Note 1
An IEBGENER step. Not used now
JZL that is used for the GO step of a batch job (which is the only step if you submit a run-only job). This includes a few standard DD statements: in addition extra DD statements will be generated from DEFINE statements that include a DSNAME option. All these extra DD statements will have DSNAME options and DISP=SHR and so you will need to modify the JCL if your job is creating a new data set (requires DISP=(NEW,KEEP) and a SPACE parameter), or is updating it and requires DISP=OLD to give it exclusive access.
A JCLLIB statement that is used with Web Service jobs
Used for Web Service Provider programs
Used for Web Service Requester programs
Note 1. These SQL procedures have been included for our own (Jazz Software Ltd) own testing. SQL features haven’t been released yet, and they have not been proven correct.
After Set up, Step 3.
Add error text to message field
Return N of M for CICS scrolling
Used with A = B && C RTRIM;
Used to trap abends and display JZ-Program-Info
General. CICS subroutines should be compiled and linked into the CICS load library so that they can be linked into CICS programs. Batch subroutines should be compiled and linked into the batch load library. Some subroutines need to be compiled and linked into both.
1. BR14 does nothing, but in CICS programs Jazz generates code to invoke it within the program’s Abend exit: -
* BR14 does nothing, but is useful for CEDF/CEDX debugging
LINK PROGRAM('BR14') COMMAREA(JZ-Program-Info)
This can be useful if you need to debug your COBOL program with CEDF.
2. JZDT01 will be required in all batch programs that include a PRINT statement, which is almost all of them.
3. JZDT02 might be used in either CICS or Batch programs. It will need to be compiled into both CICS and Batch load libraries.
4. If errors are trapped in a CICS program, for example from I/O commands, then JZABNDC will be called to produce error messages that are more relevant to Jazz programmers than COBOL-Level diagnostics. You may modify this routine to comply with your local standards: if you do so, then ensure that your version is not replaced with later Jazz versions.
5. Will be used if validation errors are detected by ACCEPT statements in classical CICS programs. The function of JZMSAD is to add error text into the message field following previous error messages, if any, and allow for overflow if there is insufficient room to fit on the line. The message field is an output field in a 3270 screen.
6. JZNOFM is used to return “N of M” in classical CICS programs when PF7/8 and PF10/11 are used for Up/Down and Previous/Next scrolling.
This is used when an assignment statement uses RTRIM, e.g.
trims.result2 = w.name1 && w.name2 RTRIM;
It may be used in both CICS and Batch programs.
CALL ‘JZSTXIT’ USING JZ-Program-Info.
immediately following the line PROCEDURE DIVISION. JZSTXIT is Assembler code, supplied as JZSTXIT.JCL. Its purpose is to trap abends and produce diagnostics telling you what is wrong at the level of Jazz so that user’s don’t have to dive into a dump, then relate this back to COBOL, then back to Jazz, to find out what’s wrong.
To make JZSTXIT available edit this JZSTXIT.JCL: -
· Check that the JOB statement is compatible with your local standards, and
In the LKED step, //SYSLMOD DD, replace
“Your_Batch_LOADLIB” with the name of your batch load library so that JZSTXIT
will be found by LKED to link into your programs. For example, we used
//SYSLMOD DD DSN=IBMUSER.MANAJAZZ.LOADLIB(JZSTXIT), …
When you’ve edited the JCL, submit the job
JZSTXIT will trap abends and display the contents of JZ-Program-Info on DD SYSOUT. If the abend is recoverable, meaning: -
1. The abend type is one of
a. A Data Exception
b. Fixed-point Overflow
c. Fixed-Point Divide
d. Decimal Overflow
e. Decimal Divide
f. Floating-Point Divide
2. The abend has occurred in your main program, not in a called subprogram
3. You have not exceeded your abend limit. This is set in Jazz configuration, see parameter STXIT limit on the Lang or System tab.
The abend is NOT recoverable if any one of these three conditions are true. For non-recoverable abends, Jazz abend diagnostics are followed by the standard COBOL dump.
To illustrate Jazz diagnostics faulty record definition CustFE was prepared by defining Name as CHAR(16) instead of CHAR(15) so that following DECIMAL (=packed) fields are in the wrong position. SalesYTD =+ 1; now throws a data exception (S0C7), and JZSTXIT produces a display like this: -
JZSTXIT - ABEND FROM JAZZ PROGRAM HANDLED
ABEND OCCURRED: S0C07 DATA EXCP
ABEND PSW ADDRESS: 00007776
ABEND DISPLACEMENT: 00000770
JAZZ PROGRAM INFORMATION
PROGRAM ID: PROGRAM PrCustfe
WRITTEN BY: IBMUSER (Using Jazz, 18.104.22.168)
LAST UPDATED: 10/03/2017 1:14:24 p.m.
CURRENT JAZZ STATEMENT: 000110 CustFE.SalesYTD += 1;
RESTART POINT: JZ-12-PROCESSGroup
CURRENT RECORD COUNT: 000000001
CURRENT RECORD LENGTH: 00044
CURRENT KEY LENGTH: 00006
CURRENT KEY: DISPLACEMENT 00000------
CURRENT RECORD: DISPLACEMENT 00000---------|---------|---------|---------|----
000001 %MCNAUGHTON,Vera -š*2013-06-11
With the STXIT limit set to 5 there were 5 such displays before the program was terminated with
CEE3250C The system or user abend U 100 R=NULL was issued.
From compile unit BATCH1 at entry point BATCH1 at compile unit offset +00004EC6 at entry offset +00004EC6 at address
and the normal dumps are also produced as if JZSTXIT were not present. To be able to find the error instruction and data fields you should use PARM=(MAP,LIST) on the IGYWCL (COBOL compile) step.
In the dump: register 2 displacement 4 points to the PSW, register 15 displacement 4 points to the registers at entry to JZSTXIT, register 5 points to the instruction causing the crash.
After the steps above have been completed then
1. Using a small mainframe test file,
a. Import a COBOL record layout into Jazz, and edit it to add missing information such as its DSNAME.
a simple batch program to print a report from it. This will test that the JZGO template is
correct for you.
2. If you are going to be writing Classical CICS programs you should
a. Examine the supplied 3270 screen template, TMPL01. If you wish to have a template that reflects your local standards, you can either create a new one with a different name, or edit TMPL01.
b. Examine, and edit if necessary, the JZL templates JZAssembleMap for assembling screen maps, and JZCompileCICS for compiling CICS programs.
c. Test these by creating a basic CICS program such as CICS2, at least to the stage of proving that the screen and program compile correctly.
may need help from your system programmer to ensure that your CICS test system
is correctly set up. CICS setup is not
the responsibility of Jazz.
3. If you are going to be writing Web Service programs you should
a. Examine, and edit if necessary, the JZL templates JZJobProc, JZWSProv, and JZWSReq.
c. You will need help from your system programmer to get your first web service program running.
Various folders store Jazz Programs, Copy Books, Screens, JCL, and other types of objects. By giving the same folder name for Jazz Programs, Jazz Copy Code, etc you could use a single folder for all these different types as Jazz uses the filename extension to denote the type of object, and there may be many objects with the same basic name but with different extensions. This is different to the mainframe world where one PDS holds COBOL programs, another holds JCL, and so on.
Jazz currently recognizes the following extensions/object types: -
.CBL COBOL program (generated by Jazz, or from an external source (e.g., downloaded from zOS when converting COBOL to Jazz))
.JCL zOS JCL. May be produced as a result of [Submit] being clicked, and built from various .JZL templates.
.jzc Jazz Copy Book. One or more DEFINE statements, and/or COPY statements. Once of the DEFINE statements should have the same name as the copy book.
.jzd Jazz Data Dictionary. This extension is reserved for a future development, in which Jazz will record data usage across all the programs of a project. It has XML format.
.jzl Jazz-format JCL. This is essentially standard zOS JCL except that it may contain Jazz parameters, and JCL statements can be of any length. Both JCL and COBOL statements may initially extend beyond column 72: this is sorted out when the JCL and COBOL is written out.
.jzm CICS 3270-type screen map. Used to generate the physical map used in classical CICS screens.
.jzs Jazz 3270-type screen. This contains both layout and data type rules, and is edited by the Jazz Screen Editor
.jzt Jazz templates. These are templates for various types of programs. Note that the templates are very basic, mostly the form of the generated program is controlled by the logic in the Jazz Workbench.
.jzw Web service descriptions. XML documents describing the web services that Jazz has discovered. These are somewhat simplified compared to the original WSDL, containing only the information that Jazz needs.
.jzz Jazz Program. This code should start with PROGRAM xxx or SUBPROGRAM xxx, where ‘xxx’ is the name of the .jzz object.
.txt Text. Jazz uses this when downloading jobs.
.xls Excel Spreadsheets
.xlsx Excel Spreadsheets
Jazz has been built with the option “The application is available offline as well (launchable from Start menu)” and so it will install on your computer, although it is sandboxed by Microsoft’s ClickOnce technology, and so can’t access your Windows system except the folders that you define with your Jazz configuration. This will enable you to run it for a while without being connected to the JazzSoftware.co.nz web site, but it will check to see if an update is available when you start Jazz. We have chosen this option so that you are not inconvenienced by breaks in service from the Internet or the Jazz web site. However Help requires the web site to be available. You will need to access the web site at least monthly.
Jazz can only access your mainframe in the same way as a COBOL application programmer using TSO: it has no special privileges or its own LPAR, and NOTHING is installed on the mainframe except for the minor subprograms described in Set up, Step 4. Compile Support Subprograms. Our expectation is that you configure zOS access only to your test environment (batch and CICS), continuing to follow the same procedures for promoting developed programs from test to production as you do now, and using the same software tools as you would when you’re writing programs manually.
Jazz is at an early stage and we expect errors and missing features. Let us know of any problems you find, and suggestions for improvement.
Jazz is delivered as a Microsoft ClickOnce program: click the Run Jazz link and Jazz should start up and install itself on your computer. If Jazz does not install cleanly from the web site www.jazzsoftware.co.nz, then the most likely cause is that you’re using a browser that does not have support for Microsoft ClickOnce programs. To confirm this, try Run Jazz using Internet Explorer or Edge.
This is the simplest fix for this problem: install Jazz using a Microsoft browser. You don’t have to make this your default browser if you prefer to keep using Chrome or another: from now on you’ll start Jazz by clicking the icon that you’ve put on your desktop or taskbar.
You can install with Firefox, Chrome, etc by installing an AddIn. Google xxxx ClickOnce (e.g. “Chrome ClickOnce”). Later versions of FireFox seem to have blocked Microsoft .Net Assistant but built in ClickOnce support.
We have seen the following error symptoms when an attempt has been made to install Jazz from a page opened by Chrome without ClickOnce support.
2. Jazz downloaded and displayed the configuration form, and everything appeared to work as normal until it reached the point where the Jazz Workbench should have been displayed. At that point this message was displayed: -
This error is incorrect: the Jazz web site would have sent a license token, the problem is that the browser is not recognising it. Clicking [OK] leads to: -
and [Continue] leads to further errors.
3. An earlier version of Jazz reported the error as: -
On clicking [Details] you saw something like this: -
PLATFORM VERSION INFO
Information about your Windows environment
Deployment url : Where it was installed/Jazz.application
Deployment Identity : Jazz.application, Version=22.214.171.124, Culture=neutral, PublicKeyToken=4a9f8c94079d1f42, processorArchitecture=x86
* Installable application.
* Trust url parameter is set.
Below is a summary of the errors, details of these errors are listed later in the log.
* Activation of Where it was installed\Jazz.application resulted in exception. Following failure messages were detected:
+ Deployment and application do not have matching security zones.
More diagnostic information