IMS Template Update (ITU)

Purpose
You can use this utility to:
  • Update templates with the latest copybook or DBD definitions.
  • Create new templates based upon existing templates.
Usage notes
  • Template members selected for processing can be filtered by specifying copybook names or masks so that only templates referencing those copybooks are included.
Related functions
ICU
IMS Criteria sets update
IVU
IMS Views update
Figure 1. Syntax

1 ITU
1! INPUT=DDIN
1 INPUT=ddname
1 DSNIN=dsname
1 ? MEMSTART=startstring? MEMEND=endstring
1 MEMBER=member_in
3? XMEMBERS=(+ ,xmem_filter)
3? COPYBOOK=(+ ,member_n)
3? LIBLIST=(+ ,dsn_n)
3? SEGCOPY=(+ ,seg_n?(copy_n))
3? MEMLIST=(+ ,member_n)
3? IMSID=imsid
3? DBDLIST=(+ ,dsn_n)
1! OUTPUT=DDOUT
1 OUTPUT=ddname
1 DSNOUT=dsname?(member_out)
4? MEMOUT=memmask
1! REPLACE=NO
1 REPLACE=YES
1! NOUPDATE=NO
1 NOUPDATE=YES
1! OVERRIDE=NO
1 OVERRIDE=YES
1! PRESERVE=NO
1 PRESERVE=YES
1! BYPASS=NO
1 BYPASS=YES
1! FORCE=NO
1 FORCE=YES
10?  %Copybook processing
Copybook processing

1! LANG=AUTO
1 LANG=
2.1 COBOL
2.1 PLI
2.1 HLASM
2?  %COBOL options
2?  %PL/I options
2?  %HLASM options
COBOL options

1! DBCS=NO
1 DBCS=YES
1! CDPC=NO
1 CDPC=YES
1! CAE=NO
1 CAE=YES
1! MIXED=NO
1 MIXED=YES
1 +  RFROMn=operand1 , RTOn=operand2
1! COMPMAXRC=4
1 COMPMAXRC=num
7? CBLADDOP=options
PL/I options

1! BIN63=NO
1 BIN63=YES
1! DEC31=NO
1 DEC31=YES
1! GRAPHIC=NO
1 GRAPHIC=YES
1! UNALIGNED=NO
1 UNALIGNED=YES
1! COMPMAXRC=4
1 COMPMAXRC=num
6? PLIADDOP=options
HLASM options

1! DBCS=NO
1 DBCS=YES
1! NOALIGN=NO
1 NOALIGN=YES
1! COMPMAXRC=4
1 COMPMAXRC=num
4? ASMADDOP=options
INPUT=ddname
Identifies the DD statement for the data set that contains the templates you want the utility to process. You can specify a PDS(E) or a concatenated PDS(E). The default DD name, DDIN, is used when you do not specify the INPUT or DSNIN parameters.

If the OUTPUT and DSNOUT parameters are not specified, the utility updates the selected members of the specified data set.

DSNIN=dsname
The name of the data set that contains the templates that you want the utility to process.
MEMBER=member_in
Specify the members of the input template data set that you want the utility to process. You can specify a member name (if there is only one member that you want the utility to process) or a member name pattern representing one or more members of the input Template data set.

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.
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.
XMEMBERS
Provides a way to exclude from processing library members that would otherwise be selected using the MEMSTART, MEMEND, and MEMBER options.
xmem_filter
A member name filter identifying one or more members that are to be excluded from processing. A filter can be a member name pattern representing multiple members.

To specify a member name filter containing lowercase characters, use a character string in the format c'string'. Filter values can also be specified as hexadecimal strings in the format x'hex-digits'.

COPYBOOK
When this parameter is specified, the utility restricts the templates that are processed to those that include the copybooks that you specify in this parameter. You can specify a list that includes copybook member names and copybook member patterns. A template is only processed if it includes a copybook that is either specified in the list or matches a copybook member pattern specified in the list.
member_n
A copybook member name or member pattern. Generic name masks are not allowed.
LIBLIST
Allows you to specify a list of up to twelve copybook libraries that contain the copybooks that you want the utility to use.

When the LIBLIST parameter is specified, the utility uses the layout members in the specified copybook libraries to build the template (rather than the layout members in the copybook libraries referenced in the template). So to avoid update errors, you need to ensure that all the layout members referenced in all the templates that the utility is updating are available in the libraries you specify. If the update using the specified copybook libraries is successful, the utility changes the copybook library list in the template to the specified library list.

dsn_n
The name of the copybook library to be searched. Generic name masks are not allowed.
SEGCOPY
When the DBD that a template is built from is modified to include new segment types, you need to provide the following information in the SEGCOPY parameter:
  • The names of all the new segment types in the DBD, and
  • For each new segment type, the name of a copybook member that describes the segment layout.
seg_n
The names of all the new segment types in the databases whose templates you are updating.
copy_n
For each new segment type, the name of a copybook member that describes its layout.
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, FM/IMS uses the input member 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.
IMSID
Allows you to specify the IMS catalog that contains the database definitions (DBDs) that you want the utility to use. You identify the IMS catalog that the function is to use by specifying the subsystem that uses it.

The utility uses the DBDs in the specified IMS catalog when BYPASS=YES is not specified and either or both of these conditions are true:

  • The DBDLIST parameter is not specified.
  • The DBDs that were used the previous time the template's segment list was updated came from an IMS catalog rather than DBD libraries.

When this is the case, the utility searches the specified IMS catalog for a DBD for the database that the template is for and obtains a list of the segment types in the database from the DBD that it finds. If the template's segment list is not the same as this list, the utility updates the template's segment list to make it the same.

If the update of the template is successful, the utility saves the name of the specified IMS catalog in the template.

Note: When the DBDLIST, IMSID and BYPASS parameters are not specified, the utility uses the DBDs in either the DBD library list stored in the template or the IMS catalog stored in the template.
DBDLIST
Allows you to specify a list of up to 6 DBD libraries that contain the database definitions (DBDs) that you want the utility to use.

The utility uses the DBDs in the specified DBD libraries when BYPASS=YES is not specified and either or both of these conditions are true:

  • The IMSID parameter is not specified.
  • The DBDs that were used the previous time the template's segment list was updated came from DBD libraries rather than an IMS catalog.

When this is the case, the utility searches the specified libraries for a DBD for the database that the template is for and obtains a list of the segment types in the database from the DBD that it finds. If the template's segment list is not the same as this list, the utility updates the template's segment list to make it the same.

If the update of the template is successful, the utility saves the specified DBD library list in the template.

Note: When the DBDLIST, IMSID and BYPASS parameters are not specified, the utility uses the DBDs in either the DBD library list stored in the template or the IMS catalog stored in the template.
DSNOUT=dsname
Specifies the name of the data set in which you want the updated templates stored. The data set you specify must be a PDS(E). You can further qualify this data set, as follows:
(member-out)
Where member-out is the member of the specified PDS(E) in which you want the updated template stored.
MEMOUT=memmask
When 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 FM/IMS replaces like-named templates in an output PDS(E).
NO
Like-named templates in the output PDS(E) are not replaced.
YES
Like-named templates in the output PDS(E) are replaced.
NOUPDATE
Specifies whether or not FM/IMS 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 FM/IMS overrides any compile options found in the template with the compiler options found in the parameter list.
NO
Compile options found in the template are not overwritten with the compiler options found in the parameter list.
YES
Compile options found in the template are overwritten with the compiler options found in the parameter list.
PRESERVE
Specifies whether or not FM/IMS uses the current version of the copybook.
NO
FM/IMS searches for the first version of the copybook.
YES
FM/IMS 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.
FM/IMS 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.
FORCE
Specifies whether or not FM/IMS updates the template when changes to the segment list or segment layouts are detected.
NO
If no changes to the segment list or segment layouts are detected during the update process, the update will not take place.
YES
FM/IMS updates the template, even when no changes to the segment list or segment layouts are detected.
BYPASS
Specifies whether or not FM/IMS checks the DBD for any changes to the segment name list. If the DBDs for the databases whose templates you are updating have not had segment types added or removed since the last time the templates were updated, you can specify BYPASS=NO.
NO
FM/IMS does not check the DBD for any changes to the segment name list.
YES
FM/IMS checks the DBD for changes to the segment name list and, if there are changes, updates the template to reflect these changes.
Compiler options
FM/IMS uses the following options when OVERRIDE=YES is specified:
LANG
Determines whether FM/IMS 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 FM/IMS 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 = 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.
CBLADDOP
Additional COBOL compiler options which are included in a CBL statement when compiling COBOL copybooks.
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.
PLIADDOP
Additional PL/I compiler options which are included in a *PROCESS statement when compiling PL/I copybooks.

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 an Assembler 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.
ASMADDOP
Additional HLASM compiler options which are included in a *PROCESS statement when compiling COPY and MACRO members.

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

Batch example

//FMBAT EXEC PGM=FMNIMS
//STEPLIB DD DSN=FMN.SFMNMOD1,DISP=SHR
//SYSPRINT DD SYSOUT=*
//IDIOPTS DD DSN=FMN.IDIOPTS,DISP=SHR
//FMNIMSIN DD *
$$FILEM ITU DSNIN=FMN.IMS.IVP.TEMPLATE,
$$FILEM MEMBER=DJ%E,
$$FILEM MEMLIST=(DJ1E,
$$FILEM          DJ2E),
$$FILEM DBDLIST=(FMN.IMS.IVP.DBDLIB),
$$FILEM DSNOUT=FMN.IMS.IVP.TEMPLATE.MORE,
$$FILEM REPLACE=YES

Update report

IBM File Manager for z/OS IMS Component

          Template Update Report

Template      New name   Type       Status
-------------------------------------------------------------------------------
DJ1E                     Template   Replaced
DJ2E                     Template   Old template requires LIBLIST

FMN1495I 2 members read 0 Updated 0 Not changed 1 Replaced  1 Errors

Report fields

Template
This is the name of the template.
Lib
When there is more than one input library, this column shows the library number from which the template came. This column will only be present if there is more than one template input library.
New name
This is the new output template name if the template was renamed during the update process.
Status
A value from the status table. See Batch update status and action.
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 4.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 File Manager. This is an internal error. If the template has not been modified then keep a copy of it and contact IBM® Support.
SYSLIB not found syslib The syslib referenced in the template could not be found. Rerun the update in foreground using option 4.1 which will list the SYSLIBs which you can then 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 4.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 4.1 or the LIBLIST parameter.
Storage exhausted File Manager 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 4.1 which will list the SYSLIBs which you can then 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 IBM® Support.
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 The update would have been a success, except that you ran with NOUPDATE=YES specified. This means that no updates were 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 4.1. This should allow you to correct the expressions that have been invalidated as a result of your copybook changes.
Segment without layouts The corresponding copy books for a given segment did not produce a layout. Rerun the update in foreground using option 4.1. This should allow you to view the copybooks for each segment and determine which copybooks do not contain data layouts.
Old template requires liblist The template you are trying to update is an old template that does not contain the copybook libraries required for the update process. You need to provide a LIBLIST parameter for batch to provide the copybook data sets. Using option 4.4 you can provide the copybook data sets via the entry panel.
DBD initialization failed The DBD referenced in the template could not be loaded properly. The DBD data set and member name will be listed with the status. Investigate why the DBD data set and member listed in the message are incorrect. Use DBDLIST or option 4.1 online to change the DBD library referenced by the template.
Template allocate error The corresponding template data set for a view or criteria could not be allocated for the update process. Check the data set name. Use the TPLIST parameter or option 4.2/4.3/4.4 to update the originating template data set.
DBD not found member_name The DBD for this template could not be found in the specified DBD library. Ensure that a DBD member_name can be found in the DBDLIST libraries if specified or the DBD library associated with this template.
Template not found member_name The template for this view or criteria set could not be found either in the specified template library. Ensure that a template member_name can be found the TPLIST libraries if specified or the original template data set used to create the view or criteria set.