Jazz Set Up

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. It has been updated to the latest version of Jazz, currently 3.17.2.312, results may differ with earlier versions.

You are probably already familiar with the Jazz Software web site, but if you haven’t already done this then it’s worth taking a few minutes to: -

· On the home page, view the Initial Demonstration. While this is only a small part of what MANASYS Jazz can do, it will illustrate its features and philosophy with a very basic problem.

· Look at the descriptions of the other videos to get an idea of what MANASYS Jazz can do. Look at any that interest you.

· Look at the Help and Training Page so that you know what’s there so that you can find it when you need to. You’ll see that the overview videos are repeated, there is also a video training course (always a work in progress), and a third section labelled “Help Pages”. The two most important help groups are Language Reference, and Users’ Guide.

Click here to see these set-up instructions as a video. Note: this video shows an earlier Jazz release. While the video remains useful, this document provides more accurate documentation about how to set up and configure MANASYS Jazz.

Your organisation may have arranged a licence that permits you and others to download and run Jazz from the Jazz Software web site, and your Jazz administrator may have given you a password with which to log on to the Jazz web site. Use your company email, plus the password if the administrator has given you one, to log on.

You can also download Jazz using your personal email like yourID@gmail.com. In this case you’ll be asked to register on the Jazz web site, and then you can download an evaluation copy that will function normally for a month. Contact us if you want to convert this into a permanent copy.

In either case when you download a copy of MANASYS Jazz you must be visiting our web site with a browser that supports Microsoft ClickOnce™ technology. We recommend a Microsoft browser (Edge or Internet Explorer), but you do not need to make this your normal browser if you prefer to keep using another. When you click the button [Download Jazz] on the download page, a copy of MANASYS Jazz will be downloaded to your computer and installed. If you have any problems, see Trouble-Shooting Installation in this page, you may find the answer there.

With MANASYS downloaded you’ll then configure it to tell it where its files will be and what options you want, and then you’ll be able to use it. This diagram shows what will happen: -

With MANASYS Jazz downloaded and configured,

1. You can start Jazz by clicking Download MANASYS Jazz as before. If you are connected to the Internet then Jazz will check with the website to see if there is a later version, and download this if necessary.

2. If you click the MANASYS icon that you set up inJazz Icon for Quick Restart then Jazz will start without checking for a new version, for about a month since the last download. However if it is longer than this then you need to refresh your licence by clicking Download MANASYS Jazz. This is very quick, especially if the software hasn’t changed, and Jazz will start and immediately pick up your previous setup – you DO NOT need to go through the setup process again.

PREREQUISITES.

1. Jazz requires a Windows computer with an Internet connection. Tests have verified that it can be installed into Windows-7, Windows-10, Windows-11, 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. Earlier Windows versions are no longer supported, and some functions (particularly DB2 support) will require an x64 computer.

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.

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 see Edge Special Note), but with Firefox, Chrome, etc you may need to install an AddIn. Google xxxx ClickOnce (e.g. “Chrome ClickOnce”) to find this AddIn. If you have problems (see Trouble-Shooting Installation) try installing Jazz with Edge: you do not have to make it your default browser. Once installed Jazz will run from the Jazz icon, including full Help support, whether or not your default browser supports ClickOnce.

4. You will need access to a z/OS environment where you can compile and test your programs. This may be a real IBM mainframe (I’ve used the IBM Dallas Test Centre), or a simulated mainframe such as the Micro Focus Mainframe Subsystem. You may set Jazz up to work with either or both environments. IF YOU DON’T HAVE A LOCAL COBOL EDITOR, set your App associations (Settings/Apps/Default Apps in Windows) so that NOTEPAD is opened if you click on xxxx.cbl or xxxx.cpy.

Edge: Special Note, October 2020.

The latest version of Edge is based on Chromium, and has ClickOnce disabled by default. If you click the Get Jazz link the software will be downloaded, even if it is the same version as you already have, and it won’t start automatically. You want to enable ClickOnce behaviour, which you do like this: -

1. Open Edge.

2. Enter edge://flags/#edge-click-once in the in the address. The web page will now look like this: -

3. Change Default to Enabled.

Edge will now behave correctly, with ClickOnce working as designed. I have been told that

If it's activated via the flags page then, as that page says, it is an experimental feature. All such features are off by default. When Edge was built by Microsoft from the ground up, they could include ClickOnce support however they wanted. Now that Edge is based on Chromium, ClickOnce support has to be added within that context. It's basically in beta form at the moment but, once it has been developed to a satisfactory level, they will include it as a standard feature and, most likely, enable it by default.

Four years later (2024) ClickOnce Support is still not the Edge default.

Create an Account on the MANASYS Jazz Web site

As the World of Jazz diagram shows, MANASYS Jazz has been developed expecting that you will be able to access the Jazz web site from your PC, enabling you to download the software directly from Home (jazzsoftware.co.nz), and also to read the Help pages when you are using it. If you are working in a secure environment such as a bank you may not have access to this site, and your system programmer will have to help you download it, perhaps by adding our web site to the list of allowed URL’s, perhaps by setting up a proxy, or perhaps by first downloading MANASYS to another PC from which you can copy it or use it indirectly. If you are the system programmer, please contact us to learn more.

To download and use MANASYS you must first create an account on our web site, which you do from the Download page. Click the Download page in the menu, or the Get Jazz link on the home page. It opens to look like this: -

When you enter your email and click [Find], then if it already exists in our database you’ll skip Create and go to Log On.

If not found, then the page responds with Email not found in database and exposes button [Create Account].

Click [Create Account] =>

Fields are: -

User ID. By default this is the part of your email up to @, but it must be unique and if necessary MANASYS will change it so that it is. For example, I had created an account with ID “robertb” and email Robert@JazzSoftware.co.nz. When developing our I tried to create another user, with email Robertb@somewhere.com. For the userid, MANASYS changed “robertb” to “robertb1”, but the email remained unchanged as Robertb@somewhere.com. You can give whatever User ID you like but, as with the example, if that User ID is already in use, it will be changed to make it unique.

Email: if you want to change this, click [Step 1 Restart] to go back to Step 1

Password and Repeat Password. These must be identical, at least 8 characters, and contain UPPER case letter(s), lower case letter(s), number(s), and special character(s)

Your Location. Please give enough to give a general idea of where you are in the world.

License Group.

· If your email matches with one that already has an account, for example xxxx@Jazzsoftware.co.nz, then you will have been put into this license group and you will inherit the license type and duration that applies to that license.

· If your email is xxxx@gmail.com, or another that MANASYS recognizes as a general email service, then an account will be created for you in the Individual group. You will initially have a month’s free trial. Contact us if you think that you may qualify for a free license (Agents and influencers), or if you want to convert your evaluation license to a full license.

· If your email has another form, like xxxx@YourCompany.com, then the button [Create New License Group] will appear. If you want this to be an individual evaluation license, just leave the license group as “Individual”. Otherwise edit your Userid if you want something different to the default value, then click [Create New License Group] to create a license group for YourCompany.

Company name. Will be filled in for you if the License Group has been found from your email. In the Individual group this is optional, and can have any text value.

Work Data is optional. Choose one of the options Employee/Self Employed/Contractor, and enter your job title.

Click [Add New User]. If the page doesn’t respond with error messages, an account will be created for you, you’ll be logged on, and you’ll be ready to Download Jazz.

[Create New License Group]

A new license group (=site) can be created by anybody who is not using a general email. You should create a new license group when YourCompany is evaluating MANASYS Jazz and, after positive evaluation, expects to license MANASYS Jazz for use. Don’t create a new license group for your own personal use, instead use the Individual license group. You cannot create a new license group using a general email like xxx@gmail.com.

A license group may have any number of users, but when initially created it will have 5 evaluation licenses, and a month’s free evaluation. All subsequent users downloading a copy of MANASYS with the same email root (@YourCompany.com) will use this license, with whatever rights and conditions it currently has. In the Individual group, each user may have different license terms.

When the button is clicked, then Create a MANASYS Account is disabled, and the Add New License Group panel appears: -

Fields are: -

· Site Name. Editable, defaults to your email root (without @)

· Site Admin. Initially your ID. Each site should have an Admin, who will be one of the site members. Once a 2^nd user joins this group, you will be able to edit them to make them the Admin.

· License Type. T (=trial), not editable except by Jazz Software Ltd

· License Expiry A month from now. Jazz Software may grant extensions

· Max Users Once MANASYS Jazz is licensed, this value will be set by Jazz Software, and not be editable. However the site admin may make users Inactive to reassign their license.

· Email Root. Taken from your email. Once the license group is created, all new MANASYS Jazz users with this email root will be put into it.

· Site Location. Editable, Required.

· Site Password and Repeat. Optional. Only users with your email root will be able to use this group anyway, but give this if you want to make access to this group tightly controlled.

· Comments. Editable, Optional.

Once the new site has been created, the Create User Group panel will disappear, and Add User panel will be reactivated. It will have been changed to use this as license group, and the company name will be filled in. Company Name and your user ID will not be able to be changed.

Complete Create a MANASYS Account by

· Required: Add your name

· Required: Add Password, and repeat it

· Optional: Choose one of the options Employee/Self Employed/Contractor, and Job Title

· Click [Check, Create New User if OK]

Download Jazz and Supporting Objects

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 (Edge) or another browser with ClickOnce Add-in enabled. Click the button [Run Jazz]. This will download a copy of Jazz into a temporary folder, check for pre-requisites (ASP.NET 4.6.1) and download this if necessary, and then start running Jazz. See Trouble-Shooting Installation if Jazz doesn’t start.

You will next see this: -

If you click the Jazz Software Ltd link, you’ll see our Code Signing Certificate, which guarantees that this software has come from us, and it hasn’t been modified: -

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 objects – programs, copy books, and so on – for your project. This may be on your own computer, or on a shared LAN drive. Project folders are always one level below a common path: for example your Common Path may be “My Documents”, and your project may be “JazzProject1”. In the example here, the common path is C:\tutorials, and my main project is TstSQL.

If you are using Jazz with Micro Focus™ and an IDE such as Visual Studio or Eclipse, set the IDE combo box. Otherwise leave it at the default setting of None. If you’re using Micro Focus™ with Visual Studio, create a VS project with type Mainframe Subsystem Application. We think that some users have successfully run MANASYS Jazz with Eclipse, it’s just another Windows program and shouldn’t be difficult to integrate with Eclipse. We are keen to work with a customer to validate this, and document any Eclipse issues with it.

If this is your very first set-up Jazz should now automatically start checking the folder locations. Common folder, which has a default value of “*”, will turn yellow and a dialog box will appear for you to locate or create the common folder. If this doesn’t happen automatically (as when you’re starting a new project, but you’ve used Jazz before), click [Check Paths].

The Jazz Common Path folder is the folder that contains one or several of your projects. Click [Locate] and you can browse to the folder you want, or you can type a value and click [Create].

With IDE = None and a personal project, this will probably be your My Documents folder. With a shared project this will be on a shared LAN drive.
With IDE = Visual Studio or Eclipse, this will be the folder where the IDE creates projects. For example, using Micro Focus Enterprise Developer with VS2017, this will be the folder where you create your COBOL projects, e.g. mine was C:\tutorials

Next, define the project folder. This will be a folder within the common path, and the Microsoft Browse for Folder dialog opens on it. For None, locate or create a suitable folder. If you’re using an IDE (Visual Studio, Eclipse) choose the project that you created earlier. Here my project is TstSQL (since recent development had focussed on providing DB2 support).

Jazz then checks that the project contains the required subfolders. You can leave the subfolder name blank, in which case Jazz will save the corresponding objects directly into the project folder, and subfolders may all have the same name. Different object types can be distinguished by their extension, so it’s simply a personal preference whether you have 0 to 6 subfolders, but we recommend that the full set of 6 be created. Any missing subfolder initiates a locate/create dialog as above.

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.

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 project. There will be error messages if you select a folder anywhere else. We want to define a folder hierarchy like this: -

Common Path

Project

Jazz Programs

Jazz Copy Code

Generated COBOL

JCL

COBOL Copy

BMS Maps

Job Output is a folder for MANASYS to store output from submitted jobs. This is only relevant if MANASYS is configured to use zOS, but will not be displayed if it is configured for Micro Focus. It is probably another folder within the Common Path/Project set, as in the example above, but it does not have to be. For a new installation you’ll have to put something in here even if you’re not going to use it because you’ll be changing to a Micro Focus configuration.

Here’s an example: this is my configuration for working with Micro Focus.

Note that the last 4 folders are the same as those used by my COBOL project in Micro Focus Enterprise Developer. (This explains the path C:\tutorials\TstSQL\...)

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. A Windows Explorer opens, showing all of these objects: -

For first-time installations you should select all of these objects: -

· Click the first item

· Scroll to the bottom and <shift>Click the last

The list of selected items appears in Filename: -

Click [Open] and they are copied into the appropriate MANASYS folders.

If your Jazz folders are shared with other users, or you have previously installed MANASYS and you’re refreshing (and updating) your MANASYS software, then these will already exist, and you’ll get messages like this whenever Jazz finds an 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.

If you’ve already installed MANASYS but now the software has been updated, the release notes may ask you to replace specific objects. Click [Configure] to open the configuration dialog, then click [Initial Objects] and select the specific objects that you want to replace.

Optional Step: Install Training Materials (Create Test Files)

If you are new to Jazz you may want to click [Add Training] to download various objects designed for an on-line tutorial. This functions like Initialise Project above, adding objects to your Jazz Programs and Copy Code folders. You may have created a special training project for this, avoiding unnecessary clutter in your normal projects.

Training objects include programs to set up the test data used in the video demonstrations and tutorials. You may like to download the training objects and create these data. Click [Add Training] to download the objects to create the objects to create the data. When you have completed set up for either z/OS or Micro Focus, you can create the test files. Click here to see a User Guide chapter on how to do this.

Initial Jazz test

When you’ve configured Jazz, MANASYS will display the Jazz Workbench. The first time that we see this we run a very basic Jazz test to prove that we’ve configured it correctly so far: -

1. Click the menu File/Open in the Jazz Workbench. Select member PFirst, a little nonsense program: -

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.

PROGRAM PFirst;

COPY PFirstR;

PROCESS PFirstR WHERE (PFirstR.Field1 = 'X' | PFirstR.Field1 = 'Y');

PRINT (PFirstR.*);

END PROCESS PFirstR;

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.

DON’T click [PROCESS] to compile and run the program! We have more configuration steps to complete first.

Generate COBOL: the COBOL Tab.

Click the COBOL tab. Mostly you will leave this at its default setting for now, but it’s worth looking at it so you know what’s there.

Important options that you need to check: -

· Cobol Dialect. Either

o Enterprise COBOL for z/OS to generate programs for either a z/OS mainframe, or the Micro Focus Mainframe Subsystem.

o Microsoft COBOL if you want to generate programs to run in a Windows or UNIX environment.

Other COBOL options that you may want to change from time to time: -

a. 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.

b. Sequence numbers (Left). If unchecked, columns 1 to 6 of each line will be left blank. If checked, then they will contain a sequence number which will increment by the amount given in the textbox. Recommended. If left unchecked, it will be difficult to relate any COBOL error messages to the line causing them: you’ll have to locate the Listing file.

c. Program Name from Col 72. If checked the program name will be put in columns 73 to 80 of each line. This may be useful to show the right-hand margin of the COBOL source code. Recommended: it delimits your COBOL source lines.

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.

e. STXIT Limit (Batch Only). In batch programs Jazz may include a call to an Assembler routine, JZSTXIT to trap abends such as Data Exception, producing diagnostics relating the error to a Jazz statement and displaying some important information such as the current record. If the limit is > 0 the program will then attempt to restart at the next record. The textbox may be set to a value from 0 to 9. If it is 0, or there have been too many abends then the default COBOL action, producing a dump, occurs.

This option is irrelevant if “Create Diagnostic Code” is unchecked, or Test Environment is IDE: in such cases Jazz does not include a call to JZSTXIT.

f. Allow SQL. Check this if your programs might use SQL. You will also need to set values in the SQL tab.

g. Max Jazz Error level. As Jazz processes your programs it will produce a 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.

By default, Max Jazz Error Level is set to Error, so Jazz won’t generate COBOL if Severe or Terminal errors have been recorded. Occasionally you might want to change this Severe to allow Jazz to generate some COBOL anyway, you won’t want to allow Terminal errors, and you’re unlikely to want to disallow COBOL with Warning or Information messages.

h. Decimal as Comma. If checked, decimal numbers are printed in the European style, swapping the decimal point and comma compared to British and American style. For example, instead of 1,234,567.89, this value will print as 1.234.567,89 .

i. Currency symbol. You can select a currency symbol of $, €, £, or ¥ from the drop down. If you want to distinguish a particular type, for example $US or $NZ, you can enter this into the textbox.

CICS Options

a. 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. However this option does not work with Micro Focus.

b. 3270 Screen Template. If you create your own standard 3270 screen template, then put its name here.

Year Rollover

Date fields are internally stored as year month day, e.g. the 28^th May 2020 is stored as INTEGER field with value 20200528. When a character value is assigned to a date, either by an assignment or an ACCEPT statement, any valid date will be accepted, using the target field’s PRINTPIC to determine the order of day, month, and year fields. If the input value has a 2 digit year the century is calculated by the year rollover value. Thus with the values shown: -

a value with year 40 or above will be interpreted as 1940 to 1999, but a year from 00 to 39 will be interpreted as 2000 to 2039.

With the COBOL tab set up, we’re now ready to generate COBOL. If we stop here then we could use Jazz to create COBOL programs but we would have to manually invoke our test system, submitting the COBOL and relevant JCL, when we want the programs to be compiled and run.

The next section deals with setting up our system to use a z/OS system, such as the IBM Dallas Test Centre, directly. If we’re using an IDE then skip this section, instead go to Set Up Jazz to work with Micro Focus and an IDE

Jazz Icon for Quick Restart

Optional step: you don’t have to do this, or you can do it later.

With MANASYS Jazz downloaded and running, you can continue with configuration and then start using it. You can stop, and use it later by going to the Jazz web site and clicking “Get Jazz” again, logging on, and then “downloading” it again. Jazz won’t actually be downloaded again unless the software has been uploaded, and your previous configuration and programs will remain available as you’d expect. But Jazz has been downloaded to your computer and added to your Start menu so it can be re-run without visiting the web site, and it is convenient to set up an icon that you can just click to restart it.

When MANASYS is running, there will be a MANASYS icon in the taskbar. Right-click this, and click Pin to taskbar.

Or, if MANASYS is installed but not running you can locate it in the list of applications like this. Click the Windows Start menu and scroll down the list of applications you’ll come to an entry for Jazz Software Ltd. Expand this, and you’ll see something like this: -

Right-click MANASYS Jazz: -

Click More/Pin to taskbar. The MANASYS Jazz icon is added to the taskbar: -

Now you only have to click the icon to restart Jazz. However, this will not check for a new version, so you should download from the web site if you know that there is a new version, or if your downloaded version has expired.

z/OS Set Up

We have completed basic set up, and Jazz is now able to check your program and (if it’s valid) generate COBOL. This section is only relevant when Test Environment (Jazz Workbench tab) is set to z/OS. However if you’ve set up Jazz with Micro Focus and an IDE (Visual Studio or Eclipse), you might still want to compile and test your programs with z/OS, perhaps first doing some testing with Test Environment = IDE and then some more testing with z/OS, so this section is not necessarily irrelevant to IDE users.

This section describes how to set up Jazz so that it will automatically upload the generated COBOL and JCL, run the jobs, and download the output. We start by setting values in the z/OS tab. We can edit our configuration at any time by clicking [Configure], and then the z/OS tab.

Set up: the z/OS tab

Here’s where you describe your z/OS set up, so that Jazz can submit jobs for you: -

· Enter your mainframe userid. IBMUSER was my personal ID at a z/OS 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 1. These Mainframe Credentials are HELD ON YOUR LOCAL PC, they are NEVER transmitted back to Jazz Software or elsewhere outside your secure environment.

NOTE 2. Provided that port 21 is correctly set up (or whatever port you give in the Job Submission section) Jazz will detect that FTPS (File Transfer Protocol (Secure) is available and use this for all communication with the mainframe.

· Edit the JOB Statement. This will become the //name JOB … statement at the start of your job. The default job statement is initially
//@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. All jobs will have the same name.

· 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. 123.123.123.123 is a dummy address, but without a real address that will recognize the IBM Userid and password Jazz can’t communicate 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. Close the Configure form to return to the Jazz workbench.

Processing

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.4. Click [Generate] and Jazz will create a COBOL program, PFirst.CBL. [Find COBOL] will change to [Review COBOL], and in “Restart from Step” JCL is checked: -

1.5. 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.

Test a COBOL Compile

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 (but not yet 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,

submit the job,

and then

check for output.

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.

Edit JZL 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: -

Name	Function
Assembler.JZL	Used when source code is Assembler, not COBOL. Not used now.
JSVSAM.JZL	Run IDCAMS. Used when you’ve defined a VSAM file.
JZAssembleMap.jzl	Compile (assemble) a BMS map. This is automatically done from the Jazz screen editor when you click [Process]
JZCoMF.JZL	GO step when configured for Micro Focus
JZCompilebatch.jzl	JCL for compiling and linking a batch program
JZCompilebatchSQL.jzl	JCL for compiling and linking a batch program that uses SQL (DB2, Oracle, etc).
JZCompileCICS.jzl	JZL for compiling and linking a CICS program
JZCompileCICSSQL.jzl	JZL for compiling and linking a CICS program that uses SQL (DB2, Oracle, etc).
JZGENER.jzl	An IEBGENER step. Not used now
JZGO.jzl	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,CATLG) and a SPACE parameter), or is updating it and requires DISP=OLD to give it exclusive access. For a new member of an existing library (PDS), then DISP=SHR is appropriate
JZGoSQL.JZL	GO step for a job including DB2
JZJobProc.jzl	A JCLLIB statement that is used with Web Service jobs
JZJSProv.JZL	JSON equivalent of JSWSProv
JZWSProv.jzl	Used for WSDL (SOAP) Web Service Provider programs
JZWSReq.jzl	Used for Web Service Requester programs

Compile Support Subprograms

Download and compile JZxxxx routines that may be required by your program. Click here (or the heading) for details.

Validate remaining templates

After the steps above have been completed then

1. Using a small mainframe sequential test file,

a. Import its COBOL record layout into Jazz, and edit it to add missing information such as its DSNAME.

b. Write 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.

d. You 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 template JZJobProc

b. If you are going to be creating SOAP (WSDL) services examine, and edit if necessary, templates JZWSProv, and JZWSReq.

c. If you are going to be creating REST (JSON) services, examine, and edit if necessary, templates JZJSProv, and create template JZWSReq if you want to write INVOKE xxx statements invoking a REST Service. See REST JZL Templates for more detail.

d. Create a simple web service and test it, as described in the web pages JazzUGSOA1.htm and JazzUGSOA2_files.

e. You will need help from your system programmer to get your first web service program running.

Set Up Jazz to work with Micro Focus and an IDE

See JazzUGMFStep1.htm

Appendices

General information.

Jazz Extensions

Various folders store Jazz Programs, Copy Books, Screens, JCL, and other types of objects. You don’t need to use different folders 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. Default setup uses 6 different folders as we’ve found it convenient to have some separation.

Jazz currently recognizes the following extensions/object types. If you don’t have any software that will deal with these types, you should configure Notepad as the default app for this extension. All Jazz objects are text files, so are displayable by Notepad. Software, such as Visual Studio and Micro Focus Enterprise Developer will provide better displays than Notepad when appropriate.

.bms (can be changed in Configure). Basic Mapping Support. Assembler macro statements generated by MANASYS from 3270 screen editing, from which the physical map is compiled.

.CBL COBOL program (generated by Jazz, or from an external source (e.g., downloaded from zOS when converting COBOL to Jazz))

.cpy (can be changed in Configure). COBOL Copy books generated by MANASYS Jazz for Web Services and SQL definitions.

.cs C# (or C Sharp). Used to generate client interfaces

.JCL z/OS JCL. May be produced as a result of [Submit] being clicked, and built from various .JZL templates.

.json JSON (Java Script Object Notation). Used to describe message formats for REST web services. See .wsdl

.jzc Jazz Copy Book. One or more DEFINE statements, and/or COPY statements. One 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 z/OS JCL except that it may contain Jazz parameters, and JZL statements can be of any length. Both JZL 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.

.jzx XML.

.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.

.wsdl Web Services Description Language. Used to describe message formats for SOAP web services. See .json

.xls Excel Spreadsheets

.xlsx Excel Spreadsheets

Various Issues

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, and you can run it by clicking the icon you created with Jazz Icon for Quick Restart, or by locating MANASYS Jazz in your applications and clicking it. This will enable you to run it for a while without being connected to the JazzSoftware.co.nz web site, but running it in this way will not 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. You will need to access the web site at least monthly. However most Help requires the web site to be available.

MANASYS Jazz is sandboxed by Microsoft’s ClickOnce technology, and so can’t access your Windows system except through the folders that you define with your Jazz configuration.

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 Compile Support Subprograms. Our expectation is that you configure z/OS 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.

Let us know of any problems you find, and suggestions for improvement.

Trouble-Shooting Installation

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 to download Jazz using Internet Explorer or Edge. For Edge, see Edge: Special Note, October 2020.

The simplest fix for this problem: install Jazz using a Microsoft browser (Internet Explorer or Edge). You don’t have to make this your default browser if you prefer to keep using Chrome or another. Once installed, you’ll usually start Jazz by clicking the icon that you’ve put on your desktop or taskbar, using Download only monthly or when you need to download the latest version.

You can install with Firefox, Chrome, etc by installing an AddIn. Google xxxx ClickOnce (e.g. “Chrome ClickOnce”) to find out how.

Here are some issues that we’ve encountered.

1. Timeout waiting for data from client

A user reported the following error: “When I tried downloading I was getting below message for all the three attempts, third time I tried refreshing the page and the download started”.

The download started and completed normally when the page was refreshed.

2. Various Javascript messages, but Jazz doesn’t start.

An attempt was made to install Jazz using the standard Chrome browser, not enabled for ClickOnce, but it just produced some message about Javascript and nothing else actually happened and Jazz didn’t start.

We haven’t seen this message recently, we think that this situation will now behave as described in #3.

The problem is caused by trying to download and install Jazz with a browser that is not enabled for Microsoft ClickOnce. Refer to PREREQUISITES, and if you’re using Edge, see Edge: Special Note, October 2020.

3. License Token not found

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.

4. Application cannot be started

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

SOURCES

Deployment url : Where it was installed/Jazz.application

IDENTITIES

Deployment Identity : Jazz.application, Version=1.13.7.111, Culture=neutral, PublicKeyToken=4a9f8c94079d1f42, processorArchitecture=x86

APPLICATION SUMMARY

* Installable application.

* Trust url parameter is set.

ERROR SUMMARY

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

We think that, like the previous items, the problem is caused by trying to download and install Jazz with a browser that is not enabled for Microsoft ClickOnce. Refer to PREREQUISITES, and if you’re using Edge, see Edge: Special Note, October 2020.

Glossary

.NET	Microsoft’s development framework – a series of support classes used by programs generated with Visual Studio.
BMS	Basic Mapping Support. The technology (Assembler Macros) used to describe 3270-type screens, i.e. the “Green screens” of Classical CICS
CICS	Customer Information Control System. IBM Operating System software to manage many simultaneous on-line users.
FTP	File Transfer Protocol. The protocol used when one computer sends or receives files from another.
FTPS	File Transfer Protocol Secure. A variation of FTP in which the transmitted data is encrypted, so that it cannot be interfered with by intermediate computers in the path from sending computer to receiving computer. Jazz will automatically use FTPS if its “FTP Handshake” detects that the other end is configured for explicit FTPS.
HTML	Hypertext Markup Language. Defines a syntax like <tag>text</tag> that allows you to specify markup, controlling the appearance of text. For example <B>Word</B> specifies that Word should be displayed as Bold.
HTTP	HyperText Transfer Protocol. The protocol used to transmit HTML, for example to send a web page for display.
IDE	Integrated Development Environment. For example Visual Studio (Microsoft), Eclipse (Open Source)
JCL	Job Control Language. A “Language” to control batch job streams, defining jobs, job steps, and files.
JSON	Javascript Object Notation. A lightweight data exchange format, used by REST web services.
JZL	Jazz-format JCL. Basically standard JCL except that is not bounded by column 72, and may include @name parameters and use ! as a separator character.
LAN	Local Area Network. Computers (usually Laptops and PC’s) linked together in an office, typically with a shared server where common files can be saved.
LPAR	Logical PARtition. A region of a shared z/OS mainframe, keeping the users, files, and other resources separate from other LPARs.
MF	Micro Focus
MFED	Micro Focus Enterprise Developer
REST	Representational State Transfer. A protocol for exchanging web service messages using JSON. MANASYS supports both REST and SOAP.
SOAP	Simple Object Access Protocol. A protocol for exchanging web service messages, based on WSDL. MANASYS supports both REST and SOAP, although further SOAP development is unlikely as REST has superseded SOAP in the market.
TSO	Time Share Option. A facility of z/OS used for program development and system management.
VS	Visual Studio
XML	eXtensible Markup Language. Whereas basic HTML uses standard tags like <B> and <P> (paragraph), XML allows you to define your own tags, for example <AccountNbr>123456</AccountNbr>. This allows messages to be transmitted with HTTP that can be understood by both receiving and sending programs sharing an XML schema
WSDL	Web Service Definition Language. A standard form of XML defined by the SOAP protocol, and used by SOAP web services.
z/OS	Z-series Operating System. The operating system for IBM Enterprise Computers (“Z-Series”)