BTU (Batch Template Update)

Purpose
Use this utility to:
  • Update one or more templates.
  • Create new templates based upon existing templates.
Usage notes
  • You can filter the templates selected for processing by providing copybook member names or member masks so that only templates referencing such copybooks are updated.
Related functions
BTB
Batch template build
Read syntax diagramSkip visual syntax diagram
Syntax

        .-INPUT=DDIN---.   
>>-BTU--+--------------+---------------------------------------->
        +-INPUT=ddname-+   
        '-DSNIN=dsname-'   

>--+-+----------------------+--+------------------+-+----------->
   | '-MEMSTART=startstring-'  '-MEMEND=endstring-' |   
   '-MEMBER=member_in-------------------------------'   

>--+---------------------------+--+-----------------------+----->
   |            .-,--------.   |  |           .-,-----.   |   
   |            V          |   |  |           V       |   |   
   '-COPYBOOK=(---member_n-+-)-'  '-LIBLIST=(---dsn_n-+-)-'   

>--+-------------------------------------------+---------------->
   |           .-,-------------------------.   |   
   |           V                           |   |   
   '-MEMLIST=(---member_n-+--------------+-+-)-'   
                          '-(template_n)-'         

   .-OUTPUT=DDOUT-------------------.                       
>--+--------------------------------+--+----------------+------->
   +-OUTPUT=ddname------------------+  '-MEMOUT=memmask-'   
   '-DSNOUT=dsname-+--------------+-'                       
                   '-(member_out)-'                         

   .-REPLACE=NO--.  .-NOUPDATE=NO--.  .-OVERRIDE=NO--.   
>--+-------------+--+--------------+--+--------------+---------->
   '-REPLACE=YES-'  '-NOUPDATE=YES-'  '-OVERRIDE=YES-'   

   .-PRESERVE=NO--.                                
>--+--------------+--+-------------------------+---------------><
   '-PRESERVE=YES-'  '-| Copybook processing |-'   

Copybook processing

   .-LANG=AUTO-------.                          
|--+-----------------+--+-------------------+------------------->
   '-LANG=-+-COBOL-+-'  '-| COBOL options |-'   
           +-PLI---+                            
           '-HLASM-'                            

>--+------------------+--+-------------------+------------------|
   '-| PL/I options |-'  '-| HLASM options |-'   

COBOL options

   .-DBCS=NO--.  .-CDPC=NO--.  .-CAE=NO--.  .-MIXED=NO--.   
|--+----------+--+----------+--+---------+--+-----------+------->
   '-DBCS=YES-'  '-CDPC=YES-'  '-CAE=YES-'  '-MIXED=YES-'   

   .-MIXED=NO--.                                               
>--+-----------+--+----------------------------------------+---->
   '-MIXED=YES-'  | .------------------------------------. |   
                  | V                                (1) | |   
                  '---RFROMn=operand1--RTOn=operand2-----+-'   

   .-COMPMAXRC=4---.   
>--+---------------+--------------------------------------------|
   '-COMPMAXRC=num-'   

PL/I options

   .-BIN63=NO--.  .-DEC31=NO--.  .-GRAPHIC=NO--.   
|--+-----------+--+-----------+--+-------------+---------------->
   '-BIN63=YES-'  '-DEC31=YES-'  '-GRAPHIC=YES-'   

   .-UNALIGNED=NO--.  .-COMPMAXRC=4---.   
>--+---------------+--+---------------+-------------------------|
   '-UNALIGNED=YES-'  '-COMPMAXRC=num-'   

HLASM options

   .-DBCS=NO--.  .-NOALIGN=NO--.  .-COMPMAXRC=4---.   
|--+----------+--+-------------+--+---------------+-------------|
   '-DBCS=YES-'  '-NOALIGN=YES-'  '-COMPMAXRC=num-'   

Notes:
  1. n= 1 to 5.
INPUT=ddname
This points to the input DD name which can have one or more associated data sets that must be valid template data sets. If you do not specify INPUT or DSN parameters, then the DD DDIN is used as a default DD name for the input data sets. You can specify concatenated data sets. If an output data set is not provided, the template is updated in the data set from which it originated.
DSNIN=dsname
Data set name where templates reside.
MEMBER=member_in
The name of a single member in a PDS, or a member name pattern representing one or more members in a PDS to be processed.

A member name pattern can consist of any characters that are valid in a member name and two special pattern characters: the asterisk (*) and the percent symbol (%).

*
represents any number of characters. As many asterisks as required can appear anywhere in a member name pattern. For example, if you enter a member name pattern of *d*, all members in the PDS whose name contains “d” are processed.
%
is a place holding character that means a single character. As many percent symbols as necessary can appear anywhere in a member name pattern. For example, if you enter a member name pattern of %%%%, all members in the PDS whose name is four characters in length are processed.

member_in is ignored if the data set is not a PDS.

MEMSTART=startstring
Is used to specify the start of a range of member names to be included. If MEMSTART is specified but MEMEND is omitted, all members of the PDS(E) from the startstring value onwards are included. startstring can have the same values, including wild cards, as for the member-in parameter of the MEMBER keyword.
MEMEND=endstring
Is used to specify the end of a range of member names to be included. If MEMEND is specified but MEMSTART is omitted, all members of the PDS(E) up to the endstring value onwards are included. endstring can have the same values, including wild cards, as for the member_in parameter of the MEMBER keyword.
COPYBOOK
Allows you to specify a list of member names or patterns used to filter so that only templates referencing those copybooks, or copybooks that match the patterns, are selected for processing.
member_n
The name of the member to be processed. Generic name masks are not allowed.
LIBLIST
Allows you to specify a list of up to twelve data set names used to replace the copybook library lists in the selected templates.
dsn_n
The name of the data set name to be processed. Generic name masks are not allowed.
MEMLIST
Allows you to specify a list of member names with optional associated output template names. If you do not specify the associated template name, Z Data Tools uses the copybook name or the name as identified by the MEMOUT mask, memmask.
member_n
The name of the member to be processed. Generic name masks are allowed.
template_n
The name of the template after it has been copied to the output data set. If unspecified, the output template is not renamed.
OUTPUT=ddname
Identifies the DD card which points to the template data set in which the templates are stored or replaced. It must refer to a PDS, PDSE, or sequential data set. Concatenated data sets are not supported.
DSNOUT=dsname
Defines the data set name where templates are created. It must be a PDS, PDSE, or sequential data set. You can further describe this data set, as follows:
(member-out)
Where DSNOUT=dsname specifies a PDS and you want to send the output to a specific member within this data set, this defines the output member name.
MEMOUT=memmask
Where a number of input members have been specified, you can specify a member name pattern for the output templates, allowing you to rename your templates as they are created. The member name pattern can consist of any characters that are valid in a member name and two special pattern characters: the asterisk (*) and percent sign (%).
Asterisk (*)
The asterisk is a place-holding character that means multiple characters with no change. Only one asterisk should appear in the mask. Any subsequent asterisk characters are treated as percent signs. For example, if you enter:
ABC*

The renamed members all begin with ABC followed by the remainder of the old member name.

Percent sign (%)
The percent sign is a place-holding character that means a single character with no change. As many percent symbols as necessary may appear anywhere in a member name. For example, if you enter:
%%%A*
The 1st 3 characters of the renamed members remain unchanged, the 4th character is replaced with the letter “A” and the remainder of the old member name remains unchanged.
REPLACE
Specifies whether or not Z Data Tools replaces like-named templates in an output partitioned data set.
NO
Like-named templates in the output partitioned data set are not replaced.
YES
Like-named templates in the output partitioned data set are replaced.
NOUPDATE
Specifies whether or not Z Data Tools writes back updates to the data set.
NO
Updates are written back to the data set.
YES
Updates are not written back to the data set.
OVERRIDE
Specifies whether or not Z Data Tools overrides any compile options found in the template with the compiler options found specified in the parameter list.
NO
Compile options found in the template are not overwritten with the compiler options found specified in the parameter list.
YES
Compile options found in the template are overwritten with the compiler options found specified in the parameter list.
PRESERVE
Specifies whether or not Z Data Tools uses the current version of the copybook.
NO
Z Data Tools searches for the first version of the copybook.
YES
Z Data Tools uses the current version of the cookbook, provided the copybook still exists in the library it was previously found in, and the library is in the list the update process is using.

Z Data Tools searches for the first version of the copybook in the order the libraries are listed if one of these conditions applies:

  • NO has been specified for this option.
  • The copybook no longer exists in the library it was previously found in.
  • The library is not in the list the update process is using.
Compiler options
If you specify OVERRIDE=YES, then the specified compile options shown here override the options found in the template:
LANG
Determines whether Z Data Tools automatically detects the copybook language or interprets the language as COBOL, PL/I, or HLASM.
AUTO
Automatically detect whether the copybook language is COBOL or PL/I, and invoke the appropriate compiler. If the compilation results in a return code greater than 4, then invoke the compiler for the other language. If the second compilation also results in a return code greater than 4, then retry the first compiler and report the compilation errors. If Z Data Tools successfully creates a template (despite the compilation errors), then continue processing with the template.
COBOL
Invoke the COBOL compiler to create a template from the copybook. (Do not invoke the PL/I compiler, even if the COBOL compilation results in errors.)
PLI
Invoke the PL/I compiler to create a template from the copybook. (Do not invoke the COBOL compiler, even if the PL/I compilation results in errors.)
HLASM
Invoke the HLASM compiler to create a template from the copybook.
COBOL options
The following options are used to compile a COBOL copybook into a template:
DBCS=YES
Use the DBCS compiler option.
DBCS=NO
Use the NODBCS compiler option.

For details on the effect of the DBCS and NODBCS compiler options, see the IBM COBOL Programming Guide for OS/390 & VM.

CDPC=NO
Do not use the COBOL SPECIAL-NAMES paragraph "Decimal-point is comma".
CDPC = YES
Use the COBOL SPECIAL-NAMES paragraph "Decimal-point is comma".
CAE=NO
Do not use the COBOL compile option ARITH(EXTEND).
CAE = YES
Use the COBOL compile option ARITH(EXTEND).
MIXED = NO
Field names stored in the template in uppercase.
MIXED = NO
Field names stored in the template in uppercase.
MIXED = YES
Field names stored in the template in the original case as coded in the COBOL copybook.
RFROM1 RTO1 … RFROM5 RTO5
Up to five pairs of “From” and “To” pseudo-text character strings for the COBOL REPLACE compiler-directing statement.

If your COBOL copybooks contain characters that you want to remove or replace with other characters before compiling the copybooks into templates, then use these replacing options.

For example, if your copybooks contain colon characters (:) that you want to remove before compiling, then specify '==:==' as operand1 and '=====' as operand2.

For details on specifying “From” and “To” strings for COBOL REPLACE, see the IBM COBOL Language Reference.

COMPMAXRC
Sets the maximum acceptable return code for a copybook compile. A return code higher than the specified level causes the function to stop. Default is 4.
PL/I options
The following options are used to compile a PL/I copybook into a template:
BIN63=YES
Use the LIMITS(FIXEDBIN(63)) compiler option.
BIN63=NO
Use the LIMITS(FIXEDBIN(31)) compiler option.
DEC31=YES
Use the LIMITS(FIXEDDEC(31)) compiler option.
DEC31=NO
Use the LIMITS(FIXEDDEC(15)) compiler option.
GRAPHIC=YES
Use the GRAPHIC compiler option.
GRAPHIC=NO
Use the NOGRAPHIC compiler option.
UNALIGNED=YES
Use the DEFAULT RANGE (*) UNALIGNED, language statement to change the default alignment.
UNALIGNED=NO
Use the PL/I default.
COMPMAXRC
Sets the maximum acceptable return code for a copybook compile. A return code higher than the specified level causes the function to stop. Default is 4.

For details on the effect of these compiler options, see the IBM VisualAge PL/I for OS/390 Programming Guide.

HLASM options
The following options are used to compile a HLASM copybook into a template:
DBCS=YES
Use the DBCS compiler option.
DBCS=NO
Use the NODBCS compiler option.
NOALIGN=YES
Use the NOALIGN compiler option.
NOALIGN=NO
Use the ALIGN compiler option.
COMPMAXRC
Sets the maximum acceptable return code for a copybook compile. A return code higher than the specified level causes the function to stop. Default is 4.

For details on the effect of these compiler options, see the HLASM V1R6 Programmer's Guide.

//DDIN   DD DSN=HFMUSER.TEMPLAT1,DISP=SHR
//       DD DSN=HFMUSER.TEMPLAT2,DISP=SHR
//SYSIN DD *
$$FILEM BTU INPUT=DDIN,
$$FILEM MEMLIST=(COPYTST,
$$FILEM          COPY01,
$$FILEM          COPY0102)

Report 1 Data set list (only produced for multiple input data sets).

Data set name                                  Lib
---------------------------------------------------
HFMUSER.TEMPLAT1                                 1
HFMUSER.TEMPLAT2                                 2

Update report

          Template Update Report

Template  Lib New name              Status
-----------------------------------------------------------------------------
COPYTST     1                       Updated
COPY01      1                       Not replaced
COPY0102    2                       Updated

3 members read 2 Updated 0 Not changed 1 Not replaced  0 Errors
Table 1. Batch update status and action
Status Explanation Action
Updated The template was successfully updated. None
Not Replaced The template exists in the output data set and the replace option is NO. Specify replace and rerun if required.
Replaced The template exists in the output data set and has been successfully updated with replace option YES. None.
Compile Error Unable to compile the copybooks associated with the template. Rerun using option 7.4 in foreground for the failing template and look at the compile listing produced.
Corrupt Template The internal format of the template is corrupted. This could have occurred because the template has been modified outside of Z Data Tools. This is an internal error. If the template has not been modified then keep a copy of it and contact you IBM® representative.
SYSLIB not found syslib The syslib referenced in the template could not be found. Rerun the update in foreground using option 7.1 which will list the SYSLIBs which you can them modify. Alternatively provide LIBLIST=(dsn1,dsn2...) parameter to identify the current location for the copybooks.
SYSLIB invalid attrs syslib The syslib referenced in the template has invalid attributes for the language type for this template. Change the syslib reference using option 7.1 or LIBLIST parameter.
Copybook not found name The copybook name could not be located in the current libraries. Provide the data set containing the referenced copybook using either 7.1 or the LIBLIST parameter.
Storage exhausted Z Data Tools ran out of storage during processing Increase the region size.
No copybooks in libraries The library list provided either from the template or override has no copybooks. Rerun the update in foreground using option 7.1 which will list the SYSLIBs which you can them modify. Alternatively provide LIBLIST=(dsn1,dsn2...) parameter to identify the current location for the copybooks.
Not a valid template The type of template is not valid for update processing. This is an internal error that should never occur—contact your IBM support center.
Duplicate name The output template name has already been referenced by another template during update. Correct parameters so that there are no duplicate names being saved.
Not found The template member referenced could be not be found on the input data set. Correct the input parameters to point to the right data set or member name.
Save error The updated template could not be saved Normally a space problem—check the output data set (or input data set if an output data set was not provided) and increase the size.
Update check successful Running with NOUPDATE=YES and update would have been done. None.
Updating of criteria failed The update was not performed because fields that were previously referenced in criteria could not be found in the current versions of the copybooks. Rerun the update in foreground using option 7.1 and the U command. This should allow you to correct the expressions that have been invalidated as a result of your copybook changes.