Purpose

Related Reading: See z/OS DFSMSrmm Implementation and Customization Guide for information about using the DFSMSrmm parmlib OPTION COMMANDAUTH command and authorizing the use of the DFSMSrmm subcommands.

Use the SEARCHDATASET subcommand to create a list of data sets that match criteria you specify. You can specify a generic name using the full set of filter masks. Specify a fully-qualified name to restrict the search to data sets that match the name exactly. Specify the FILESEQ operand to restrict the search to data sets at a relative position on the volume. You can also use the JOBNAME operand to restrict the search to data sets that are created by a particular job name.

You can restrict how many data sets DFSMSrmm lists by specifying the LIMIT operand. DFSMSrmm searches until it reaches your limit or until it finds all data sets that match your search criteria. If you do not specify a search limit, DFSMSrmm lists a maximum of ten data sets.

Table 1 shows the information DFSMSrmm returns for each data set in the order it is displayed:

Parameters

ABEND(YES|NO)

Specifies the search to volumes containing data sets that were closed as a result of ABEND processing.

ADD

Specify this operand to request that new records written to the CLIST data set are added after any existing records in the data set. When the CLIST data set is empty or DFSMSrmm creates the CLIST data set during command execution, specifying ADD is the same as specifying START.

ADD is mutually exclusive with START.

You can easily build a set of commands from CLIST processing using multiple SEARCH subcommands of the same or different resource types. For variable length records, the minimum record length can cause the LRECL to be increased. For fixed length records, if the minimum length cannot be accommodated, the subcommand fails.

BESKEY(key)

Specify this operand to search for data sets based on their CA Tape Encryption key index, which is set by the BES subsystem. To search for data sets that have:

• A specific encryption key index value, specify BESKEY(key)
• Any non-zero encryption key index value set, specify BESKEY(*)
• No encryption key index value (that is, a key index value of 0), specify NOBESKEY.

CATALOG

Specifies to limit the search to data sets based on catalog status. Specify CATLG(UNKNOWN) to search for data sets that have not yet been catalogued. Specify CATLG(YES) to search for data sets that are currently cataloged. Specify CATLG(NO) to list only data sets that have been uncataloged. CATALOG can be abbreviated as CATLG.

CHAIN

Specifies the search for all physical files in the same multivolume data set. DFSMSrmm returns all the files in the set in volume sequence order starting from the first volume and file in the multivolume data set. You must provide a data set name and a volume serial number of a physical file in the multivolume data set. If you do not specify a file sequence number, DFSMSrmm uses the default file sequence value of 1. The value you specify the number of the physical file on the volume you specify for the search. The output might consist of files with numbers which are different from this number; a multivolume data set can start on any physical file on a volume, but on each subsequent volume the file sequence number is 1.

When you use the CHAIN operand, DFSMSrmm ignores all other operands you specify except for the ADD, CLIST, LIST, NOLIST, START operands.

This operand is optional and has no default.

CLIST(prefix_string,suffix_string)

Specifies a CLIST to create a data set of executable commands. You can edit the data set to remove any data sets you do not want in the list. Then you can run the CLIST at your convenience.

DFSMSrmm returns the name of the data set, a data set sequence number, and the volume serial number of the volume on which the data set resides you do not specify (prefix_string and suffix_string).

You can add RMM TSO subcommands and operands to the records in the CLIST data set by specifying (prefix_string and suffix_string). These text strings cannot exceed 255 characters. Separate the prefix_string and suffix_string using a blank or a comma between the text strings. Insert blanks in the prefix and suffix values to prevent DFSMSrmm from concatenating the strings with the data that DFSMSrmm returns. To enter a null prefix_string, add a pair of separator characters such as '' to the text string (for example, CLIST('','suffix_string')).

See Creating CLISTs of executable subcommands for information about the data set used for the CLIST output.

CONTINUE(DSNAME(dsname)VOLUME(volser)FILESEQ(seq))

Specify the CONTINUE operand without any value to notify DFSMSrmm SEARCH subcommand processing that you want to break down the search results based on the LIMIT value and request that DFSMSrmm return the search continue information for use with the next command. For TSO, the continue information is returned either as a REXX variable or as a line mode message. When the subcommand is issued from the DFSMSrmm API, the continuation information may be either a line mode message or an SFI or XML attribute.

CONTINUE is an optional operand.

Use the LIMIT operand to control the maximum number of entries to be returned each time you start or continue the search.

To continue a previous search subcommand, the CONTINUE operand value includes all of these values to identify the current search position:

DSNAME(dsname)

dsname is one to 44 characters enclosed, in single quotation marks if it contains any special characters, or blank.The default is "*" (an asterisk).

VOLUME(volser)

volser is one to six characters, enclosed in single quotation marks if it contains any special characters, or blank.

FILESEQ(seq)

seq is a number within the value range 0 to 65535.

The information required to continue a search subcommand is returned by each search subcommand that specifies the CONTINUE operand and passed back to DFSMSrmm unchanged in order to continue the previous search. You should specify the exact same subcommand unchanged. To do this, just change the CONTINUE operand value on each additional command required.

CRDATE

Lists the data sets whose creation date matches the specified date criteria. CRDATE is mutually exclusive with the SINCE operand. CRDATE may be specified as any of the following:

CRDATE

Only data sets whose creation date is the current date are listed

CRDATE(START(start_date))

Only data sets whose creation date is on or after the specified start date are listed, where start_date is either an absolute date or relative date.

CRDATE(END(end_date))

Only data sets whose creation date is on or before the specified end date are listed, where end_date is either an absolute date or relative date. Note that because START defaults to the current date, the specified end date equal to or greater than the current date when START is omitted.

CRDATE(START(start_date)END(end_date))

Only data sets whose creation date is within the range delimited by the specified start and end dates are listed, where both start_date and end_date are either an absolute date or relative date. The specified end date equal to or greater than the specified start date.

Each of the start_date and end_date values can be absolute or relative dates.

Absolute dates are specified as either yyyy/ddd or yyddd format. For example, January 3, 2011 may be specified as 2011/003 or 11003.

Relative Dates are specified as a number of days, months, or years prior to the current date.

-0

specifies the current day, current month, current year.

-n

specifies that the date is n days before the current date

-nM

specifies that the date is n months before the current month and the current day in the month is as the current date.

-nY

specifies that the date is n years before the current year and the current day in the year is as the current date.

The value range for n is 0 to 99999, with a required leading dash (‘-‘) and an optional suffix of M or Y.

Examples: To list data sets whose creation date is:

Today

specify: SD CRDATE

Three days ago

specify: SD CRDATE(START(-3) END(-3))

Before January 1, 2000

specify: SD CRDATE(START(0000/001) END(1999/365))

On or after January 2, 2005

Specify: SD CRDATE(START(2005/002))

CRSYSID(creating_system_ID)

Specifies data sets based on the ID of the system on which the data set was created. Specify a one-to-eight character unique system name.

DATACLASS(dataclass_name)

Specifies to limit the search to data sets with the specified data class name. A data class name is one-to-eight alphanumeric, national, or special characters. DATACLASS is mutually exclusive with NODATACLASS.

DELETED(NO | YES)

Specifies to limit the search to data sets based on deleted status. Specify:

DELETED(YES)

to search for data sets that are deleted.

DELETED(NO)

to list only data sets that are not deleted.

The default value is NO.

DSNAME(full_or_generic_data_set_name)

Specifies a data set name. Specify a fully-qualified data set name to list only those data sets that match the name exactly. DFSMSrmm does not check data set names for valid characters. Any string of up to 44 characters is accepted, except those that start with a blank or x'00'. Data set names without quotes have your TSO PROFILE PREFIX value applied. Any data set name containing generic characters is validated against the basic mask rules. However, if the mask rules are not met, the data set name is treated as non-generic.

Note: DFSMSrmm does not fold data set names to uppercase letters when you specify quoted data set names. When you specify data set names or data set name masks, be sure to specify the correct case for each character. If you create VRS data set name masks with lowercase or mixed case letters, these will not match to data sets with all uppercase characters.

In addition to normal data set naming conventions, you can use these masking characters:

* (asterisk)

A single * represents a single qualifier of any number of characters.

A single * when used within a qualifier represents zero or more characters.

More than one single * can be used within a qualifier as long as a character precedes or follows the *.

.** represents zero or more qualifiers. At the end of the mask, it indicates to ignore any remaining characters.

** indicates to select all data sets.

% (percent sign)

A place holder for a single character.

Period (.)

A leading or trailing period is not allowed. Consecutive periods are also not allowed.

Double asterisk (**)

Cannot be specified within a data set name qualifier.

For example, you can specify DSNAME('USERID.**.CONF.*'). As another example, you can specify the fully-qualified data set name, USER.ALL.DATA or the generic data set name, USER.*.DATA.

You can specify an asterisk instead of a name to list all data sets that meet the other search criteria.

EXPDT(date_range)

Lists the data sets whose current expiration date matches the specified date criteria. The date criteria can be specified using the START and END suboperands. See the description of the SEARCHDATASET CRDATE operand for a description of how to use the START and END suboperands and examples of their use.

FILESEQ(*|physical_file_sequence_number)

Specifies data sets based on the relative position on a volume. The maximum allowable decimal value is 65535. Specify an asterisk (*) to list all data sets on the volume.

The default value is *.

FORCE

Limits the search based on whether the force flag of a data set is set. If the force flag is set, it means that information about the data set has been changed by a CHANGEDATASET subcommand with the FORCE operand and the requested change was made only because FORCE was specified. Specify FORCE(YES) to list only those data sets whose force flag is set on. Specify FORCE(NO) to list only those data sets whose force flag is not set.

There is no default value for FORCE. If FORCE is not specified, data sets are listed without regard to how their force flag is set.

JOBNAME(create_jobname|*)

Specifies the job name that created the data set. A job name is one-to-eight alphanumeric characters or $, #, or @. You can use a generic job name. Use % in your generic job name mask to match any one character and * to match any character string in the jobn ame.

If you do not specify JOBNAME, all data sets are listed.

If you specify JOBNAME(*), DFSMSrmm returns all data sets that match the specified data set name that have a job name. Data sets that do not have a job name are not listed. JOBNAME is mutually exclusive with NOJOBNAME.

If you have data sets with job names that include symbols other than alphanumeric characters, $, #, or @, use a generic job name to find them.

LASTCHANGEDATE(date_range)

Lists the data sets whose last changed date matches the specified date criteria. The date criteria can be specified using the START and END suboperands. See the description of the SEARCHDATASET CRDATE operand for a description of how to use the START and END suboperands and examples of their use.

LASTPROGRAMNAME(full_or_generic_last_program_name)

Specifies data sets by the last referenced program name. A program name is one-to-eight alphanumeric characters, $, #, or @. The program name must start with an alphabetic character, $, #, or @. Use % in your generic program name mask to match any one character and * to match any character string in the program name. If you specify LASTPROGRAMNAME(*), DFSMSrmm returns all the data sets that have a last referenced program name. If you do not specify LASTPROGRAMNAME or NOLASTPROGRAMNAME, DFSMSrmm returns all data sets. LASTPROGRAMNAME is mutually exclusive with NOLASTPROGRAMNAME.

LASTREFDATE(date_range)

Lists the data sets based on both the last read date and last write date, using the most recent of both dates. The most recent of the two values within the date range for a data set to be selected. The date criteria can be specified using the START and END suboperands. See the description of the SEARCHDATASET CRDATE operand for a description of how to use the START and END suboperands and examples of their use.

LIMIT(search_limit)

Specifies how many entries DFSMSrmm lists. The maximum allowable decimal value is 9999. Specify an asterisk to request a list of all entries matching the search criteria.

The default value is 10.

LIST

Specifies that DFSMSrmm produce a list when the CLIST operand is used.

LIST is mutually exclusive with the NOLIST operand. LIST is the default.

MANAGEMENTCLASS(managementclass_name)

Specifies to limit the search to data sets with the specified management class name. A management class name is one-to-eight alphanumeric, national, or special characters. MANAGEMENTCLASS is mutually exclusive with NOMANAGEMENTCLASS.

NODATACLASS

Specifies to limit the search to data sets that do not have a data class. NODATACLASS is mutually exclusive with DATACLASS.

NOJOBNAME

Specifies data sets that do not have a job name. NOJOBNAME is mutually exclusive with JOBNAME.

NOLIST

Specifies that DFSMSrmm should neither produce a list nor set REXX variables for resources when the CLIST operand is used. DFSMSrmm produces only the CLIST output file.

NOLIST is mutually exclusive with the LIST operand. LIST is the default.

NOLASTPROGRAMNAME

Specifies to select data sets that do not have a last referenced program name. NOLASTPROGRAMNAME is mutually exclusive with LASTPROGRAMNAME.

NOMANAGEMENTCLASS

Specifies to limit the search to data sets that do not have a management class. NOMANAGEMENTCLASS is mutually exclusive with MANAGEMENTCLASS.

NOPROGRAMNAME

Specifies to limit the search to data sets that do not have a creating program name. NOPROGRAMNAME is mutually exclusive with PROGRAMNAME.

NOOEXPDT

Specifies to limit the search to data sets that do not have an original expiration date. NOOEXPDT is mutually exclusive with OEXPDT.

NOSTORAGECLASS

Specifies to limit the search to data sets that do not have a storage class. NOSTORAGECLASS is mutually exclusive with STORAGECLASS.

NOSTORAGEGROUP

Specifies to limit the search to data sets that do not have a storage group. NOSTORAGEGROUP is mutually exclusive with STORAGEGROUP.

OEXPDT(date)

Lists the data sets whose original expiration date matches the specified date.

If you use an *, DFSMSrmm returns dataset information for all data sets that have any original expiration date. OEXPDT is mutually exclusive with NOOEXPDT.

OWNER(owner)

Specifies to limit the search to volumes assigned to a specific owner ID. An owner ID is one-to-eight alphanumeric characters. The first character cannot be a number.

If you use an *, DFSMSrmm returns dataset information for all owners for data sets on both non-scratch and scratch volumes.

If you do not use the OWNER operand or you use a specific OWNER ID, DFSMSrmm returns data set information for data sets on non-scratch volumes only.

If you specify both the OWNER operand and the VOLUME operand of this subcommand, DFSMSrmm processes the last operand specified. If you do not specify OWNER or VOLUME, DFSMSrmm uses the user ID of the command issuer as the default OWNER ID.

The default is the ID of the command issuer.

PROGRAMNAME(full_or_generic_create_program_name)

Specifies the PROGRAMNAME operand to search for data sets with a creating program name recorded. DFSMSrmm records the name of the job step program running at the time the data set is opened for output. A program name is one-to-eight alphanumeric characters, $, #, or @. The program name must start with an alphabetic character, $, #, or @. Use % in your generic program name mask to match any one character and * to match any character string in the program name. If you specify PROGRAMNAME(*), DFSMSrmm returns all the data sets that have a program name. Use the NOPROGRAMNAME operand to search for data sets with no creating data set name recorded. If you do not specify PROGRAMNAME or NOPROGRAMNAME, DFSMSrmm returns all data sets. PROGRAMNAME is mutually exclusive with NOPROGRAMNAME.

READDATE(date_range)

Lists the data sets whose last read date matches the specified date criteria. The date criteria can be specified using the START and END suboperands. See the description of the SEARCHDATASET CRDATE operand for a description of how to use the START and END suboperands and examples of their use.

RETDATE(retention_date)

RETDATE specifies that DFSMSrmm lists only data sets that will expire up to and including the specified date. Data sets on scratch volumes are excluded. You can specify a specific date as RETDATE(retention_date). You can also specify the DFSMSrmm special date formats; CATRETPD, PERMANENT, WHILECATLG, or CYCL/nnnnn, where "nnnnn" is five numeric digits. When you specify one of the special dates, DFSMSrmm lists only those data sets that are VRS retained with that special retention date. When you specify the special cycles format date, CYCL/nnnnn, DFSMSrmm lists data sets that are VRS retained and have a cycles retention date and the same number or fewer cycles. For example; RETDATE(CYCL/00255) searches for all data sets with a retention date set to CYCL/00255 or lower, such as CYCL/00001. For data sets retained by a VRS DFSMSrmm uses the retention date. For data sets not retained by a vital record specification, DFSMSrmm uses the expiration date for the search. To obtain a list of data sets that have a permanent expiration date and that are not retained by vital record specifications, specify the expiration dates 1999/365 or 1999/366.

Supply the year and day in one of two forms. We recommend that you use the yyyy/ddd format rather than the yyddd format for dates.

• yyyy/ddd, where yyyy is the four-digit number for the year. The maximum allowable value for yyyy is 9799. ddd is the three-digit number for the day of the year, such as 2012/001. The slash is required.
• yyddd, where yy is the last two-digit number for the year and ddd is the three-digit number for the day of the year, such as 12001. When you use the yyddd format, DFSMSrmm determines the century by using a date window:
  • DFSMSrmm uses the current century if the difference between the current year and the specified year is not greater than 50.
  • DFSMSrmm uses the previous or next century if the difference between the current year and the specified year is greater than 50.

If you do not specify the RETDATE operand, DFSMSrmm searches all data sets, regardless of their retention date. See Defining retention policies for data sets and volumes for information about how DFSMSrmm calculates retention dates.

SINCE(create_date)

Returns a list of data sets that were created after the create date that you specify. Specify the year and day in the create date in one of two forms:

• yyyy/ddd, where yyyy is the four-digit number for the year. The maximum allowable value for yyyy is 9799. ddd is the three-digit number for the day of the year, such as 2012/001. The slash is required.
• yyddd, where yy is the last two-digit number for the year, and ddd is the three-digit number for the day of the year, such as 12001.

If you do not specify the SINCE parameter, DFSMSrmm considers all data sets regardless of the date when they were created.

SINCE is mutually exclusive with the CRDATE operand.

START

Requests that records written to the CLIST data set start from the beginning of the data set.

START is mutually exclusive with ADD.

START is the default value.

STATUS(SCRATCH | PRIVATE)

Specifies to limit the search to data sets residing on scratch or private volumes. Specify STATUS(SCRATCH) to search for data sets on scratch volumes that have no owner ID assigned to them. Specify STATUS(PRIVATE) to search for data sets on master and user volumes.

STORAGECLASS(storageclass_name)

Specifies to limit the search to data sets with the specified storage class name. A storage class name is one-to-eight alphanumeric, national, or special characters. STORAGECLASS is mutually exclusive with NOSTORAGECLASS.

STORAGEGROUP(storagegroup_name)

Specifies to limit the search to data sets with the specified storage group name. A storage group name is one-to-eight alphanumeric, national, or special characters. STORAGEGROUP is mutually exclusive with NOSTORAGEGROUP.

VITAL(YES | NO)

Specifies to limit the search to data sets that are retained by vital record specifications. If you do not specify this operand, retention by vital record specification is not part of the search criteria.

VOLUME(volume_serial)

Specifies to limit the search to data sets residing on the indicated volume. A volume serial is one-to-six alphanumeric, national, or special characters. Enclose it in single quotation marks if it contains any special characters.

If you do not specify a volume serial, DFSMSrmm considers all volumes.

If you specify both the VOLUME operand and the OWNER operand of this subcommand, DFSMSrmm processes the last operand specified. If you do not specify VOLUME or OWNER, DFSMSrmm uses the user ID of the command issuer as the default OWNER ID.

VRSELEXCLUDE(YES | NO)

Specifies to limit the search to data sets excluded (or not excluded) from VRSEL processing. Specify NO to search for data sets that are not excluded from VRSEL processing. Specify YES to search for data sets that are excluded from VRSEL processing. VRSELEXCLUDE can be abbreviated as VX.

WRITEDATE(date_range)

Lists the data sets whose last write date matches the specified date criteria. The date criteria can be specified using the START and END suboperands. See the description of the SEARCHDATASET CRDATE operand for a description of how to use the START and END suboperands and examples of their use.

  RMM SEARCHDATASET OWNER(OWN000) SINCE(91073) LIMIT(*)

Data set name                                Volume Owner    Create date Seq
 -------------------------------------------- ------ -------- ----------- ----
 DATA.SET.FIVE                                VOL001 OWN000   31/03/2002  1
 DATA.SET.FOUR                                VOL000 OWN000   21/03/2002  4
 DATA.SET.SEVEN                               VOL002 OWN000   16/03/2002  1
 DATA.SET.TWO                                 VOL000 OWN000   17/03/2002  2
 EDG3012I 4          ENTRIES LISTED

  RMM SEARCHDATASET VOLUME(VOL000) LIMIT(*)

Data set name                                Volume Owner    Create date Seq
 -------------------------------------------- ------ -------- ----------- ----
 DATA.SET.ONE                                 VOL000 OWN000   19/02/2002  1
 DATA.SET.TWO                                 VOL000 OWN000   01/03/2002  2
 DATA.SET.THREE                               VOL000 OWN000   09/02/2002  3
 DATA.SET.FOUR                                VOL000 OWN000   21/03/2002  4
 EDG3012I 4          ENTRIES LISTED

  RMM SEARCHDATASET FILESEQ(1) OWNER(OWN000) LIMIT(*)

Data set name                                Volume Owner    Create date Seq
 -------------------------------------------- ------ -------- ----------- ----
 DATA.SET.FIVE                                VOL001 OWN000   31/03/2002  1
 DATA.SET.ONE                                 VOL000 OWN000   19/02/2002  1
 DATA.SET.SEVEN                               VOL002 OWN000   11/03/2002  1
 EDG3012I 3          ENTRIES LISTED

  RMM SEARCHDATASET DSNAME(*) OWNER(WOODY) LIMIT(*) -
       CLIST('RMM LD ')

Data set name                                Volume Owner    Create date Seq
 -------------------------------------------- ------ -------- ----------- ----
 RMML01.SYSRES.BACKUP                         999000 WOODY    26/02/2002  1
 RMML01.SYSRES.BACKUP                         999001 WOODY    26/02/2002  1
 RMML01.SYSRES.BACKUP                         999002 WOODY    26/02/2002  1
 RMML01.SYSRES.BACKUP                         999003 WOODY    26/02/2002  1
 RMML01.SYSRES.BACKUP                         999004 WOODY    26/02/2002  1
 EDG3012I 5          ENTRIES LISTED

DFSMSrmm also creates a CLIST data set containing the records shown in Figure 5:

 RMM LD 'RMML01.SYSRES.BACKUP' VOL(999000) FILESEQ(01)
 RMM LD 'RMML01.SYSRES.BACKUP' VOL(999001) FILESEQ(01)
 RMM LD 'RMML01.SYSRES.BACKUP' VOL(999002) FILESEQ(01)
 RMM LD 'RMML01.SYSRES.BACKUP' VOL(999003) FILESEQ(01)
 RMM LD 'RMML01.SYSRES.BACKUP' VOL(999004) FILESEQ(01)

Return codes

See DFSMSrmm return codes and reason codes for DFSMSrmm reason codes.

0

Subcommand completed normally.

4

Warning. Subcommand completed but some operands could have been ignored or modified. DFSMSrmm sets a reason code.

8

User not authorized.

12

Subcommand ended with an error. DFSMSrmm sets a reason code.

16

Error. The DFSMSrmm subsystem is not active.

20

Error. The data is incomplete or incorrect and the TSO user has set NOPROMPT.

24

The TSO subcommand is not APF authorized.

28

The user pressed the attention key.