XML definitions for a template

Table 1. XML definitions for a template
Lvl Element Attribute Type Description
1 template lang

BASE
IMS

For templates derived from copybooks.

Values:

  • COBOL
  • PLI
  • ASM
    type All Type of template.

Values:

  • BASE
  • IMS™
  • IMSVIEW
  • IMSCRIT
  • Db2®
  • DYNAMIC
    segmented BASE Applies to base templates only and is a Boolean value to indicate the template is segmented or not.

Values:

  • 0
  • 1
  • true
  • false
2 describe   all This is a template description. You can provide up to five occurrences of this element and it equates to five description lines. Maximum length is 54 characters per description line.
2 db2object   Db2 This is the Db2 object in the form owner name.objectname.
2 ssid   Db2 This is the four character Db2 subsystem. This value has no effect for import which uses the SSID of the Db2 session for which it is run.
2 db2rel   Db2 The Db2 release for the template object. This is for information purposes only.
2 dbd  

IMS
IMSVIEW
IMSCRIT

This is the DBD name. It is used as the originating template name for view and extract criteria, when an import is being performed.
2 imstp  

IMS
IMSVIEW
IMSCRIT

This is the IMS template data set name. This overrides the default template data set names provided in the options when importing a view or extract criteria.
2 dbdlib  

IMS
IMSVIEW
IMSCRIT

This is the IMS DBDLIB that is used to build the IMS template. You can specify this element up to six times to provide more than one DBD library to be searched.
2 relcrit max IMSCRIT Relation criteria definitions.

max="nnn" Integer

Enter a number to be used as the default maximum number of target database records to be selected per source database record for the listed logical and application relationships.

If you do not specify, there is no default maximum selections per database record.

    sel   Boolean

Values:

1
Selected
0
Not selected
3 reldbd name   name="DBD name" Source DBD name
    seg   seg="segment name" Source Segment
    targ   targ="DBD name" Target DBD name
    bidir   Boolean and appears on export (bidir="1") if the relationship is bidirectional.
    sel   Boolean

Values:

1
Selected
0
Not selected
    max   max="nnn" Integer

Enter a number to be used as the maximum number of target database records to be selected per source database record for the listed logical and application relationships.

If you do not specify, the relcrit max value is used if specified. If both are unspecified then there is no limit. It is recommended that a value of 2 or 3 is used for bidirectional logical relationships.

2 cset subset IMSCRIT Criteria set subset number.
    sel IMSCRIT Boolean.

Values:

1
Selected
0
Not selected
    desc IMSCRIT Optional description.
2 copybooks  

BASE
IMS

Group element for copybook definitions.
3 library     Data set name where a copybook can be found. This element can be repeated up to 12 times.
3 syslib     Data set name where nested copybooks can be found. This element can be repeated up to ten times.
3 member name   Copybook member name.
    lib   This specifies the library element number from which this copybook must be taken. If not specified the first occurrence in the library data sets specified.
    name01   01 name to be inserted by Z Data Tools.
    segname IMS only Associated IMS segment name.
4 segdesc   IMS only Segment description.
4 redefine offset   Boolean. Set to "1" to tell Z Data Tools to automatically adjust the offset value for each layout so that the starting location is the redefines, union or org field start location.
    chglvl   Boolean. Set to "1" if required. COBOL level change.

This is a COBOL ONLY option which changes the way the level value (specified below) is processed. If you set this option then every occurrence of the specified level value is changed to 01 before the compile step, irrespective of whether the data item has a redefines clause. This option should be used with care as it may result in incorrect offsets to data items, or compile errors as the structure is changed from its intended programmable form.

    level   Source level value that is used to identify redefines or union level clauses that are to generate new record layouts.

This value is used when you have a structure that has defined multiple layouts using COBOL redefines or PL/I unions. Z Data Tools creates a separate record layout or each redefines clause at the given level. After the first matching redefines is found, Z Data Tools creates new layouts for the next and subsequent redefines for the same level and start location. Header and trailing data items are included in each record layout. This field is ignored for Assembler copybooks.

    name   Field Name: This specifies the target field name of the redefines (COBOL), Union (PL/I) or ORG (Assembler) clause.

Z Data Tools uses this value to determine the redefines, union or org statements that are to be represented in a new layout. This is an alternative way of identifying redefines, union and org statements that require new layouts to be generated. You can specify both Level and Field name values and Z Data Tools checks both when generating new layouts.

4 sourcerange fromstr   From string. Z Data Tools searches each source statement for the specified string. The first statement with a matching string starts the extract process. If the From statement is specified (not the default value), then it is used if the string is not found first.
    tostr   To string. Z Data Tools searches each source statement for the specified string. The first statement with a matching string ends the extract process. If the To statement is specified, then the first statement that matches either the To statement value or contains the To string ends the extract.
    fromstmt   From Statement: Start source line number. This tells Z Data Tools the starting statement for extract. If not specified the default start location is statement 1.
    tostmt   To Statement: End source line number. This tells Z Data Tools the ending statement for extract. If not specified the default end location is the last source statement.
3 cobol dbcs

BASE
IMS

Boolean. Set DBCS="1" if the DBCS COBOL compiler option is required.
    maxrc   Maximum acceptable compiler RC, 0-20.
    mixedcase   Boolean. Set mixedcase="1" to retain the original case of the field name as coded in the COBOL copybooks. This feature is only available if you are running with the Z Data Tools COBOL compiler or a minimum compiler level of Enterprise COBOL V4R1.
    dpc   Boolean. Set dpc="1" to use the Decimal-point is comma SPECIAL-NAMES paragraph when compiling COBOL copybooks.
    arith   Boolean. Set arith="1" to use the Arith(extend) COBOL compile option when compiling COBOL copybooks.
4 replace     Group element to provide COBOL replacing strings.
5 repfrom     COBOL replace from string. There should be a matching repto element. Up to five replace from elements supported
5 repto     COBOL replace to string. Should be one for every repfrom string specified.
4 cbladdopp     Additional COBOL compiler options which is added via the CBL statement when a COBOL compile is run to build or update a template. These options are validated during the compile process. To avoid compile errors please ensure the syntax is correct and that any additional data sets required by these options are allocated prior to invoking HFM. Do not exceed 50 bytes.
<cbladdop>compiler options</cbladdop>
3 pli graph

BASE
IMS

Boolean. Set graph="1" to use the GRAPHIC PL/I compiler option.
    maxrc   Maximum acceptable compiler RC: 0-20.
    bin63   Boolean. Set bin63="1" to use the LIMITS(FIXEDBIN(63)) PL/I compiler option.
    fixdec   Boolean. Set fixdec="1" to use the LIMITS(FIXEDDEC(31)) PL/I compiler option.
    unalign   Boolean. Set unalign="1" to add the statement DEFAULT RANGE(*) UNALIGNED;. This changes the default for structure alignments.
4 pliaddopp     Additional PL/I compiler options which are added via the *PROCESS statement when a PL/I compile is run to build or update a template. These options are validated during the compile process. To avoid compile errors please ensure the syntax is correct and that any additional data sets required by these options are allocated prior to invoking HFM. Do not exceed 50 bytes.
<pliaddop>compiler options</pliaddop>
3 asm dbcs

BASE
IMS

Boolean. Set dbcs="1" to use the DBCS assembler compiler option.
    noalign   Boolean. Set noalign="1" to use the NOALIGN assembler compiler option.
4 asmaddopp     Additional HLASM compiler options which are added via the *PROCESS statement when a assembler is run to build or update a template. These options are validated during the assembly process. To avoid assembly errors please ensure the syntax is correct and that any additional data sets required by these options are allocated prior to invoking HFM. Do not exceed 50 bytes.
<asmaddop>compiler options</asmaddop>
2 layout name Not Db2 01 layout name - not applicable to Db2 templates
    copybook

BASE
IMS

The name of the copybook where this 01 layout originated.
    sel Not Db2 Boolean. The default value is "1". Specify sel="0" to deselect the layout.
    segment

IMS
IMSVIEW
IMSCRIT

Segment name
    segsel

IMS
IMSVIEW
IMSCRIT

Boolean. The default value is "1". This is segment selection - it only has value when used for Views and Criteria sets - Typically you can use this to turn off segment selection by setting segsel="0".
    offset not Db2 offset="nnnn" The default value is 0. The start location of all fields in the layout is adjusted by the value provided, which must be in the range -32760 to 32760.
3 criteria type Not Db2 Specify:
type="ID"
Identification criteria
type="SEL"
Selection criteria
type="RID"
Related identification criteria
    byfield   Boolean. The default value is "0". Specify byfield="1" if expressions are specified using byline elements as opposed free format. <exp>expressions</exp> values are ignored if you specify byfield="1".
    or segmented Boolean. The default value is "0" Specify or="1" to OR this criteria with related 01 criteria.
    rname segmented The name of related 01 layout. This is only valid if type="RID" is also specified.
    cset IMSCRIT cset=nnn The subset number this criteria belongs to. The subset number is defined on the cset element subset attribute described above.
4 exp   ALL This is a free format expression or a where clause for Db2 templates. Note: As expressions generally contain special XML characters it is advisable to specify using CDATA as follows:
<exp><![CDATA[ my expression]]></exp>
4 byline   ALL Use the byline and child elements to describe your expression by field. The elements described here map to the by field representation entered through the ISPF interface to provide an expression by field. byfield="1" must be specified on the layout to specify these elements.
    seq   This is the sequence number starting from 1 and incrementing by 1 for each subsequent byline.
    lparen   Specify lparen="(" to insert a left parenthesis before the expression defined by this element.
    rparen   Specify rparen=")" to insert a right parenthesis after the expression defined by this element
    conn   How this expression is to be connect to subsequent expressions. Specify conn="AND" or conn="OR".
    name   The name of the field this expression is to use as the left hand side operand.
5 oper   not Db2 The arithmetic relational operation. See the operators described for the dynamic template panel in this manual for a full description. As operators generally contain special XML characters it is advisable to specify using CDATA as follows:
<oper><![CDATA[ < ]]></oper>
  oper2   Db2 This is the Db2 operator as described in the Z Data Tools User’s Guide and Reference for Db2 Data, see "Row Selection Criteria" and the supported operators.

As operators generally contain special XML characters it is advisable to specify using CDATA as follows:

<oper2><![CDATA[ <]]></oper2>
  byval   ALL This specified the right hand or second operand which must be a valid value for the specified operator and field or column referenced.

It must not exceed 255 characters.

3 symbol   all This element, with its attributes and child elements are used to specify the formatting, create, scrambling and for dynamic templates the field definition itself.
    name   This is the field or column name.
    sel   Boolean. The default value is "1". Specify sel="0" to deselect the column or field.
    seq not Db2 This is a number representing the display order. Lowest number appears first. For example, seq="1".
    hold   Boolean. The default value is "0". Specify hold="1" if you want this field or column to be held in a edit, view or browse session.
    lzero   Boolean. The default value is "0". Specify lzero="1" for numeric fields where the formatting is to include leading zeros
    width   Numeric. This specified an alternate display width for "TABL" formatting of the data.

For example, width="10" sets a display width of 10.

    start dynamic Defines the start column for a field definition in a dynamic template.
    length dynamic Defines the length for a field definition in a dynamic template
    type dynamic Defines the type of field. See the types described for the dynamic template panel in this manual for a full description.
    keyseq   Integer. keyseq='nnnn'

Specify this value to provide a key sequence number used to define the composite key field for data set comparison.

    db2ord Db2 Integer. db2ord='nnnn'

This is a sequence number for Db2 templates that indicates how to order the data based on the data values for the column, when the data is retrieved from Db2.

    db2AD Db2 Integer. Ascending or Descending indicator. (db2AD="A")

This is only valid when db2ord is specified and indicates whether the data retrieved from Db2 is to be in A(ascending) or D(descending) order.

    ref   Integer.

This is the field or column reference number and is used to identify the field.

Note: A field can also be identified by the name="field name". If this value is provided it takes precedence in identifying the field or column.
4 heading   ALL Alternate heading
<heading>Myfield name</heading>
4 lenfld   segmented Tells us that the associated parent symbol is a length field for determining the length of the actual segment. This element should only be provided once for any given layout.
    excl   Boolean. Default value is "0". Specify excl="1" to say the length of the segment is the length provided in this field plus the length of the field.

If not specified or "0" then the length of the segment is the length value provided in this field.

4 createN start ALL The default value is 0. Start="nnnn", where nnn is numeric.

Specifies the initial value you want a field to contain, before being adjusted by the increment you specify. The value must be a number that, when converted to the appropriate numeric data type, the field can hold, and, for a field with decimal places, must not specify more decimal integers than the number of decimal places in the field definition.

If you specify a negative number, the sign is honored, even if the field is unsigned.

If the field is a floating-point field, the start value can be specified as a floating-point number consisting of a mantissa and an exponent (such as -1.14579E01). The mantissa consists of an optional sign (+ or -) followed by 1 to 16 digits. The mantissa can also contain a decimal point. The exponent consists of the letter E, an optional sign (+ or -), and 1 or 2 digits.

    end   The default value is the largest positive or negative number the field can contain. end="nnnn"

Specifies the maximum value (if the increment is a positive number) or minimum value (if the increment is a negative number) you want a field to contain. See rules for start attribute in specifying the number.

    inc   The default value is 0. inc="nnnn"

Specifies a positive or negative number by which you want the value in the field adjusted for each record (or cycle of records). See rules for start attribute in specifying the number.

    cycle   The default value is 1. cycle="nnnn"

Specifies the number of output records that are to be generated before the increment value is applied to the field value. For example, if you specify a field start value of 100, an increment value of 10, and a cycle value of 3, the field in the first three records contains 100, 110 in next three records, 120 in the next three records, and so on.

If cycle is zero, the value in the field is always set to the start value.

4 createDT value Db2 createdt="dd/mm/yy etc"

Specify a date value to be used when creating a new row. The creation attribute is only used for those functions where ZDT/Db2 is to create rows, for example the create utility. You can specify a date value in the same format shown in the Format field. You can specify an = to indicate that the current date is to be used. When you specify this the current value is retrieved and replaces the = in the field. The value retrieved is a constant, so that if a create utility is run later, the same value is always used to populate the column.

You can specify * to indicate that the current date when the row is created should be used to populate the column. Specifying * indicates a variable value for the column when a create utility is run, since the value is the date on which the create utility is executed.

    inc   inc="nnnn"

Specify an increment value to be used when creating multiple rows. Valid values are integers. A value of 1 indicates that each subsequent row should have a date value one day later than the previous date value. A value of -1 indicates that each subsequent row should have a date value one day earlier than the previous date value.

4 createC   ALL Use this to populate field with various patterns.
    act   Action. Specifies how the contents of the field are to be varied for each record. For more information. For example, act="FX". For details of each action, see Options for "act".
    repeat   The default is NO. repeat="YES"

Repeat user pattern. Specify YES if you have provided a user-supplied pattern that is shorter than this field and you want the pattern to be repeated as many times as necessary to fill the field. By default, Z Data Tools uses the fill character to pad the receiving field when the user-supplied pattern is shorter than the field. This option has no effect when the RA action is specified.

HCL-supplied patterns are always repeated in a field, as necessary.

5 filler   ALL
<filler>cccc</filler>

Specifies a value that is to be placed in each byte of the field before any other operation in the construction of the field. Can be one of:

char
A character such as 0 to be written in each byte.
X'cc'
A hexadecimal value, such as X'FF' to be written in each byte.
5 start     <start>cccc<start>

Start character

Sets the starting character to be used when you specify an HCL-supplied pattern (AL, AN, or CO) or a user-supplied pattern (with the exception of RO, WV, and FX). The specified character must be one of the characters in the HCL-supplied pattern or user-supplied pattern.

Default: First character in HCL-supplied pattern or user-supplied pattern.

5 pattern     <pattern>cccc<pattern>

Specifies the pattern to be used when generating data for this field. You can specify either an HCL-supplied pattern indicator or a user-supplied pattern. The user-supplied pattern can be either a character string or a hexadecimal string. A character string must be enclosed in quotation marks, while a hexadecimal string must be enclosed in quotation marks and be preceded by a X. The hexadecimal string must contain an even number of valid hexadecimal characters. The HCL-supplied patterns you can specify are:

AL
Alphabetic - characters A-Z, inclusive.
AN
Alphanumeric - characters A-Z, 0-9 inclusive.
AX
Alphanumeric displayed in long hexadecimal.
CO
Collating sequence - all printable characters in the range X'40' - X'F9'.

If you provide a user-supplied pattern that is longer than the field, for actions other than RA and RP the pattern is first truncated on the right to fit the receiving field before the specified action is performed. For the RA action, characters are randomly selected from the entire user-supplied pattern. For the RP action, the entire pattern is rippled for each record before it is truncated to fit the receiving field. If you provide a user-supplied pattern that is shorter than the field, you can specify that you want the pattern to be repeated to fill the field.

Default: None

4 scramble   ALL Use the scramble element to specify all the scrambling type options for the associated parent symbol.
    type   For example, type="1" Scramble Type. Specify one of these values:
Blank
No scrambling is performed.

Value or range specifications are saved but ignored for the associated function.

1 (Random)
Performs random scrambling.

The same input value produces different output values on subsequent invocations.

2 (Repeatable)
Performs repeatable scrambling.

The same input value produces the same output value on subsequent invocations.

3 (Translate)
Performs translation.

The value data set is searched to find a matching input value. If a match is found, then the output value is taken from the output column of the matching record.

4 (Exit)
Invokes a scrambling user exit.
5 (ODPP)
If you set this value then you must provide the ODPP command using the ODPP attribute described below.
    ODPP   This is the Optim™ Data Privacy Provider command input area. Refer to the ODPP Syntax Guide for the command syntax.
5 translate incol   incol="nnn"

Defines the start location of the input field value on the value data set, and is used when the translate process is run during a copy operation to match the input field with a value on the value data set. The length of the field is set to the length of the input field that is mapped to this field during the copy process.

    outcol   outcol="nnn"

Defines the start location of the output field value on the value data set, and is used as follows during a copy operation:

For scramble type Translate
If an input field value is matched on the value data set, then the corresponding output value is used.
For scramble types Random or Repeatable
The input value is used to randomly or repeatably select an output value from the value data set.

The length of the field is the current field length as displayed on this panel.

This value is required when you select the scramble type Translate. If you select Random or Repeatable, and also select Value, then the start location defaults to 1 if a value data set name (Dsn) has been provided.

    dsn   dsn="data set name"

Defines the value data set. It can be any catalogued sequential, partitioned or VSAM data set containing data that is used to determine the output field value during a copy process.

5 range     This restricts scrambling values to a range of numbers between the min and max values provided on the attributes. You must provide a min and max value
    min   Minimum value. Must be less than the maximum value and greater than or equal to -2GB.
    max   Maximum value. Must be greater than the minimum value and less than or equal to 2GB
5 value outcol   outcol="nnn"

Defines the start location of the output field value on the value data set, and is used as follows during a copy operation:

For scramble type Translate
If an input field value is matched on the value data set, then the corresponding output value is used.
For scramble types Random or Repeatable
The input value is used to randomly or repeatably select an output value from the value data set.
    dsn   dsn="data set name"

Defines the value data set. It can be any cataloged sequential, partitioned or VSAM data set containing data that is used to determine the output field value during a copy process.

6 sval     <sval>field value</sval>

The values you provide are randomly or repeatably selected depending on your scrambling option to populate the output field during the scrambling operation. The field value must be valid data for the associated parent symbol.

5 exitprog name all Enter a 1 to 8 character valid load module member name to identify the scramble exit that is invoked during a copy operation for this output field. Any exit you provide must be in the form of a load module, in any load library available to Z Data Tools at the time of the copy process, either by a STEPLIB DD statement, or in LINKLIST, or LPALIST.
    parm   You can specify a constant value that is passed to the exit for each call type by entering a non blank value in this field.
    format   Boolean. Default value is "0". Specify format="1" to format the field value passed to the exit as display numeric with leading zeros suppressed.
    lzero   Boolean. Default value is "0". Specify lzero="1" to format the field value passed to the exit as display numeric with leading zeros.