Jazz LRM: The Type Option

The type-definition, i.e. VSAM, SQL, etc, determines what kind of data is described, what options are valid (and sometimes required) in the rest of the DEFINE statement, rules about the field formats, and what you are able to do with the record defined by this DEFINE statement. It must immediately follow the definition name (“record1” in the example above). Possible options are

SQL, VSAM, ESDS F, FB, V, VB, U, TS, CDF, TDL, XML, XIO, PARAMETERS, SCREEN, SERVICE, SYSTEM, COMMAREA, CONSTANTS, LOCAL, STATIC, and WORK

SQL

(Synonyms DB2, RDB)

Using SQL defines a “record” in a relational database. This record may be a row from a base table, or from a view.

Records defined with SQL may be read, and perhaps updated, with PROCESS and GET statements, and inserted with WRITE.

The items defined in the DATA option may not have dimension, nor be grouped with GROUP/ENDGROUP.

VSAM, ESDS

VSAM records are managed by the “Virtual Storage Access Method”, which has replaced the obsolete ISAM (Indexed Sequential Access Method) in IBM systems. VSAM is a KSDS (Key Sequenced Data Set), and records must have a field or group defined with the KEY property.

ESDS refers to a VSAM Entry Sequenced Data Set. It has no key, and like a PSAM file is read or written in sequence, and cannot be accessed with GET.

Both types of VSAM file must be predefined with IDCAMS. The dialog New/Data/VSAM can create the necessary IDCAMS job for you from a Jazz definition with type VSAM or ESDS.

F, FB, V, VB, U

These are “Physical Sequential Access Method” (PSAM) file organizations, the data being kept in a file that can only be read from front to back. You can process these records with PROCESS, but you cannot use GET. You cannot use these file organizations in a CICS program.

TS

This means “Temporary Storage”, and is a special way of organizing data that is used in a CICS “pseudo-conversation”. You cannot use TS definitions in a batch program.

Temporary Storage files can be processed with GET, PROCESS, and WRITE, although not with DELETE. When you are using GET you give a record number, which is a bit like a Key except that it is not carried in the record. Thus if you have defined a TS file like this: -

DEFINE TS TS DATA(

RECORD LIKE Orders.*)

and you have written 20 records to it with

PROCESS ORDERS WHERE …

TS.Record.* = Orders.*;

WRITE TS;

END PROCESS;

then you can read the 17th record with

GET TS (17);

IX = 17; [Any SMALLINT field

GET TS (IX);

As when a GET WHERE(…) doesn’t find a record, if the value of IX is outside the range 1 – number of records, the GET returns a “Not Found” condition and an initialised record area.

XIO

Means “External I/O”. Use this when the data is read and written via I/O routines. For example

COPY XIOR1;

DEFINE Record1 XIO(XIOR1) DATA(…)

defines a record layout with DATA like any other definition. Because of XIO(XIOR1), when the Jazz program wants to read or write a record it invokes the routines defined within XIOR1.

Refer to this Users’ Guide chapter for information on how to write XIO definitions and routines.

PARAMETERS [BATCH | CICS | ANY | ROUTINE]

When you write

CALL Xxx2 (Field1, Field2);

it is vital that the format of Field1 and Field2 are correct. If you pass Field1 as a CHAR(10) variable, but Xxxx is expecting a SMALLINT then there will be a nasty error when this CALL is executed. Or what if Xxxx expects three parameters, but you’ve only given two. Even worse than a nasty error: there might be a subtle error that doesn’t result in any error message, just incorrect results. It is thus very important that you get it right.

An interface definition gives Jazz the information that it needs to check this, ensuring that errors can be detected or avoided early, not left to run testing. A definition like

DEFINE Xxxx PARAMETERS BATCH DATA(

P1 SMALLINT,

P2 CHAR(30),

P3 INTEGER);

will ensure that Jazz either converts Field1 to the format of P1 or tells you that it can’t, and the fact that you haven’t given the third parameter is immediately detected and reported. It also tells Jazz that Xxxx can only be called within Batch environments (perhaps because it uses statements that are not valid in CICS).

Interface definitions are compulsory for subprograms even when the subprogram has no parameters: -

DEFINE SubPr PARAMETERS BATCH DATA( );

Interface definitions are only required for a ROUTINE if the PERFORM statement passes one or more parameters.

If you create a SUBPROGRAM with Jazz the interface definition will be automatically created and used, but you can create these definitions manually for situations where a subprogram has been written in another language.

Note that the definition name is the same as the subprogram (or routine) name. There is no way to separately name a definition as there is for COMMAREA in a program.

If you have several subprograms that use the same definition then you can create the 2^nd interface definition with

DEFINE Routine2 PARAMETERS LIKE Routine1;

Parameter Items and Parameter Class below give more information. Also, the Users’ Guide chapter JazzUGLogic.htm gives examples of using subprograms and routines.

Parameter Items

· Each of the parameter objects may be a basic type like SMALLINT, CHAR, etc, or a GROUP.

·         If a GROUP then you may define its structure in the usual way, i.e. as a list of next-level objects, possibly including lower-level groups, ending with END GROUP.   You can pass a record to a SUBPROGRAM by defining the corresponding parameter with LIKE, and including an appropriate COPY statement. For example
      COPY Custf;
      DEFINE SubProg PARAMETERS BATCH DATA(

P1 LIKE Custf,

P2 CHAR(30),

P3 INTEGER);

Note 1. This means that P1 has the same structure as a record from Custf, but it is not a file like CustF and so you cannot use I/O statements like GET P1 …

Note 2. For subprograms your parameter definition will be in a COPY book so that each of the calling programs can be guaranteed to have the latest definition. COPY books have to be self-contained, with COPY statements to resolve any LIKE properties as in the example above. With PARAMETERS ROUTINE you are more likely to just write the DEFINE statement into the program with the PERFORM and ROUTINE, as there will already be the required definitions (like Custf) required to resolve LIKE properties.

· Parameters cannot have a dimension (although fields and groups within a GROUP may have a dimension).

· Parameters can be described with properties INPUT, OUTPUT, INOUT.

o INPUT specifies that the parameter is INPUT to the subprogram, i.e. it is passed FROM the calling program TO the subprogram, but the calling program does not expect the value to be changed (and Jazz will ensure that it can’t be).

o OUTPUT specifies that the parameter is OUTPUT from the subprogram, but not passed to it. It doesn’t matter what value the field has on entry to the CALL statement, it will be reset.

o INOUT specifies that data is passed both ways.

· Property OPTIONAL. If this is specified then the parameter may be omitted. There must be a default value (specified with VALUE) unless the parameter is also specified as OUTPUT.

· Property UNSPECIFIED. This data type specifies that the parameter could have any format and length. Often another parameter will give the length of this parameter. For example, a checksum routine is defined

DEFINE JZCKSM PARAMETERS DATA(

Record UNSPECIFIED,

RecordLength SMALLINT,

CheckSum CHAR(36) OUTPUT;

Parameter Class: BATCH | CICS | ANY | ROUTINE

You can specify whether the definition describes parameters passed to a subprogram in CICS or Batch environments, or describes parameters passed to an internal ROUTINE (a COBOL paragraph) with PERFORM.

DEFINE Routine PARAMETERS CICS DATA(

P1 SMALLINT VALUE 20,

P2 CHAR(30),

P3 INTEGER);

If BATCH is specified then Routine can only be called from batch programs. Perhaps it uses PRINT or other I/O statements.

If CICS is specified then Routine can only be called from CICS programs. (Web Service Provider Programs are CICS programs). With CALL statements (but not INVOKE), CICS adds two standard parameters to the list defined with DATA. Thus with

you will write

CALL Routine (X1, X2, X3);

where X1, X2, and X3 are fields defined that are compatible with P1, P2, and P3. Because of CICS, and with X1 etc defined within record R, at the COBOL level the CALL statement will be

CALL ‘Routine’ USING DHFEIBLK DFHCOMMAREA XI OF R X2 OF R X3 OF R.

These two standard parameters are the CICS Exec Interface Block and CICS CommArea.

Specify ANY for basic subprograms that can be called from either CICS or Batch. These programs can’t use any I/O operations (since READ etc are handled differently in COBOL Batch programs and COBOL CICS programs), nor use any CICS commands (so they can’t use SEND, or INSCREEN).

If ROUTINE is specified then the routine can’t be used with CALL, but is invoked with PERFORM. In Jazz PERFORM can pass parameters to a ROUTINE (a Paragraph in COBOL), just as parameters are passed to external programs with CALL.

Parameter Type Matching

Suppose that we have an interface definition

DEFINE SubProg PARAMETERS ANY DATA(

P1 SMALLINT VALUE 20,

P2 CHAR(30),

P3 INTEGER);

and working data

DEFINE R DATA

(X1 INTEGER,

X2 VARCHAR(30),

X3 SMALLINT);

We now write

CALL SubProg (R.X1, R.X2, R.X3);

Jazz can check that the arguments X1, X2, and X3 are compatible with the parameters types. If they are compatible for assignment but are not identical then Jazz generates assignments to the parameter fields before the CALL, and back again afterwards. It’s as if we’d written: -

SubProg.P1 = R.X1;

SubProg.P2 = R.X2;

SubProg.P3 = R.X3;

CALL SubProg (SubProg.P1, SubProg.P2, SubProg.P3);

R.X1 = SubProg.P1;

R.X2 = SubProg.P2;

R.X3 = SubProg.P3;

If the parameters (P1, P2, P3) have the same formats as the arguments (for example, X1 had been defined as SMALLINT then no assignments would have been necessary. Of course no assignments are generated if you assign values to the parameter fields yourself and then name them as arguments: -

SubProg.P1 = 23;

SubProg.P2 = 'A Name';

CALL Subprog(SubProg.P1, SubProg.P2, R.X3);

Constants can simply be written as arguments. A constant effectively has the property INPUT because Jazz doesn’t assign it back again: -

CALL SubProg(23, 'A Name', R.X3);

#263 W SubProg.P1 treated as INPUT

#263 W SubProg.P2 treated as INPUT

It’s as if we’d written

SubProg.P1 = 23;

SubProg.P2 = 'A Name';

SubProg.P3 = R.X3;

CALL Subprog(SubProg.P1, SubProg.P2, SubProg.P3);

R.X3 = SubProg.P3;

Parameter definitions (P1, P2, P3) may have some properties that are not valid in DEFINE statements with other types. A parameter may have property

· INPUT, OUTPUT, or INOUT. If none of these is present, then INOUT is assumed. Hidden assignments to the parameter fields may be used to enforce INPUT and OUTPUT properties.

· OPTIONAL. If present, then the corresponding argument may be omitted from the CALL statement. Jazz will use the parameter, set to its default value, as argument.

SCREEN

The Jazz Screen Editor creates three forms of Screen definition when an editing session is completed: -

name.jzs This is a full description of the screen, in XML format

name.jzm This is a CICS screen map, used by BMS to generate the screen’s physical map

name.jzc This is a DEFINE statement, with form

DEFINE name SCREEN DATA(

item, …);

This is used within a Jazz program to ensure that the program knows the names and types of the fields in the screen.

You are not expected to edit these definitions manually. Normally you won’t even see the screen definition, as it is handled like other copy code and only made visible if the option “Display Copy Code” is checked in the Jazz Workbench configuration window.

With the DATA option of name.jzc there are some unusual options: -

SalesYTD CHAR(10) VALUE('$$$,$$9.99') ASSIGN 'CustF.SalesYTD' SITYPE(2),

1. All screen fields have type CHAR. If they are numeric then appropriate conversions will be generated between the screen and the COBOL program.

2. In screen definitions the VALUE attribute gives the initial value displayed on the screen. For fields this is the output format.

3. ASSIGN names the field that was dropped on to the screen to create this definition.

4. SITYPE(number) denotes the Screen Item Type, i.e. whether this is a constant, a special constant, a normal field (input and output), or an output-only field.

SERVICE

This indicates that the definition describes Web Service data. You will not write these definitions directly: they will be created as a result of dialogs from

PROGRAM name WEBSERVICE

and from web services discovery from

INVOKE ?;

Here is an example: -

*# Last Updated by IBMUSER at 28/07/2015 4:39:20 p.m.

*# Definition created from Web Service SOATst-SOATest1

*# Do not manually edit this definition

DEFINE SOATst-SOATest1 SERVICE DATA(

INPUT VARCHAR(30) VALUE 'ISOATest1',

OUTPUT VARCHAR(30) VALUE 'OSOATest1');

DEFINE ISOATest1 SERVICE DATA(

Name VARCHAR(20) OPTIONAL);

DEFINE OSOATest1 SERVICE DATA(

SOATest1Result VARCHAR(70) OPTIONAL,

Name VARCHAR(20) OPTIONAL);

SYSTEM

SYSTEM records are provided to allow names with special system meanings to be defined to Jazz, without generating anything into the COBOL data division. At the beginning of a program a DEFINE statement naming COBOL’s figurative constants is automatically inserted by Jazz: -

DEFINE COBOL SYSTEM DATA(

ZERO SMALLINT FIGURATIVE,

ZEROS SMALLINT FIGURATIVE,

…

Although nothing is inserted into the program, you are now able to write

Field = Zero;

Jazz makes use of SYSTEM definitions to define COBOL and CICS functions and standard control blocks.

You may find SYSTEM definitions useful to define your own data types that you use in several records. For example, perhaps you have a standard format of Names, Addresses, Phone Numbers, and various other fields. You might define these once in a SYSTEM definition: -

DEFINE TYPES SYSTEM DATA(

Name GROUP,

Title DECIMAL(1) CODES (1:Mr, 2:Mrs, 3:Miss, 4:Dr),

Given-Name VARCHAR(20),

Family-Name VARCHAR(20),

END GROUP,

Address GROUP,

Line1 CHAR(30),

Line2 CHAR(30),

State CHAR(3) CODES (NSW:’New South Wales’,VIC:Victoria,QLD:Queensland,TAS:Tasmania,

SA:’South Australia’, NT:’Northern Territories’, WA:’Western Australia’),

PostCode PIC ‘9999’,

END GROUP)

Now by defining records with

COPY TYPES;

DEFINE CUSTOMER VSAM DATA(

Name LIKE TYPES.Name,

Address LIKE TYPES.Address,

Other stuff ….);

you ensure that all records have a consistent definition of Name and Address, including common validation rules.

For more information about SYSTEM definitions click here.

COMMAREA

If a PROGRAM statement contains “CICS COMMAREA(record)” then the record definition will be incorporated into the program, with COMMAREA. This means that these definitions must exist in the copy library. The PROGRAM statement must include the option CICS.

There can only be one COMMAREA definition in a program. If you include a second with COPY it will be treated as type WORK.

From

DEFINE name1 COMMAREA DATA

field1 …,

field2 …);

Jazz will generate a record area named “name1” in working storage, and another named “DFHCOMMAREA” in the linkage section. On entry the linkage-section record is assigned to the working-storage record: from then on all reference is to the working storage definition.

CONSTANTS

This is like a working storage definition in which every item within the DATA(…) section has the attribute CONSTANT. It is used by Jazz for CICS 3270 screen attributes: -

DEFINE ATTRIBUTES CONSTANTS DATA(

* Basic Attributes

UNPROT CHAR(1) VALUE (X'40'),

UNPROT-NUM CHAR(1) VALUE (X'50'),

PROT CHAR(1) VALUE (X'60'),

…

Jazz won’t generate any COBOL code for unused values, saving space and complexity in the COBOL code.

Users are encouraged to use CONSTANTS definitions rather than leaving “magic numbers” scattered through their code to become errors in later maintenance.

WORK

This is the default if you don’t write any TYPE, so you don’t normally write WORK. It defines data that is used within your program but not stored in a file or database. You use this data in assignment statements and expressions, but you may not use the definition in a PROCESS or GET statement.

LEVEL1

This is used if you want to define individual working-storage fields that are not part of another definition. For example: -

DEFINE AMCR LEVEL1 CHAR(1000);

With this definition AMCR is a single CHAR (1000) field that you can refer to without qualification, for example: -

AMCR = 'ABCDEFGHIJKLMNOP';

LEVEL1 fields may have dimension: -

DEFINE AMCR LEVEL1 (5) CHAR(1000);

in which case references to the field must use this form: -

AMCR.AMCR(2) = 'ABCDEFGHIJKLMNOP';

REDEFINES

DEFINE Record REDEFINES DATA(

Record redefines the previous definition. This previous definition should: -

1. Have a file type other than SQL (V, VB, VSAM, etc), or type WORK. Other types might be valid, but Jazz can’t ensure this.

2. The record must not be longer than the redefined record. For example: -

DEFINE R1 VB DATA(

FIELD1 CHAR(20));

DEFINE R1R REDEFINES DATA(

FIELD1A CHAR(40));

#507 E REDEFINES object R1 is shorter

It is strongly recommended that REDEFINES is used in the same COPY book as the object that it redefines.

The following notes are for future planning, but are not currently implemented.

CDF, TDF, XML

These stand for “Comma Delimited Fields”, “Tab Delimited Fields”, and “eXtended Markup Language” respectively. Like the previous group these are “Physical Sequential” organizations and cannot be used in CICS, and can only be read sequentially. These formats are particularly useful for communicating with Unix and Windows programs.

All data in these formats is carried externally in character format. Depending on the environment this may use EBCDIC encoding, or ASCII encoding, but you don’t need to think about this in your program as you’ll only be dealing with characters like “A” and “a”. You won’t care, and probably you won’t even know, whether “A” is represented as X“C1” or X “41”. In fact the encoding may be changed as the data is sent to/from the mainframe to a Windows or UNIX device.

With CDF, fields are separated by commas. Character string data will be enclosed in quotes, as “,” is a possible character value and without the quotes it would not be possible to distinguish whether an address value of “123 AStreet, ACity” was a single value, or two separate values. Note that you do not need to handle these surrounding quotes yourself: Jazz will insert them on WRITE and remove them on READ.

TDL uses the Tab character as field delimiter. The values can not contain tabs, and so no surrounding quotes are necessary. A value of “123 AStreet<tab>ACity” is two separate fields.

An option with CDF and TDL data specifies whether there is a Header row. If there is, then the first row is a list of the field names. On output this is created from the data definition, in input it is checked against the data definition and an Open Error will be reported if the names don’t match. Case doesn’t matter, so that a heading of “Address” is the same as a field name of “ADDRESS”, but it is different to “Address Line 1”.

XML data is carried in a series of strings like <Address>123 A Street, ACity</Address>. As above, the field names must match the names defined into the definition.

LOCAL

LOCAL and STATIC are not yet implemented.

This is like WORK except that the definition must be written between ROUTINE and END ROUTINE. Using LOCAL applies the following rules: -

1. The record name, and fields within it, may not be referred to outside the ROUTINE.

2. The values will be initialised on every entry to the routine: values are not retained from a previous use of the ROUTINE (see STATIC)

3. There may already be a record of this name elsewhere in the program, either before the first ROUTINE statement or within another routine. These other definitions do not have to have the same data format.

STATIC

STATIC is like LOCAL except that rule #2 becomes

2. The values are initialised at the start of the program, but will be retained on exit from the ROUTINE and so may be re-used on re-entry. Note that in a CICS program the values are not retained when the program terminates: for data to be retained the multiple uses have to be within the same response of a pseudo-conversation.