CATNAME Statement

Logically combines two or more catalogs into one by associating them with a catref (a shortcut name ); clears one or all catrefs; lists the concatenated catalogs in one concatenation or in all concatenations

Valid: Anywhere

Category: Data Access

Syntax

1 CATNAME < libref. > catref

< (libref-1.catalog-1 <(ACCESS=READONLY)>
< libref-n.catalog-n <(ACCESS=READONLY)>)> ;
2 CATNAME < libref. > catref CLEAR _ALL_ CLEAR;
3 CATNAME < libref. > catref LIST _ALL_ LIST;

Arguments

libref

is any previously assigned SAS libref. If you do not specify a libref, SAS concatenates the catalog in the Work library, using the catref that you specify.

Restriction: The libref must have been previously assigned.

catref

is a unique catalog reference name for a catalog or a catalog concatenation that is specified in the statement. Separate the catref from the libref with a period, as in libref.catref . Any SAS name can be used for this catref.

catalog

is the name of a catalog that is available for use in the catalog concatenation.

Options

CLEAR

disassociates a currently assigned catref or libref.catref .
Tip: Specify a specific catref or libref.catref to disassociate it from a single concatenation. Specify _ALL_ CLEAR to disassociate all currently assigned catref or libref.catref concatenations.

_ALL_ CLEAR

disassociates all currently assigned catref or libref.catref concatenations.

LIST

writes the catalog names that are included in the specified concatenation to the SAS log.
Tip: Specify catref or libref.catref to list the attributes of a single concatenation. Specify _ALL_ to list the attributes of all catalog concatenations in your current session.

_ALL_ LIST

writes all catalog names that are included in any current catalog concatenation to the SAS log.

ACCESS=READONLY

assigns a read-only attribute to the catalog. SAS, therefore, will allow users to read from the catalog entries but not to update information or to write new information.

Details

Why Use CATNAME? CATNAME is useful because it enables you to access entries in multiple catalogs by specifying a single catalog reference name ( libref.catref or catref ).

After you create a catalog concatenation, you can specify the catref in any context that accepts a simple (non-concatenated) catref.

Rules for Catalog Concatenation To use catalog concatenation effectively, you must understand the rules that determine how catalog entries are located among the concatenated catalogs:

When a catalog entry is opened for input or update, the concatenated catalogs are searched and the first occurrence of the specified entry is used.
When a catalog entry is opened for output, it will be created in the first catalog that is listed in the concatenation.

Note: A new catalog entry is created in the first catalog even if there is an entry with the same name in another part of the concatenation.

Note: If the first catalog in a concatenation that is opened for update does not exist, the item will be written to the next catalog that exists in the concatenation.
When you want to delete or rename a catalog entry, only the first occurrence of the entry is affected.
Any time a list of catalog entries is displayed, only one occurrence of a catalog entry name is shown.

Note: Even if the name occurs multiple times in the concatenation, only the first occurrence is shown.

Comparisons

The CATNAME statement is like a LIBNAME statement for catalogs. The LIBNAME statement allows you to assign a shortcut name to a SAS data library so that you can use the shortcut name to find the files and use the data they contain. CATNAME allows you to assign a short name <libref.>catref (libref is optional) to one or more catalogs so that SAS can find the catalogs and use all or some of the entries in each catalog.
The CATNAME statement explicitly concatenates SAS catalogs. You can use the LIBNAME statement to implicitly concatenate SAS catalogs.

Examples

Example 1: Assigning and Using a Catalog Concatenation

You might need to access entries in several SAS catalogs. The most efficient way to access the information is to logically concatenate the catalogs. This enables access to the information without actually creating a new, separate, and possibly very large catalog.

Assign librefs to the SAS data libraries that contain the catalogs that you want to concatenate:

 libname mylib1 '  data-library-1  ';  libname mylib2 '  data-library-2  ';

Assign a catref, which can be any valid SAS name, to the list of catalogs that you want to logically concatenate:

 catname allcats (mylib1.catalog1 mylib2.catalog2);

The SAS log displays this message:

Output 7.3: Log Output from CATNAME Statement

 NOTE: Catalog concatenation WORK.ALLCATS has been created.

Because no libref is specified, the libref is WORK by default. When you want to access a catalog entry in either of these catalogs, use the libref WORK and the catalog reference name ALLCATS instead of the original librefs and catalog names. For example, to access a catalog entry named APPKEYS.KEYS in the catalog MYLIB1.CATALOG1, specify

 work.allcats.appkeys.keys

Example 2: Creating a Nested Catalog Concatenation

After you create a concatenated catalog, you can use CATNAME to combine your concatenation with other single catalogs or other concatenated catalogs. This is useful, because you can use a single catref to access many different catalog combinations.

 libname local 'my_dir';  libname main  'public_dir';  catname private_catalog (local.my_application_code                           local.my_frames                           local.my_formats);  catname combined_catalogs (private_catalog                           main.public_catalog);

In the above example, you could work on private copies of your application entries by using PRIVATE_CATALOG. If you want to see how your entries function when they are combined with the public version of the application, you can use COMBINED_CATALOGS.

CATNAME Statement