SEARCH (Search RACF database)

Purpose

You can display the selected profile names at your terminal.

You can also format the selected profile names with specific character strings into a series of commands or messages and retain them in a CLIST data set.

Restriction: When searching profiles in the IDIDMAP class, you cannot use the FILTER or MASK option to limit the results of the search. This is because IDIDMAP profile names are stored in UTF-8 format and are translated to EBCDIC for use with the SEARCH command.

Issuing options

For information on issuing this command as a RACF TSO command, refer to RACF TSO commands.

For information on issuing this command as a RACF operator command, refer to RACF operator commands.

You must be logged on to the console to issue this command as a RACF operator command.

Related commands

• To obtain information on general resource profiles, see RLIST (List general resource profile).
• To display a data set profile, see LISTDSD (List data set profile).
• To display a user profile, see LISTUSER (List user profile).
• To display a group profile, see LISTGRP (List group profile).

Authorization required

When issuing this command as a RACF operator command, you might require sufficient authority to the proper resource in the OPERCMDS class. For details about OPERCMDS resources, see "Controlling the use of operator commands" in z/OS Security Server RACF Security Administrator's Guide.

In addition to one of the other four conditions, RACF also checks your security level and categories against those in the specified user profile.

To specify the AT keyword, you must have READ authority to the DIRECT.node resource in the RRSFDATA class and a user ID association must be established between the specified node.userid pair(s).

To specify the ONLYAT keyword you must have the SPECIAL attribute, the userid specified on the ONLYAT keyword must have the SPECIAL attribute, and a user ID association must be established between the specified node.userid pair(s) if the user IDs are not identical.

Note that it is the authority of the user ID specified on the USER operand that is used to determine if SEARCH displays the profile name.

No authorization is required to the user or group profiles that are listed when the UID or GID keyword is specified.

Inactive SECLABEL profiles and profiles that contain inactive security labels may not be listed if SETROPTS SECLBYSYSTEM is active because only users with SPECIAL, AUDITOR or ROAUDIT authority are allowed to view inactive security labels.

Parameters

subsystem-prefix

Specifies that the RACF subsystem is the processing environment of the command. The subsystem prefix can be either the installation-defined prefix for RACF (1 - 8 characters) or, if no prefix has been defined, the RACF subsystem name followed by a blank. If the command prefix was registered with CPF, you can use the MVS command D OPDATA to display it or you can contact your RACF security administrator.

Only specify the subsystem prefix when issuing this command as a RACF operator command. The subsystem prefix is required when issuing RACF operator commands.

AGE(number-of-days)

Specifies the aging factor to be used as part of the search criteria.

Note: This operand works only for discrete profiles and requires that STATISTICS is enabled system-wide.

Only resources that have not been referenced within the specified number of days are selected, unless you specify CLASS(GROUP). In this case, the SEARCH command uses the date on which the group was defined to determine the age.

You can specify up to five digits for number-of-days.

ALL | GENERIC | NOGENERIC | MODEL | TAPE | VSAM | NONVSAM

ALL

Specifies that RACF is to select all data set profiles (tape, VSAM, and non-VSAM DASD) including both generic and discrete profiles. RACF ignores this operand for classes other than DATASET. ALL is the default if you omit VSAM, NONVSAM, TAPE, GENERIC, NOGENERIC, MODEL, and ALL.

GENERIC

Specifies that only generic profiles are to be selected. If neither GENERIC nor NOGENERIC is specified, both profile types are selected. RACF ignores this operand unless generic profile command processing is enabled.

RACF ignores this operand unless generic profile command processing is enabled.

NOGENERIC

Specifies that no generic profiles (that is, only discrete profiles) are to be selected. If neither GENERIC nor NOGENERIC is specified, both profile types are selected.

RACF ignores this operand unless generic profile command processing is enabled.

MODEL

Specifies that only data set profiles having the MODEL attribute are to be selected. RACF ignores this operand for classes other than DATASET.

TAPE

Specifies that only tape data sets are to be selected. RACF ignores this operand for classes other than DATASET.

VSAM

Specifies that only VSAM data sets are to be selected. RACF ignores this operand for classes other than DATASET.

NONVSAM

Specifies that only non-VSAM data sets are to be selected. RACF ignores this operand for classes other than DATASET.

AT | ONLYAT

The AT and ONLYAT keywords are only valid when the command is issued as a RACF TSO command.

AT([node].userid ...)

Specifies that the command is to be directed to the node specified by node, where it runs under the authority of the user specified by userid in the RACF subsystem address space.

If node is not specified, the command is directed to the local node.

Note: The SEARCH command is not eligible for command direction when the CLIST keyword is specified. Do not specify the AT and CLIST keywords together on a SEARCH command.

ONLYAT([node].userid ...)

SEARCH is not eligible for automatic command direction. If you specify the ONLYAT keyword, the effect is the same as if you specified the AT keyword.

CATEGORY | EXPIRES | LEVEL | SECLEVEL | SECLABEL | WARNING

CATEGORY[(category-name)]

Specifies that RACF is to select only profiles with an access category matching the category name that you specify, where category-name is an installation-defined name that is a member of the CATEGORY profile in the SECDATA class. If you specify CATEGORY and omit category-name, RACF selects only profiles that contain undefined access category names (names that were once known to RACF but that are no longer valid).

RACF ignores this operand when CLASS(GROUP) is specified.

EXPIRES(number-of-days)

Specifies that RACF is to select only tape volumes on which all of the data sets either have expired or will expire within the number of days that you specify. The variable number-of-days is a number of 1 - 5 digits in length in the range of 0 - 65533. For data sets that never expire, use 99999. RACF ignores this operand for classes other than TAPEVOL.

LEVEL(level-number)

Specifies that RACF is to select only profiles with an installation-defined level that equals the level number you specify. You can specify a value for level of 0 - 99.

RACF ignores this operand for classes other than DATASET or classes defined in the RACF class descriptor table.

SECLABEL[(seclabel-name)]

Specifies that RACF is to select only profiles with a security label name that matches the value you specify for seclabel.

SECLEVEL[(seclevel-name)]

Specifies that RACF is to select only profiles with a security level name that matches seclevel-name, where seclevel-name is an installation-defined name that is a member of the SECLEVEL profile in the SECDATA class. If you specify SECLEVEL and omit seclevel-name, RACF selects only profiles that contain undefined security level names (names that were once known to RACF but that are no longer valid).

RACF ignores this operand when you specify CLASS(GROUP).

WARNING

Specifies that only resources with the WARNING indicator are to be selected.

RACF ignores this operand when you specify CLASS as USER or GROUP.

CLASS(DATASET | class-name)

Specifies the name of the class of profiles to be searched. The valid resource classes are DATASET, USER, GROUP, and those specified in the class descriptor table. For a list of general resource classes defined in the class descriptor table supplied by IBM®, see Supplied RACF resource classes.

If you omit this operand, the default value is DATASET.

To search all RACF-defined user profiles, you must have either the SPECIAL, AUDITOR, or ROAUDIT, attribute.

SEARCH CLASS(USER) can be issued to obtain information about the irrcerta and irrsitec user IDs, which are the user IDs used by RACF to anchor digital certificates.

When searching with the CLASS(GROUP) option, groups are listed based upon the connect authority of the user, not READ or higher access to the profile. If CLASS(TAPEVOL) is specified, RACF processes all volumes that meet the search criteria independently, even if the volumes belong to a tape volume set.

CLIST[('string-1 '[' string-2'] )]

Specifies that the selected profile names are to be retained in a CLIST data set. One record is put into the data set for each selected profile name.

Profile names containing ampersands (&) appear in the CLIST data set with each occurrence of an ampersand (&) doubled (&&). When the CLIST is executed, double ampersands (&&) prevent the CLIST from performing symbolic substitution when encountering a variable. The CLIST removes only the first ampersand, leaving the second ampersand intact.

'string-1 '[' string-2']

Specifies strings of alphanumeric characters that are put into the CLIST records along with the selected profile names. Each string must be enclosed in single quotation marks. In this way, you can build a set of commands that are similar except for the profile name.

Mixed-case strings are always accepted and preserved for the CLIST operand. If string-1 is specified, the resulting output CLIST will contain a CONTROL ASIS statement.

The format of the text portion of the CLIST record is as follows:

string-1'data-set name'string-2 or
string-1volume-serial-numberstring-2 or
string-1terminal-namestring-2

Guideline: No blank is inserted after string-1 or before string-2. To ensure that the commands execute correctly, use a blank character as the last character in string-1 and the first character in string-2. For example, specify:

CLIST('DELDSD '' SET')

rather than:

CLIST('DELDSD''SET')

An 8-position sequence number is placed on the front of the text.

If both strings are missing, the CLIST record contains only the profile name. If you want a string of data to appear only after the resource name, specify string-1 as a double-quotation mark (").

The DASD data set name for the CLIST data set is generated in the format:

'prefix.EXEC.RACF.CLIST'

where prefix is the default data set name prefix in your TSO profile. If you do not have a prefix specified in your TSO profile, (PROFILE NOPREFIX), the user ID from the SEARCH command issuer's ACEE is used as the qualifying prefix.

If this data set is partitioned rather than sequential, the CLIST records are placed in member TEMPNAME of the data set. In either case, you can execute the CLIST after SEARCH has finished by issuing the TSO/E command:

EXEC 'prefix.EXEC.RACF.CLIST'

If a CLIST data set is found through the catalog and is a sequential data set, the records it contains are replaced with the new records. If the CLIST data set is a partitioned data set, however, member TEMPNAME is created to hold the new records, or is replaced if the member already exists.

If the CLIST data set does not already exist, it is created and cataloged. If the CLIST data set created is a partitioned data set, member TEMPNAME is created.

The CLIST data set must have variable length records and a maximum logical record size of 255. This includes a 4-byte length field at the front of the record. The records are numbered in sequence by 10.

Note: The SEARCH command is not eligible for command direction when the CLIST keyword is specified. Do not specify the AT and CLIST keywords together on a SEARCH command.

FILTER(filter-string)

(Also see the MASK operand.)

Specifies the string of alphanumeric characters used to search the RACF database. The filter string defines the range of profile names you want to select from the RACF database. For a tape or DASD data set name, the filter string length must not exceed 44 characters. For a general resource class, the filter string length must not exceed the length of the profile name specified in the class descriptor table.

Mixed-case strings are accepted and preserved when CLASS refers to a class defined in the static class descriptor table with CASE=ASIS or in the dynamic class descriptor table with CASE(ASIS).

When you issue the SEARCH command with the FILTER operand, RACF lists profile names from the RACF database matching the search criteria specified in the filter string. Note that RACF lists only those profile names that you are authorized to see.

The following generic characters have special meaning when used as part of the filter string:

%

You can use the percent sign to represent any one character in the profile name, including a generic character. For example, if you specify DASD%% as a filter string, it can represent profile names such as DASD01, DASD2A, and DASD%5. If you specify %%%%% as a filter string, it can represent profile names DASD1, DASD2, DASD%, TAPE%, MY%%%, TAPE*, and %%%%*.

*

You can use a single asterisk to represent zero or more characters in a qualifier, including generic characters. For example, AB*.CD can represent data set profile names such as AB.CD, ABEF.CD, and ABX.CD. ABC.D* can represent data set profile names such as ABC.DEFG, ABC.D%%%, and ABC.D%*. If you specify a single asterisk as the only character in a qualifier, it represents the entire qualifier. For example, ABC.* represents data set profile names such as ABC.D, ABC.DEF, ABC.%%%, and ABC.%DE.

**

For general resource and data set profile names, you can use a double asterisk to represent zero or more qualifiers in the profile name. For example, AB.**.CD represents data set profile names such as AB.CD, AB.DE.EF.CD, and AB.XYZ.CD. You cannot specify other characters with ** within a qualifier. (For example, you can specify FILTER(USER1.**), but not FILTER(USER1.A**). You can also specify ** as the only characters in the filter-string to represent any entire profile name.

Tip: Use FILTER for an alternative to MASK | NOMASK as a method for searching the RACF database. FILTER offers more flexibility than MASK. For example, when you use FILTER, you can generalize the character string you specify to match multiple qualifiers or multiple characters within a profile name. You can also specify a character string to match a single character regardless of its value or search for a character string anywhere in a profile name.

Restrictions:

• The SEARCH command might provide unpredictable results when searching on the DIGTCERT or DIGTRING classes. Because these classes contains names with mixed-case characters, the profile filter on the SEARCH command might not function correctly.
• You cannot use a generic character (*, **, or %) in the high-level qualifier when you define a generic profile for a data set. However, you can use a generic character in the high-level qualifier of a data set name when specifying a filter-string with the FILTER operand.
• The FILTER and MASK | NOMASK operands are mutually exclusive; you cannot specify FILTER with either MASK or NOMASK on the same SEARCH command.
• When searching profiles in the IDIDMAP class, you cannot use FILTER to limit the results of the search. This is because IDIDMAP profile names are stored in UTF-8 format and are translated to EBCDIC for use with the SEARCH command.

GID (group-identifier)

Specifies that RACF is to display all group profiles which contain the specified group-identifier for the GID in the OMVS segment. GID is ignored unless CLASS(GROUP) is specified. When GID is specified, all other keywords (except CLASS) are ignored.

LIST | NOLIST

LIST

Specifies that the selected data set names, volume serial numbers, or terminal names are to be displayed at your terminal. LIST is the default value when you omit both LIST and NOLIST.

NOLIST

Specifies that the selected data set names, volume serial numbers, or terminal names are not to be displayed at your terminal. You can use this operand only when you specify the CLIST operand. If you use NOLIST without CLIST, the command fails.

MASK | NOMASK

MASK(char-1 | * [char-2])

(Also see the FILTER operand.)

Specifies the strings of alphanumeric characters used to search the RACF database. This data defines the range of profile names selected. The two character strings together must not exceed 44 characters for a tape or DASD data set name, or, for general resource classes, the length specified in the class descriptor table.

char-1

Specifies the starting characters of names of profiles to be searched. The string can be any length up to the maximum allowable length of the resource name. All profiles that start with char-1 in their resource names are selected.

If an asterisk (*) is specified for char-1, it specifies that profiles of the search criteria are to be selected:

• For DATASET class, your user ID is used as the mask for the profiles to be selected.
• For other classes, all profiles of the specified class are selected.

char-2

Specifies a second string of characters to be included in the search for profiles. All profiles whose names start with char-1 and contain char-2 anywhere beyond char-1 are selected. This limits the list to a subset of the resource names identified with char-1.

If an asterisk (*) is specified instead of char-1, all profiles that contain char-2 anywhere in their resource names are selected.

If you omit both the MASK and NOMASK operands, this is the same as specifying MASK(*): for the DATASET class, your user ID is used as the mask for profiles to be selected; for other classes, all profiles of the class are selected. (Note also that for classes other than DATASET, omitting both operands is the same as NOMASK.)

Mixed-case strings are accepted and preserved when CLASS refers to a class defined in the static class descriptor table with CASE=ASIS or in the dynamic class descriptor table with CASE(ASIS).

Restriction: When searching profiles in the IDIDMAP class, you cannot use MASK to limit the results of the search. This is because IDIDMAP profile names are stored in UTF-8 format and are translated to EBCDIC for use with the SEARCH command.

NOMASK

Specifies that RACF is to select all profiles (to which you are authorized) in the specified class.

Note: The MASK | NOMASK and FILTER operands are mutually exclusive. You cannot specify MASK or NOMASK with FILTER on the same SEARCH command.

UID(user-identifier)

Specifies that RACF is to display all user profiles which contain the specified user-identifier for the UID in the OMVS segment. UID is ignored unless CLASS(USER) is specified. When UID is specified, all other keywords (except CLASS) are ignored.

USER(userid)

Specifies that RACF is to list the profiles that the specified user has access to (READ authority or higher, or owner) for the class you specify on the CLASS operand. RACF lists only those profiles that the specified owner is allowed to see.

If you issue:

SEARCH USER(JONES) CLASS(ACCTNUM)

RACF lists all TSO account numbers that user ID JONES is allowed to use.

If you issue:

SEARCH USER(JONES) NOMASK

RACF lists profiles in the DATASET class that JONES has access to.

If you issue:

SEARCH USER(JONES) CLASS(GROUP)

RACF lists all groups that user ID JONES owns or, in which JONES has JOIN or CONNECT authority or the group-SPECIAL attribute.

Note:

1. If you omit the CLASS operand, the default class is DATASET. For more information, see the description of the CLASS operand.
2. You should not specify a user ID that has been revoked. If you need to display information about a user whose user ID is revoked, perform the following steps:
   1. Change the password for the user ID.
   2. Resume the user ID.
   3. Issue the SEARCH command to display the desired information.
   4. Revoke the user ID.
3. You can only specify one user ID at a time on the USER operand. If you need to display information about all users, first create a CLIST by issuing the following command:

   SEARCH CLASS(USER) CLIST('SEARCH USER(' ') CLASS(class-name)')

   After you create a CLIST, issue:

   EXEC 'prefix.EXEC.RACF.CLIST'

   to display the desired information. (Note that prefix is the default data set name prefix in your TSO profile.) For more information, see the description of the CLIST operand.

VOLUME

Specifies that you want RACF to display volume information for each tape or DASD data set that meets the search criteria specified by the MASK or FILTER operand.

RACF ignores this operand if you specify GENERIC.

For non-VSAM data sets, the volume serial number displayed is the location of the data set. For VSAM data sets, the volume serial number displayed is the location of the catalog entry for the data set. For tape data sets, the volume serial number displayed is the location of the TVTOC entry for the data set.

This operand is valid only for CLASS(DATASET). RACF ignores it for all other class values.

VOLUME(volume-serial ...)

Specifies the volumes to be searched; the volume serial numbers become part of the search criteria. Non-VSAM DASD data sets are selected if they reside on the specified volumes. VSAM data sets are selected if the catalog entries for the data sets reside on the specified volumes. Tape data sets are selected if the TVTOC entries for the data set reside on the specified volumes.

RACF ignores this operand if you specify GENERIC.

If the selected data set names are displayed at your terminal, the volume information is included with each data set name.

This operand is valid only for CLASS(DATASET). RACF ignores it for all other class values.