The DEFINE Statement
Rich data definitions are key to the power of Jazz, so you
should read at least the first part of this Section. The DEFINE
statement’s TYPE option and DATA option are separately described, this Language
Reference page describes the overall syntax of the DEFINE statement and
its other options. You might also like
to refer to The COPY statement, as most DEFINE
statements will be written to be included in a program through COPY.
The DEFINE statement defines the data that you work with in your Jazz programs. You use DEFINE to define working storage, file and database records, parameters, screens, communication areas, and anything else that your program needs to deal with. Here is a basic DEFINE statement: -
DEFINE
IN1 VB DATA(
RDKey GROUP,
Region
DECIMAL(3),
District
DECIMAL(3),
END GROUP,
Name CHAR(15),
SalesThisMonth
DECIMAL(7,2),
SalesYTD DECIMAL(7,2),
BillingCycle
LIKE Types.month,
DateCommenced
CHAR(10))
DSNAME('IBMUSER.FILES.IN1');
DEFINE
record-name
{[Type] DATA
(Data list) | LIKE Record or Group name [Type]}
[CPYLIBNAME name]
[DSNAME dataset-name]
[X-Options]
;
A Jazz “record” might be a relational database table, a
screen or service message, a record in a physical file, or a collection of
fields in working data. Depending on the TYPE
option a record name might follow the restrictions of external names, or it might be valid
to have longer names and to use hyphens.
The type option describes the way in which the data is stored and accessed; for example, the type of file or database handler. Examples are: -
VB or TYPE(VB)
VSAM or TYPE(VSAM)
etc.
TYPE(xx) is an older syntax form: it is still accepted, and must be
used when a DEFINE statement defines one record LIKE another.
If there is no TYPE option then WORK is
assumed.
If present, the type option must precede DATA and other options. This is because different rules might be applied to different types of data. For example, data in a relational database (type SQL) cannot be groups or have dimension, but groups and dimensions are permitted if the data has type VSAM.
SYSTEM is used to define special names like ZERO and $LEN,
and has some special rules.
A full description of TYPE is
available here.
The data-list describes each field or group of fields in the record. The description must include the field’s format – for example CHAR, INTEGER, and so on, but it may also include validation criteria, display formats, initial values, CODES, EXISTS properties that define record relationships, and more.
A MANASYS Jazz definition is much more than a COBOL layout. As well as the fields and groups that correspond to the fields that you’ll see in the COBOL record, there are also some special names like $Found and $Endfile that may be defined elsewhere in the COBOL program, or used by MANASYS Jazz without generating any COBOL fields. When appropriate you can refer to them like other fields, for example CustF.$Found. For some definition types you’ll see names like PK that define the primary and other keys.
A full description of DATA is available here.
DEFINE
Custf2 LIKE Custf;
defines a record called Custf2 that has the same DATA (record
layout) as Custf. The LIKE object may
be another file, or a qualified reference to a GROUP, for example
DEFINE ProgInfo LIKE JZABNDW.Program-Info;
The new
definition (Custf2) may
be identical to CustF except for its record name, or you can give different TYPE, DSNAME, and CPYLIBNAME. For example
DEFINE Custf2 LIKE Custf DSNAME ‘Custf.VB.COPY’ TYPE(VB);
Note that
when LIKE is used you must use the keyword TYPE explicitly
if you want to change it, you do not write DEFINE CustF2 VB LIKE Custf …
If an
object is defined LIKE a group, e.g. ProgInfo, then it will have type
WORK unless the DEFINE includes a TYPE option.
If you do
not give the DSNAME option but the LIKE object is a physical file with a DSNAME option
then Jazz uses creates a DSNAME value for the new file by: -
1.
If
it can find the LIKE name within the DSNAME, this name is replaced by the new
file’s name. Thus
DEFINE Custf VSAM DATA(….)
DSNAME ‘Master.VSAM.Custf’;
DEFINE
Custf2 LIKE Custf;
This will replace “Custf” with
“Custf2”, effectively adding DSNAME ‘Master.VSAM.Custf2’
2.
If
it can’t find the LIKE name, it adds “O” (letter O, not zero) to the LIKE file’s DSNAME
value. This is because we thought that
the most likely use of this feature would be to define an output file – you
were copying CustF to Custf2.
It is
recommended that you write the DSNAME option explicitly, as in the example above.
From
PROCESS FILE1R SORT
MANASYS
inserts
DEFINE IFILE1R LIKE FILE1R MERGESORT;
MERGESORT causes the SORT to read IFILE1R using FILE1R’s
DSNAME, writing it to FILE1R which has been given DSNAME &&FILE1R. See JazzUGMerge.htm
for more information.
Normally
you’ll write record definitions in Jazz copy books. For example, you’ll create a definition of a
record, say “Customer”, as a separate object from the programs using it, and
you’ll save it as Customer.jzc. In a
program using this record layout you’ll then write
PROGRAM Progname ….;
COPY Customer;
logic
and this
record definition will be retrieved and used in your program. This is exactly the same concept as your use
of COPY in manually-written COBOL and %INCLUDE in PL/I.
When Jazz
creates a COBOL program it doesn’t normally generate COPY statements except for a few
standard structures like the CICS control blocks. Instead, the Jazz COPY statement causes the record
description to be directly generated into the COBOL program before it the
program is sent to zOS to be compiled.
There are
however exceptions where members in the COBOL copy library (CPYLIB) are
required: -
·
Web
Service Message Formats. For web
service providers using WSDL Jazz will invoke the web services assistant
program, DFHLS2WS. This requires COBOL
copy books describing the input and output message formats so that DFHLS2WS can
create the .wsdl and .wsbind objects, so before invoking DFHLS2WS Jazz creates
entries in CPYLIB. For web service
providers using JSON Jazz will invoke DFHLS2JS, but again COBOL copy books are
required.
·
The
same is presumably true of web services providers using JSON, with the
substitution of JS for WS, e.g. program DFHLS2JS.
z/OS rules
mean that CPYLIB member names can’t be longer than 8 characters, but what if
the record name is longer? Jazz allows
record names up to 30 characters, and the first 8 characters might not be
unique. CPYLIBNAME provides a solution
to this problem: -
DEFINE ArchivedCustomer SQL CPYLIBNAME ArCust
DATA(…
causes the
CPYLIB member to be named ArCust, even though it will start
01
ArchivedCustomer.
…
If you do
not provide a CPYLIBNAME option and Jazz needs one, it will create one
for you using a name
·
For
TYPE(SERVICE):
$WSnnnnn
where nnnnn
is a five digit number, starting at 00001, chosen to be unique within the
CPYLIB
This property
will be added to the Jazz definition: for example ArchivedCustomer.jzc will
contain
DEFINE ArchivedCustomer SERVICE CPYLIBNAME
$WS00001 DATA(…
and be
saved as $WS00001 at the end of its editing session.
Note: if you
assign your own CPYLIBNAME then you must ensure that the name is
unique. Jazz cannot detect errors that will
occur if you reuse a CPYLIBNAME, either because you write CPYLIBNAME
(samename), or save a record layout with a definition name that matches one of
the CPYLIBNAME values that you’ve used elsewhere.
For example
DEFINE ArchivedCustomer SQL CPYLIBNAME ArCust
DATA(…
and another
definition like this: -
DEFINE ArCust SQL DATA(…
or
DEFINE ArchivedCustomerV2 SQL CPYLIBNAME ArCust
DATA(…
With DSNAME you can
specify the Data Set Name that the system uses to locate the file. For example
you may write: -
DEFINE
CustF VSAM DATA(
Account PIC '999999' HEADING 'Account Number'
KEY,
Region DECIMAL(3),
District DECIMAL(3),
Name CHAR(15) DKEY 'ibmuser.vsam.custf1'
,
SalesThisMonth
MONEY(7,2),
SalesYTD MONEY(7,2),
Billingcycle
LIKE types.month,
DateCommenced
CHAR(10))
DSNAME 'ibmuser.vsam.custf';
When your
program runs file CustF will be associated with dataset 'ibmuser.vsam.custf'. By specifying this name within
your program and Jazz will use this name when it generates a script or JCL to
access the file, and you will not need to amend the JCL to run a batch
program. Note that a dataset name can
also be given with alternate indexes – DKEY and UKEY options.
The value of DSNAME
may include Jazz parameters that will be substituted as Jazz creates the run
script, for example: -
DSNAME '@Project.vsam.custf'.
This is a convenient way of denoting test and production versions of files. Refer to JazzWKConfig for information on Jazz Parameters.
DSNAME is only used for definition types VSAM, ESF, FB, V, VB, and U.
These
options give defaults applied to fields defined without KEY, REQUIRED, or OPTIONAL.
This option only has meaning for SQL and SERVICE definitions.
NOTNULL is
a synonym for REQUIRED, NULL and NULLABLE are synonyms for OPTIONAL.
KEY (but
not DKEY or AKEY) implies REQUIRED.
Otherwise for SQL the
default is OPTIONAL,
for SERVICE the
default is REQUIRED. For these
definition types, if a field is OPTIONAL then there will be an indicator variable generated
into the COBOL definition.
If the file
type is XIO,
meaning External I/O, then the DEFINE
statement may include a variety of options to handle various types of I/O
operation, for example XOPEN, XREAD, XKREAD, etc.
Refer to External
I/O for more details about these options.