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 before reading further.

DEFINE – Introduction. 1

record-name. 1

Type Option. 1

DATA (data-list) 2

CPYLIBNAME.. 2

DSNAME.. 3

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');

 

The DEFINE statement has this form: -

DEFINE record-name [Type option]

{DATA (data-list) | LIKE record-name}

[DSNAME dataset-name]

[CPYLIBNAME short-record-name]

;

record-name

A Jazz “record” might be a relational database table, a screen message, a record on 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)         TYPE(xx) is an older form syntax: it is still accepted, and must be used with LIKE.

VSAM or TYPE(VSAM)

etc.  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 have dimension, but 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.

 

If there is no TYPE option then WORK is assumed.

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, and more. A full description of DATA is available here.

LIKE record-name

DEFINE Custf2 LIKE Custf;  defines a record called Custf2 that has the same characteristics as Custf, and can therefore be used in exactly the same way as CustF.  You can give different TYPE, DSNAME, and CPYLIBNAME: for example

            DEFINE Custf2 LIKE Custf DSNAME ‘Custf.VB.COPY’ TYPE(VB);

 

When LIKE is used you must use the keyword TYPE explicitly if you want to change it.  For example, if CustF had type VSAM and Custf2 had type VB, then you’d write.

DEFINE Custf2 LIKE CustF TYPE(VB) DSNAME 'IBMUSER.files.Custf2';

 

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.

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 copied into the COBOL program before it the program is sent to zOS to be compiled.  

 

There are however two exceptions where members in the COBOL copy library (CPYLIB) are required: -

·         SQL record (table) definitions.  SQL definitions must be included into your COBOL programs by

EXEC SQL
    INCLUDE Customer
END-EXEC.
so that the record definition is available both to COBOL and to SQL.  This means that before you can compile the Jazz-generated COBOL there must be a record layout called Customer in CPYLIB.  Jazz therefore automatically creates such an layout when Customer.jzc is saved (and Jazz recognizes that it’s a
TYPE(SQL) definition.

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

 

zOS 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(SQL):   $SQnnnnn

·         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 SQL CPYLIBNAME $SQ00001 DATA(…

and be saved as $SQ00001 at the end of its editing session.  The generated COBOL program will use

            EXEC SQL
                INCLUDE $SQ00001
            END-EXEC.

 

Note: if you assign your own CPYLIBNAME then you must ensure that the name is unique.  Errors that Jazz cannot detect 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.

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.