Configuration

Configuration. 1

Workbench Options. 2

Colours. 2

Workbench Options. 2

IDE. 3

User File Paths. 3

[Initialize Project] 4

[Add Training] 4

Lang. 4

z/OS. 6

JZL Templates. 7

Job Submission. 8

Web Services. 9

Diagnostics. 9

 

When you click [Configure] on the workbench, or start Jazz for the first time, this form opens: -

 

You make changes on any of the tabs, then when you click [Close] these changes are saved and will be used immediately and for all your following Jazz sessions until changed.   As described under “Setup”, you use this form when you use Jazz for the first time, as Jazz needs to be pointed to the right folders.   You will set values on the Workbench and Lang (=language) tab, but you will only set the z/OS tab if you are submitting jobs to a z/OS mainframe.   If you are using Micro Focus with an IDE (Visual Studio or Eclipse) then you won’t need anything on the z/OS tab.

Workbench Options

This tab relates to the Jazz workbench: -

Colours

(or for our American friends, Colors).  You probably won’t feel the need to change the default colours, but double-click or right-click any of these if you do and a colour palette appears:-

 

Select the colour that you want for this type of program text.

Workbench Options

Set your UserID.  This will appear in the automatic comments generated at the top of Jazz programs and copy books: -

*# Last Updated by JazzUser at 15/05/2018 10:24:48 a.m.

PROGRAM Batch1 BATCH;

If you are using z/OS, this should be your z/OS user id, as it will be the same value shown/set in the z/OS tab.

 

You can set the number of spaces per indent, the maximum line length, whether you want COPY code to be displayed by default, and the number of files that you want to be remembered in the “Most Recently Used” list of the File menu.  Thus with File limit set to 4 (the default), your File menu will look like this: =

 

 

Open Last Session automatically.  If checked, the previous program is opened automatically, e.g. you don’t have to use File/Open to reopen

*# Last Updated by JazzUser at 15/05/2018 10:24:48 a.m.

PROGRAM Batch1 BATCH;

 

Min Jazz Error Messages.   Set to “Warning” and you won’t see “Information” message.  Set to “Error” and you won’t see “Warning” either.   Sometimes a program or copy book can produce an annoying number of low-level messages that you don’t want to see: set this if you want to suppress them.

IDE

(Integrated Development Environment).  Options are None, Visual Studio, or Eclipse.

Select Visual Studio or Eclipse if you want to use Jazz with one of these IDE’s.   Leave the default as None if you’re using Jazz without an IDE.

  

Currently this has been tested with Visual Studio (2017), but not with Eclipse.  Eclipse will be tested and implemented in cooperation with an Eclipse user after Visual Studio implementation is completed.  In the meantime Eclipse will behave like None.

User File Paths

This describes the folders that are used in your Windows environment for Jazz objects.  Jazz has been developed assuming that folders are arranged like this: -

            Common Folder

                        Project1

                                    Jazz Programs

                                    Jazz Copy Code

                                    etc

                        Project2

                                    etc

 

If you are working on your own then these can be on your own PC, but if you are working with others then all members of your project team must have the same values, and the common path should refer to a folder on a shared server.

 

[Set Defaults] sets Common Path and Project to *, and checks that they exist: of course they don’t so the textbox is highlighted and a Windows Explorer search is initiated.

Common Path

“*”, the default value, initiates a dialog to define the common path when [Check Folders] or [Initialise project] is clicked.  Create or navigate to the folder where you want to save the objects for your projects.

 

If an IDE is used then the common path should be the folder in which it saves its project objects.  For example, with earlier Jazz development my projects were stored in My Documents, so Common Path had value

            C:\Users\Advanced Computers\Documents

and the project folder was named

            Jazz

With Version 15 Jazz we implemented Micro Focus support, and so my common folder became

            C:\tutorials

and the project folder was ACCT, or whatever actual tutorial I was working with.

 

Common Path must not be left blank, or as “*”.

Project

Project may not be a blank, but should be the name of a subfolder within the common path.  “*” will cause [Initialise Project] to initiate a Windows Explorer search within the Common Path.  If you’re using Micro Focus Enterprise Developer with Jazz, then you start by creating a COBOL project as described in the Micro Focus tutorials.  In the example above the Window snap illustrates Jazz being set up to work with within the Micro Focus CICS tutorial, ACCT.

 

Values for Project depend on the IDE setting: -

None

Any valid folder name may be given.  If it doesn’t already exist, the dialog offers options to create it, or to choose another name. 

Visual Studio

The folder name must already exist within the common path.  To use Jazz with Visual Studio you must first create a VS project with one of the COBOL project types provided by Micro Focus: probably Mainframe Subsystem Application.  Suppose that we’ve created a COBOL project called ACCT.  VS will have created a folder structure like this: -

ACCT\

Bin\

Obj\

Properties\

ACCT.cblproj

   ACCT.sln

Eclipse

Temporary rules – behaves as None.  To be reviewed after implementation of Visual Studio

Subfolders

Jazz Programs, Jazz Copy Code, Generated COBOL, and JCL are all sub-folders within the project folder.  They may be a valid folder name or left blank. With this example Jazz will create three subfolders, Jazz_Programs, Jazz_CopyDefs, and Jazz_LocalJCL, within the project folder.   Generated COBOL will be created directly into the Project folder.

 

Jazz uses different extensions like .jzz, .jzc, etc to distinguish different object types, so you can have a single subfolder for all types of object, or you can define separate subfolders to make your Windows set-up more like the way mainframe libraries are organized, or some combination.  There are more subfolders defined on the Lang tab.

Locate or Create Folders

A folder search is initiated when you set up Jazz for the first time, click [Check Folders] or [Initialise Project], or type “*” in one of the folder textboxes.  This displays the Set Configuration Value dialog, with the name of the object that you are setting.  For example, here we’re setting Jazz Project, which has been coloured yellow on the underlying Configure dialog: -

 

 

Set Configuration Value displays

·         The original text, “*”, in the original textbox is redisplayed as a label

·         Within Path shows the path hierarchy so far.   Here we’re defining Project, which will be a folder within the Common Path, so Within Path displays the value of the common path.  If we were defining one of the next level, such as Jazz Programs, then Within Path would show the Common Path  \  Project.  You may need to drag the right-hand side of the Set Configuration Value dialog box to the right to see the whole path.

·         The original text is displayed in a textbox.  Here you can edit it, for example typing “MyNewProject”.   As you type here, the related text in the Configure form will also change.   You might do this if you were going to create a new folder, and needed to change the text value.

Then follow action buttons

·         [Locate] opens Windows’ Browse For Folder dialog, with the path hierarchy so far highlighted, and with an option to create new folders: -

 

Expand the highlighted folder and select the folder that you want.  You can create a new folder by clicking [Make New Folder]: this creates a folder named “New Folder” which you can immediately re-name.  Whether a selection or new folder, it should be a folder directly within the path so far, not several levels down.  

·         [Create] will create a new folder within the path so far, using the name in the textbox.  It must be valid, so you’ll change “*”. 

·         [Undo] is for “Oops” moments: if you created a path incorrectly, you can click undo to delete it (if possible), clear the textbox, and start again.

·         [Exit]  Following a successful [Locate] or [Create] the Set Configuration Values dialog closes.  Click [Exit] if you want to leave this dialog without making any change.

[Initialize Project]

When values have been given for the user file paths click [Initialize Project] and Jazz will copy some initial objects into the libraries.  A selection dialog will appear: -

 

First time you should probably select all items – click on the top item, then click the last with <shift> pressed.   With an updated version of Jazz you may be given a list of objects to select.  If in doubt, select all.

[Add Training]

Click this for a training project: various Jazz training objects will be downloaded.   As with [Initialise Project] you have the option of selecting items, and the particular tutorial will have told you which objects you need.  However it is harmless to select all.

Lang

Here you give the options that will be used for the Intermediate Language (COBOL) and screen generation.

 

Intermediate Language.  You can’t change this: it’s put here just to emphasis our future intent.

 

COBOL Dialect.  Choices are  Enterprise COBOL for z/OS, and MicroFocus COBOL.   Choose Enterprise COBOL for z/OS if the program is to be developed for z/OS or the Micro Focus mainframe subsystem.   MicroFocus COBOL targets Unix and Windows, and needs more development.

 

Include Jazz Program as Comments.  If checked then the Jazz source program is included as comments at the top of the program.  Individual Jazz statements are also printed within the body of the COBOL program just ahead of the corresponding COBOL statements, whether this is checked or not.

 

Show Dictionary Entries in Jazz Program.  If checked, then Jazz will print into the program the entries that will be added to the system data dictionary.  The data dictionary feature isn’t yet developed: when it is the entries shown will be picked up and put into a dictionary database.

 

Sequence Numbers (left).  If unchecked, columns 1 to 6 will be left blank.  If checked, you can set the line increment.

 

Program Name from Col 72.  If checked then cols 73-80 will contain the program name. 

 

Generate Diagnostic Code.   If checked, Jazz creates extra COBOL code that may be useful in the event of a run-time error (abend).   This code introduces a slight overhead, but our recommendation is to leave this checked if you’re directly using z/OS: the overhead will be undetectable (only a few extra MOVE statements) in practice.  With Micro Focus Enterprise Developer and Visual Studio, you may feel that it’s unnecessary clutter.

 

STXIT Limit (Batch only).  In batch programs some abends are trapped (for example, Data Exception), allowing your Jazz program to present diagnostic messages in terms of your Jazz program, not just leave it to you to interpret a COBOL dump.   The program may be able to recover from this and try again: you can set the number of retry attempts up to 9.  STXIT is not used if the test environment = IDE.

 

Max Jazz Error Level.  If Jazz checking finds errors with severity greater than the level set here, then COBOL won’t be generated.  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: The program is probably correct

·         I           Information:  This isn’t a problem, just something that Jazz thought you should know.

Sometimes you might want to change this from “E” to “S” to allow Jazz to generate some COBOL anyway.

 

CICS Mapping Level.  Setting this has no effect unless you are generating web services, where it can affect the size of messages.  Suppose you have a message structure defined with a variable number of occurrences of a record.  With CICS Mapping Level absent or less than 4 then the message will always contain the maximum number of occurrences of the record, with excess records being sent as initialised values (blanks and zeros).  With CICS Mapping Level 4 or greater a COBOL OCCURS DEPENDING ON structure is created, and the actual number required (up to the maximum) is sent.

 

3270 Template.  When you create a new screen Jazz starts with a template: here you give the name that will be used as default by the screen editor.  If you have local standards about 3270 layout then you may prefer to create your own template with a different name.

 

Test Environment.  Choices z/OS or IDE.  

 

If z/OS, then [Process] will create COBOL and JCL, submit the job to a z/OS system, and then read the output into the Job Output folder.  The COBOL dialect must be Enterprise COBOL for z/OS.   You will need to set values on the z/OS tab.

 

If IDE then [Process] will create COBOL, then the program is tested using the IDE. 

z/OS

Here you give the details needed to allow jobs to be created and submitted by FTP to the z/OS system.  It is irrelevant and can be ignored if you are using Jazz with Micro Focus and testing your generated COBOL programs with the IDE (Visual Basic or Eclipse), not directly submitting the job to a z/OS system.

 

 

UserID, Password.        These are the credentials with which you log into TSO on the z/OS system.   Unless your z/OS system has been set up to allow anonymous FTP (which is unlikely) Jazz needs to log on to the FTP/FTPS connection in order to upload the generated COBOL and submit a job to compile [and run] it, so it needs this information. When you enter the password you must repeat it in the textbox “Repeat PWord”.   Your z/OS system may periodically (monthly?) require you to change your password: when you do this (with TSO) you will also need to enter the new password here. 

 

Job Stmt.  This is a pro-forma JOB statement.  Note that, like all “JZL”, it is standard z/OS JCL except that the statements may be longer than 72 characters, and may include Jazz parameters: names starting with “@” that are substituted before the JCL is submitted.  Here there is a parameter @Jobname, which is formed according to the rule described in the section “JobName Rule”.

 

JobName Rule.  Choose a rule to create a value for @Jobname.

 

ISPF.  Here you describe the library name heirachy, as you would in ISPF.  The main value of this is to give values for symbolic parameters @Project and @Group, which are used in the following section, Libraries

 

JZL templates.   See below.  JZL is “Jazz-format JZL” that Jazz uses to submit a job

 

Job Submission.  IP gives the address that you’d use in a TN3270 session to communicate with your z/OS system.  Port is the port number for FTP communication.  Secure FTP (TLS) will be used if it is detected.  Your z/OS system should be configured to support this, otherwise your z/OS credentials (userid and password), as well as the following details of your job submission and results, are exchanged with basic FTP and are vulnerable to interception.

 

Libraries.  Here you define the z/OS libraries that you’ll use.  Note that their DSNAME values can be defined with Jazz parameters.  After substitution these values may be used when jobs are generated and submitted.

 

Web Services.  This gives the details that you need to develop and test web service provider and requester programs with z/OS.  See below for more details.

 

Job Output.  Like Common Path on the Workbench Options tab, you must name a folder where the job output will be placed when Jazz downloads it from the z/OS mainframe.  Enter “*” to initiate a dialog to search for and set the Job Output path.  As with Common Path. you give a complete path: you may name a folder within the common path or an independent folder.  Downloaded jobs don’t need to be shared, so you may decide to use a folder within your My Documents folders. A value is required if you’re using z/OS testing.

JZL Templates

 

JZL is “Jazz-format JZL” that Jazz uses to submit a job.  For example, if you click [Process] when you are editing a batch program, then after Jazz has checked the program and found that there are no serious errors it will generate and submit a job by: -

1.                   Uploading the generated COBOL to the COBOL source library (defined as “Source”)

2.                   Creating a JOB statement based on the Job Statement on this form

3.                   Creating JCL from the batch compile template JZCompileBatch.  This uses the procedure IGYWCL and so includes a Compile and Link step

4.                   Adding a step to run the program based on the template JZGo, with additional DD statements derived from the files used by the program that have DSNAME options.

 

You can edit any of these templates by clicking the label or double clicking the textbox: this will open the named template with Notepad.  You can create a new template by giving it a new name with Save AS

 

JZL is normal z/OS JCL except that: -

1.                   Lines do not have to fit within “columns 1 to 72”, but can be any length.  

2.                   Lines, including parameter lines, can include Jazz Parameters, which are words starting with “@” like “@Program”. 

 

Jazz converts JZL to JCL by: -

1.                   Substituting Jazz @ parameters.  The JZL and hence the JCL may also contain JCL parameters like &SYSUID – these will be handled later by z/OS.

2.                   Breaking over-long JCL statements at appropriate boundaries, and creating continuation lines.  (This does not apply to parameter lines).

 

To be substituted a parameter must be bounded by punctuation or the end of the line.  If you wish to have a parameter value directly followed by other text use the special punctuation symbol “!” (shift-1 on most keyboards).  ! will be removed from the output line when it is used in this way: thus

@Program = “WST1”

BINDING=@Program!HTTPSOAPBINDING 

results in

            BINDING=WST1HTTPSOAPBINDING

Lines that use this special punctuation should not use “!” in any other way as ALL “!” will be removed from that line.  However it is a normal data character in other situations, albeit invalid in JCL.

 

Here is the list of parameters recognized by JZL => JCL conversion.  Mostly the source of these values is obvious, and is usually a field in the z/OS tab of the configuration form.  Parameter values may be entered in lower or upper case or a mixture, but Jazz may change this: -

·         In situations where the value MUST be upper case to avoid errors, like the z/OS library names (@Source, @Copy, @JCL, @LoadBatch, and @LoadCICS) the values will be changed to upper case as they are entered.  In the table below, the parameters with “U” in the Case column are forced to upper case.  Otherwise parameter values retain the case with which they were entered.

·         In some cases a parameter value is wanted in upper case in the z/OS file system, but in lower case in the z/OS Unix file system.  An example is Project, which is set by default to @Userid and therefore is upper case.  However when this is a component of the HFS name it may need to be lower case.  In such cases you can use @lc… or @uc… parameter names, e.g. if @Project has value “IBMUser” then @lcProject will have value “ibmuser” and @ucProject would have value “IBMUSER”.  If a parameter value contains further parameters then the coercion to upper or lower case occurs on the initial substitution.  For example, if a Jazz @parameter has value  “/u/@project”, then @ucParameter will initially become “/U/@PROJECT”.  Now @Project will be substituted, but since the @ name is neither @ucProject nor @lcProject the actual value of @Project will be used, so if the value of @Project were “Myprojt” the final value of @ucParameter would be  “/U/Myprojt”.

 

Parameter name

Case

Comment

@JobName

U

Formed by the rules in JobName Rule

@Library

U

May be set to @Source, @Copy, @Loadbatch, or @LoadCICS

@Userid

U

From textbox on z/OS tab

@Suffix

 

Set automatically.  See JobName Rule

@Program

U

Taken from the PROGRAM statement

@Screen

U

Screen name: set when the Jazz Screen Editor submits a physical map for assembly

@JobStmt

 

From textbox on z/OS tab

@Project

 

From textbox on z/OS tab, usually defaulted to @Userid

@lcProject

L

Value of @Project in lower case

@ucProject

U

Value of @Project in lower case

@Group

 

From textbox on z/OS tab

@lcGroup

L

Value of @Group in lower case

@ucGroup

U

Value of @Group in upper case

@TypeValue

 

From textbox on z/OS tab.  Currently not used

@Source

U

From textbox on z/OS tab

@Copy

U

From textbox on z/OS tab

@JCL

U

From textbox on z/OS tab

@LoadBatch

U

From textbox on z/OS tab

@LoadCICS

U

From textbox on z/OS tab

@HFS

 

From textbox on z/OS tab

@Reqname

L

Web Service Provider: Request member name

@Respname

L

Web service provider: Response member name

@Pgmint

U

Web Services: parameter for DFHLS2WS.  Value CHANNEL or COMMAREA

@Contid

 

Web Service provider: container name

@Mode

 

Set by program to “Provider” or “Requester”

Web Services

 

Give the name of the HFS (Hierarchical File System) that you’ll be using for Web Services.  As with the JZL Templates section, Provider and Requester name JZL templates that you can edit.  Just click on the word “Provider” or “Requester” to open a Notepad window.

 

[Check HFS].  Checks (and creates if necessary, subject to a dialog), the pair of files defined as HFS, i.e. /u/manajazz/Provider and /u/manajazz/Requester, with subfolders /shelf and /wspickup.  Note that these names are case-sensitive. 

Diagnostics

This tab is designed for the Jazz software development team, not for Jazz users. 

 

There is only one field on this tab that might be relevant to Jazz users:  Loop Trap Limit.   At various points in Jazz the logic should be going through a list – of statements, of fields, whatever – and if we have made a programming error the code may go into an endless loop.  To prevent this a limit has been coded: if the limit is reached then there is a message “Loop Trap Exceeded” and the program stops. Unless you are writing much larger programs than we do you shouldn’t see this message: if you do see it but you think that it’s a valid situation you may like to set a larger limit.

 

Other options on this tab cause various diagnostics to be produced as Jazz runs.  These will be meaningless without access to Jazz .NET source code, and mostly are not useful with the compiled version of Jazz available to users.