The Type Option describes the method by which the record is stored and accessed, or processed by the system. It has the format: -
DEFINE Record1 VSAM
DEFINE Table1 SQL
or the older format TYPE(type-definition [Option])
DEFINE Record1 TYPE(VSAM)
DEFINE Table1 TYPE(SQL)
The older format is now being removed from documentation, and will eventually be removed from the language.
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, F, FB, V, VB, U, TS, CDF, TDL, XML, XIO, PARAMETERS, SCREEN, SERVICE, SYSTEM, COMMAREA, CONSTANTS, LOCAL, STATIC, and WORK
(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) records are managed by the “Virtual Storage Access Method”, which has replaced the obsolete ISAM (Indexed Sequential Access Method) in IBM systems.
Initially Jazz will support only z/OS, and ISAM support is not provided
These are “Physical Sequential” 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.
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.*;
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.
Means “External I/O”. Use this when the data is read and written via I/O routines. For example
DEFINE Record1 XIO(XIOR1) DATA(…)
defines a record layout with DATA like any other definition. Because of XIO(XIOR1), when the Jazz program want to read or write a record it invokes the routines defined within XIOR1.
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>
When you write
CALL Xxxx (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.
A parameter 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(
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).
If you create a subprogram with Jazz this definition will be automatically created and used, but you can create these definitions manually when a subprogram has been written in another language.
Note that the definition name is the same as the subprogram 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 their interface definitions with
DEFINE Routine2 PARAMETERS LIKE Routine1;
· Each of the parameter objects may be a basic type like SMALLINT, CHAR, etc, or a GROUP.
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.
DEFINE Routine PARAMETERS DATA(
P1 LIKE Custf,
Note that 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 …
· 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, the Checksum routine is defined
DEFINE JZCKSM PARAMETERS DATA(
CheckSum CHAR(36) OUTPUT;
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,
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. 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 ALL 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.
If none of the options BATCH, CICS, or ROUTINE are specified then Jazz waits until either CALL RoutineName or PERFORM RoutineName is encountered: -
If PERFORM RoutineName is encountered first, then
· CALL RoutineName will be invalid
· There must be a ROUTINE RoutineName statement within the program
If CALL RoutineName is encountered first, then
· PERFORM RoutineName will be invalid
· ALL is assumed, so the external routine (i.e. a subprogram) can be invoked from both Batch and CICS programs. It may not use any batch-only or CICS-only Jazz statements like PRINT or SEND, nor do any other type of I/O (PROCESS, GET, DELETE statements).
Suppose that we have an interface definition
DEFINE SubProg PARAMETERS BOTH DATA(
P1 SMALLINT VALUE 20,
and working data
DEFINE R DATA
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 field may have property
· INPUT, OUTPUT, or INOUT. If none of these is present, then INOUT is assumed. Hidden assignments to the parameter fields may also 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.
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(
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.
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
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,
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(
Title DECIMAL(1) CODES (1:Mr, 2:Mrs, 3:Miss, 4:Dr),
State CHAR(3) CODES (NSW:’
PostCode PIC ‘9999’,
Now by defining records with
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.
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.
DEFINE name1 COMMAREA DATA
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.
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.
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.
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';
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(
DEFINE R1R REDEFINES DATA(
#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.
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 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.