Criteria set update (ICU)

The ICU (IMS Criteria set Update) function provides you with the ability to update criteria sets using a batch process.

Purpose
You can use this utility to:
  • Update one or more criteria sets.
  • Create criteria sets based upon existing existing criteria sets.
Usage notes
  • You can filter the criteria sets selected for processing by providing the originating template member names or masks.
Related functions
ITU
IMS Template Update
IVU
IMS Views Update
Figure 1. Syntax

1 ICU
1! INPUT=DDIN
1 INPUT=ddname
1 DSNIN=dsname
1 ? MEMSTART=startstring? MEMEND=endstring
1 MEMBER=member_in
3? XMEMBERS=(+ ,xmem_filter)
3? MEMLIST=(+ ,member_n?(criteria_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! FORCE=NO
1 FORCE=YES
7? TEMPLATE=(+ ,member_n)
7? TPLIST=(+ ,mdsn_n)
INPUT=ddname
Identifies the DD statement for the data set that contains the criteria sets you want the utility to process. You can specify a PDS(E), a concatenated PDS(E) or a sequential data set. 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 or the specified sequential data set.
DSNIN=dsname
The name of the data set that contains the criteria set or criteria sets that you want the utility to process.
MEMBER=member_in
When the input criteria data set is a PDS(E) or a concatenated PDS(E), specify the members of the 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 criteria 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.

member_in is ignored if the data set is not a PDS(E).

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'.

MEMLIST
Allows you to specify a list of member names with optional associated output criteria set names. If you do not specify the associated criteria set 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.
criteria_n
The name of the criteria set after it has been copied to the output data set. If unspecified, the output criteria set is not renamed.
OUTPUT=ddname
Identifies the DD statement for the data set in which you want the updated criteria sets stored. The data set you specify must be a PDS(E) or a sequential data set. This parameter does not support concatenated data sets. If the OUTPUT and DSNOUT parameters are not specified, the utility stores the updated criteria sets in the data sets specified in the INPUT or DSNIN parameter.
DSNOUT=dsname
Specifies the name of the data set in which you want the updated criteria sets stored. The data set you specify must be a PDS(E) or a sequential data set. If it is 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 criteria set stored.
MEMOUT=memmask
When a number of input members have been specified, you can specify a member name pattern for the output criteria sets, allowing you to rename your criteria sets 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 criteria sets in an output PDS(E).
NO
Like-named criteria sets in the output PDS(E) are not replaced.
YES
Like-named criteria sets 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.
FORCE
Specifies whether or not FM/IMS updates the criteria set when the template it was created from has not changed.
NO
If the template that the criteria set was created from has not changed, the update will not take place.
YES
FM/IMS updates the criteria set, even if no change has been made to the template that it was created from..
TEMPLATE
When this parameter is specified, the utility restricts the criteria sets that are processed to those that are built from the templates that you specify in this parameter. You can specify a list that includes template member names and template member patterns. A criteria set is only processed if it is built from a template member that is either specified in the list or matches a template member pattern specified in the list.
member_n
A template member name or member pattern.
TPLIST
When this parameter is specified, the templates in the specified data sets are used to update the criteria sets (rather than the template referenced in each criteria set) and, if the update is successful, the utility changes the template data set name in the criteria set to the name of the data set which contains the template that the utility used.
dsn_n
The name of a template data set that you want the utility to use. Generic name masks are not allowed.

Batch example

In this example, a criteria set is updated, removing a segment from the DBD.

//FMBAT EXEC PGM=FMNIMS
//STEPLIB DD DSN=FMN.SFMNMOD1,DISP=SHR
//SYSPRINT DD SYSOUT=*
//IDIOPTS DD DSN=FMN.IDIOPTS,DISP=SHR
//FMNIMSIN DD *
$$FILEM ICU DSNIN=FMN.IMS.IVP.CRITERIA,
$$FILEM MEMBER=DJ1E*,
$$FILEM MEMLIST=(DJ1ESS),
$$FILEM TPLIST=(FMN.IMS.IVP.TEMPLATE.LESS),
$$FILEM DSNOUT=FMN.IMS.IVP.CRITERIA.LESS,
$$FILEM REPLACE=YES

Update report

Update report

IBM File Manager for z/OS  IMS Component

          Template Update Report

Template      New name   Type       Status
-------------------------------------------------------------------------------
DJ1ESS                   Criteria   Replaced

FMN1494I 1 members read 0 Updated 1 Not changed 1 Replaced 0 Errors

Report fields

Template
This is the name of the criteria set.
Lib
When there is more than one input library, this column shows the library number from which the criteria set came. This column will only be present if there is more than one criteria set input library.
New name
This is the new output criteria set name if the criteria set was renamed during the update process.
Status
A value from the status table - see Batch update status and action.