Jazz
Set Up Support Routines
Notes
(what the routines are used for)
Support Routines
When you write a program in Jazz and click [Process] Jazz turns your
Jazz program into COBOL. [Process] should
be set up so that when you click it the COBOL is generated and
z/OS: a job is
submitted to compile and link the program, and (if batch) run it.
Micro Focus: The MFED
COBOL project is opened where you compile the program, and (if batch) submit
the corresponding JCL to run it.
(For CICS and Web Services there is a little
extra set up before the program can be tested).
In some situations this COBOL will include
statements to invoke pre-compiled routines.
For example, if you write
EMPLOYEE.HIREDATE =
EMPLOYEE.BIRTHDATE +
0/0/30;
#578 I DateDiff = 30 years, 0 months,
and 0 Days
then the following COBOL results in which the routine JZDTAR is invoked for the DATE arithmetic calculation: -
003950*
EMPLOYEE.HIREDATE = EMPLOYEE.BIRTHDATE + 0/0/30;
003960 MOVE
EMP-BIRTHDATE OF EMPLOYEE TO JZ-Date2 OF JZ.
003970 MOVE
'+' TO JZ-Op OF JZ.
003980 MOVE
30 TO DFYears OF JZ.
003990 MOVE
0 TO DFMonths OF JZ.
004000 MOVE
0 TO DFDays OF JZ.
004010 CALL
'JZDTAR' USING EMP-HIREDATE OF EMPLOYEE JZ-Date2 OF JZ
004020 JZ-DateDiff
OF JZ JZ-Op OF JZ.
If you haven’t already compiled JZDTAR into the appropriate library then
it won’t be found by the link-editor.
The COBOL will compile, but errors still occur
z/OS: At run time the program will abend when it
attempts CALL ‘JZDTAR’
MFED:Error messages are produced when you click Build
Thus
before you can run your Jazz programs you have to make these support
subprograms available. This is part of
the configuration process, and needs to be done with each new project.
From the
Configuration form, button [Initialise project] displays a list of all the
support routines: they all have names starting with JZ, and type cbl (COBOL) except for JZSTXIT which has type JCL and is
supplied as a job containing an Assembler routine. You can be selective about which routines
you download and compile, but if you do you will need to be aware of when Jazz
uses them to avoid unexpected link errors.
You’ll probably select all the initial objects, and compile all the
routines. This only needs to be done
once per project.
These
routines are provided when Jazz is installed and configured. If you click [Initialise Project] on the
first configuration screen they are included in the list of initial objects:
you can choose to select the ones you need, but as you will often be unaware of
whether a Jazz program requires them you’ll probably select all the initial
objects and compile all the routines.
List of Support Routines
|
JZABNDW |
Abend handline, CICS Web Services |
No |
Yes |
14. |
|
JZBR14 |
2. |
|||
|
3. |
||||
|
4. |
||||
|
JZDTAR |
Date Arithmetic |
Yes |
Yes |
5. |
|
JZDTVL |
DATE Validation |
Yes |
Yes |
15. |
|
JZDTVL2 |
Check Day>28 |
Yes |
Yes |
16. |
|
JZDTVS |
Date Validation |
Yes |
Yes |
6. |
|
JZHASH |
Calculate Hash-Digest |
? |
Yes |
12. |
|
JZLIKE |
Used when a LIKE condition is written in normal Jazz, e.g. an IF condition, not in a SQL WHERE clause |
Yes |
Yes |
10. |
|
JZMSAD |
Add error text to message field |
No |
Yes |
7. |
|
JZNOFM |
Return N of M for CICS scrolling |
No |
Yes |
8. |
|
JZNXTKY |
Next Key for a Character key |
Yes |
Yes |
11 |
|
JZSTXIT |
Used to trap abends and display JZ-Program-Info |
Yes |
No |
9. |
|
JZTRIM |
Used to Trim CHAR and VARCHAR data |
Yes |
Yes |
13 |
|
17 |
||||
|
JZTM02 |
Format time for DB2 |
Yes |
Yes |
18 |
|
JZTMAR |
TIME arithmetic |
Yes |
Yes |
19 |
|
JZTMVS |
TIME Validation |
Yes |
Yes |
20 |
Compiling
the routines
z/OS
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 routines (JZDT02, JZDTVS) should be
compiled and linked into both. Such
routines must be compiled without the COBOL parameter PARM.COBOL=CICS
Micro Focus (Enterprise
Developer)
The CBL
routines must be added to the COBOL project.
If the project is enabled for CICS (or CICS Web Services) then for all
programs except the CICS-Only routines (JZBR14, JZABNDC, and JZNOFM) set
property CICS Directives=None
Open
the COBOL project,
Right-click
the routine, e.g. JZDTAR.CBL, click Properties,
Click
the COBOL tab,
General section, CICS
Directives: Select None from the drop-down.
If the
batch or dual-use routines are compiled with CICS directives then they are
invoked with DFHEIBLK and DFHCOMMAREA as their first two arguments. Since they are not expecting this, this will
cause errors when they attempt to refer to the parameters passed to them.
Notes (what the routines are used for)
1. JZBR14 does nothing, but in CICS
programs Jazz generates code to invoke it within the program’s Abend exit: -
JZ-Abend-Exit.
* BR14 does nothing, but is
useful for CEDF/CEDX debugging
EXEC CICS
LINK PROGRAM('JZBR14 ') COMMAREA(JZ-Program-Info)
RESP(JZ-RESPONSE)
END-EXEC.
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.
JZDTAR
is used in Date Arithmetic statements such as Date1 = Date2 + DateDiff. Date1
and Date2 are fields with format DATE, DateDiff is a group containing three SMALLINT fields for years, months, and days.
5.
JZDTVS
is used to validate a CHAR value assigned to a DATE field or used as DateDiff
(see above) in DATE arithmetic. The CHAR (or VARCHAR) value is parsed based on the way that you’ve
written the CHAR value, and the DPIC of the target DATE. Rules are designed to make data entry as easy
and flexible as possible, and are described more
fully below.
6.
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.
7.
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.
8.
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.
9.
JZSTXIT
is not used with MFED. With z/OS, with
the appropriate configuration option batch programs will include
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.
For more detailed
information about JZSTXIT, see below.
10. In SQL you can use LIKE to compare a
character string: for example
PROCESS
Employee WHERE
EMPLOYEE.LASTNAME LIKE
'SM%';
JZLIKE is used when this same kind
of comparison is used in normal Jazz condition, such as from an IF
statement.
11. When you use FREEKEY in a GET statement, for example
GET SQLRow FREEKEY CREATE;
FREEKEY instructs Jazz to find the last key in the file (or table) and add one
to it. If the file has a compound key,
then one is added to the last element of the key. But what if this key (or key element) is not
a number? Jazz invokes routine JZNXTKY
to “Add 1” to the character string, with “A” becoming “B” and so on. It doesn’t actually add 1, but it will create
a higher key.
12. JZHASH is used instead of EXEC CICS
BIF DIGEST when the test environment is not z/OS. For more detailed
information about JZHASH, see below.
13. JZTrim is called when an assignment
statement uses TRIM, RTRIM, or LTRIM, and in an
ACCEPT statement where the input data is trimmed
before being checked for numeric.
14. JZABNDW is called when a CICS Web
Service abends, either because an invalid SQL Code follows an EXEC SQL
statement, or an invalid CICS response code is returned from EXEC CICS.
15. JZDTVL validates a DATE field (in contrast, JZDTVS validates
other-format data that is assigned to a DATE field).
See JZDTVL Detail
16. JZDTVL2 is called by JZDTVL to check
DAY values > 28 and <= 31, considering leap years. See JZDTVL2 Detail
17. JZTM01 formats a TIME value to its display format (DPIC). It is
used in the COBOL generated for PRINT and other display
statements.
18. JZTM02 is used to convert a TIME to the form required for DB2, i.e. DPIC ‘hh:mm:ss’.
19. JZTMAR is used for TIME arithmetic.
20. JZTMVS is used to validate and
assign compatible fields to a TIME variable.
JZDTVS Detail
JZDTVS is
used to split a CHAR value into a DateDiff structure, which is a group containing Day, Month,
and Year values to be assigned to a DATE field
or used in DATE arithmetic. It applies part of the validation: for
example checking that Day and Year are numbers, and Month is either a number 1
to 12 or one of Jan,Feb,Mar,Apr,May,Jun,Jul,Aug,Sep,Oct,Nov or Dec.
Rules are
designed to make data entry as easy and flexible as possible. For example, here a DATE
field is displayed on a screen awaiting input so that it can be updated: -
The field
has been defined HIREDATE DATE so it has the default DPIC of dd MMM yy, and naturally you can enter a
value 08 Feb 19 to update its value. But
if one had to match the display format EXACTLY users would make many mistakes,
omitting the leading zero, entering the month with incorrect case, and so on. Instead JZDTVS interprets the date according
to these rules: -
1. If the input value is an integer,
then it will be interested as a number of days if it in the range 1 to 366, or
a date in format yyyymmdd if it is entered with no
punctuation, e.g. 20190208 (8th February 2019).
2. If the date is entered as a decimal
number, then it is interpreted as an ordinal date. Thus if you write
19.39 then it is interpreted as day 39 of year 19 (again, 8th
February, 2019)
3. If the date is entered with separation
characters, as in 8/2/19, then the separation character '/' breaks the string into three parts. The separation character is the first
character from the left that is one of '/', '.', '-' or Space.
The DPIC associated with HIREDATE tells JZDTVS
to interpret these three parts in order Day, Month, and Year.
Day and Year must be integers, Month can be either an integer in the range 1 to
12, or a month abbreviation (in any case).
JZDTVS
applies basic validation, but it does not check that the numbers form a valid
date because it is involved in both DATE
arithmetic and in assignment of CHAR fields to DATE fields. When the value is assigned to a DATE, Jazz will generate a DateCheck
routine into your program to detect errors like attempting to set a date to the
73rd of November.
JZDTVL Detail
DEFINE JZDTVL PARAMETERS ANY DATA(
DateIn DATE INPUT,
Message CHAR(80) OUTPUT);
If DateIn is Zero (= valid, Null value), or a
valid date, then Message is returned as SPACE
To be valid, DateIn must be 0, or >=
15830101 and <= 99991231,
=> Message “Out of Range” if not. (The Gregorian calendar was introduced in
October 1582)
Plus the month must be >= 01 and <= 12, => message “Month Invalid” if not
Plus the day must be >= 01 and <= number of
days in the month (considering leap years),
=> Message “Days invalid” if Day
= 0 or > 31
=> Message “Day > Max for Month” for
invalid Day values when 29, 30, or 31
JZDTVL2 Detail
JZDTVL2 is
called by JZDTVL to check February Day values > 28, considering whether this is a Leap
Year.
DEFINE JZDTVL2 PARAMETERS ANY DATA(
Year SMALLINT INPUT,
Month SMALLINT INPUT,
Day SMALLINT INPUT,
Message CHAR(80) OUTPUT);
JZHASH Detail
When you generate a web service program that can update a record, Jazz
creates a record checksum that it writes into the output message. Checksums are calculated according to the
SHA-1 standard, which IBM describes as
The SHA-1 digest is
a cryptographically strong checksum of the string, so for practical purposes it
is unique for each string
Before
allowing an update, the program’s logic will recalculate the checksum and check
that it is identical to the value returned with the input message. For example, the messages used with a service
updating the EMPLOYUP record include: -
DEFINE IWSPGDS SERVICE DATA([Input message
…
ViewState GROUP, [Must not be changed
CheckSum-EMPLOYUP CHAR(40),
END GROUP);
DEFINE OWSPGDS SERVICE DATA([Output message
ERROR VARCHAR(80),
ViewState LIKE IWSPGDS.ViewState,
…
When the test environment is z/OS checksums are calculated with
EXEC CICS
BIF DIGEST RECORD(EMPLOYUP) RECORDLEN(JZ-INT) HEX
RESULT(CheckSum-EMPLOYUP OF
OWSPGDS) END-EXEC.
When the test environment is Micro Focus EXEC CICS BIF is not available,
and instead Jazz generates
CALL
'JZHASH' USING EMPLOYUP JZ-INT CheckSum-EMPLOYUP OF
OWSPGDS.
JZHASH invokes the RMCOBOL program C$SecureHash. It can be used explicitly (when the test environment is Micro Focus) with this signature: -
DEFINE JZHASH PARAMETERS ANY DATA(
Record CHAR(*) INPUT,
Lth INTEGER INPUT,
Hash CHAR(40) OUTPUT);
JZSTXIT Detail
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, 1.14.1.165)
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------
000001
FFFFFF
000001
CURRENT RECORD:
DISPLACEMENT 00000---------|---------|---------|---------|----
000001 %MCNAUGHTON,Vera -š[1]*[1]2013-06-11
FFFFFF0006DCDCECCEDD6E898026206050FFFF6FF6FF
0000011C0C4351478365B5591000C442C22013006011
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
0000BEC6.
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.
Glossary
|
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. |
|
MF |
Micro Focus |
|
MFED |
Micro Focus |
|
VS |
Visual Studio |
|
z/OS |
Z-series Operating System. The operating system for IBM Enterprise Computers (“Z-Series”) |