The DEFINE Statement

DEFINE – Introduction. 1

record-name. 1

TYPE Option. 1

DATA (data-list) 1

LIKE Record-name or Group. 1

CPYLIBNAME.. 1

DSNAME.. 1

REQUIRED | OPTIONAL. 1

X-options. 1

 

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.

DEFINE – Introduction

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 Statement Syntax

DEFINE record-name

    {[Type] DATA (Data list)  |  LIKE Record or Group name [Type]}

                [CPYLIBNAME name]

                [DSNAME dataset-name]

                [X-Options]

    ; 

record-name

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.

TYPE Option

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.

DATA (data-list)

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.

LIKE Record-name or Group

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

LIKE …  MERGESORT

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.

CPYLIBNAME

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(

DSNAME

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, ESDS, F, FB, V, VB, and U.

REQUIRED | OPTIONAL

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.

X-options

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.