A catalog is a special type of file in a WPS Analytics library. It can contain source code, data, logs, other entities resulting from the execution of WPS Analytics, and other elements or items of the SAS language.
Specifying elements within a catalog
A catalog is stored in a library, and consists of a collection of catalog entries. A catalog entry has a particular type, which identifies the kinds of entities stored in the catalog; for example, you can store source code as a source entry type, and log files as a log entry type. There are many entry types; these are not all listed in this blog.
A catalog is specified using a four-level library reference:
- libname is the name of a library. Catalogs, like datasets, are members of a library.
- catname is the name of a catalog.
- entryname is the name of a member of the catalog; a member can be a program, data, a log, an FCMP routine, and so on.
- entrytype is the type of entry. The type is a container for entries of the same type. For example, log files can be written into the catalog, and you can identify these with the entry type log.
A catalog is created when the first entry is written to it. Once the catalog has been created, other entries can be written to it. The entry name and entry type uniquely identify the entry. The entry myent.source is different to myent.log and mynet.source. When you want to access an entry, the entry name and entry type must match exactly.
A catalog can be read and written to using the FILENAME CATALOG access method. A catalog can be edited using the CATALOG procedure.
Note: As catalogs have developed in WPS Analytics, they have been assigned version numbers. For WPS Analytics 4.2, the catalog version is 3. You can only open version 3 catalogs from WPS version 4.2 and later; you cannot open this version of the catalog in earlier versions of WPS.
Getting information into a catalog
You can put information into a catalog in various ways, depending on the element you are adding. For example, you can:
- Use one or more PUT statements to write a program into the catalog.
- Direct the output of a procedure to a catalog.
- Use the /STORE option on the %MACRO statement. This stores the compiled form of the macro in the catalog SASMACR in a specified library. (If you wanted to write the source of the macro into a catalog, you would write the statements required using PUT).
The element type might be defined by the method you use to write to the catalog. For example, if you use the FORMAT procedure to create user-defined formats, and save these in a catalog, the type is defined as format by default. Similarly, if you create a stored compiled macro using /STORE, this is stored as the type macro by default.
For example, the following program writes a DATA step to the catalog:
LIBNAME tdir 'c:\temp'; FILENAME tct catalog 'tdir.tcat.tadd.source'; DATA _NULL_; FILE tct; PUT 'DATA _NULL_;'; PUT 'x + 3;'; PUT 'PUT x=;'; PUT 'RUN;'; RUN;
The FILENAME statement specifies the catalog entry. CATALOG is the access method used to define and access a catalog; the catalog, the entry and the type are then defined in the quoted string. The library reference must be defined before the FILENAME statement. In this example, tdir in the catalog definition has already been specified with LIBNAME statement. The program uses PUT statements to write each line of the program into the catalog. The entry type is specified as source.
When you run a program from a catalog, the type of element you specify must match the type of element in the catalog. For example, instead of writing the above program to temp.tcat.tadd.source, you could write it to temp.tcat.bertcds.log; however, when you run the program from the catalog as described below, you would need to specify the type as log.
Getting information out of a catalog
How you retrieve information from a catalog depends on the type of catalog entry, and what you want to do with the entry. For example, some procedures enable you to specify a catalog entry as the source of input data; some statements (such as %INCLUDE) enable you to specify a catalog entry, so you can run program statements saved in a catalog; and you can specify a catalog entry on the INFILE statement, enabling you to read each line in the catalog entry as an input record.
To run source code contained in a catalog, you can use the %INCLUDE statement. To run the program created and stored in a catalog in the example above:
LIBNAME temp 'c:\temp'; FILE prun catalog 'temp.tcat'; %INCLUDE prun(tadd.source);
This specifies only the catalog name to the filename reference prun. The %INCLUDE statement includes the specified entry and type of the entry. By running programs this way, you could run source stored in many catalog entries using the same filename reference:
%INCLUDE prun(tadd.source); %INCLUDE prun(tadd2.source); %INCLUDE prun(tmult.source);
You could also specify the full catalog entry for the program:
filename prun catalog "temp.tcat.tadd.source"; %include prun;
You could retrieve a log from a catalog by reading the catalog as a file and inputting each line as a record. You could then write the log to a dataset, or write it to the current log. For example:
LIBNAME tdir 'c:\temp'; FILENAME catmc CATALOG 'tdir.tcat.olog.log'; DATA logout; INFILE catmc; INPUT a $1-80; PUT '** ' a; RUN;
This writes the following to the log:
** real time : 0.003 ** ** 6 ** 8 contents catalog = temp.tcat; ** NOTE: Procedure catalog step took : ** cpu time : 0.000 ** ** 11 proc printto;
Each line of the retrieved log is also written to the dataset logout as an observation.
Catalogs are not transportable between platforms (that is, operating systems, devices, or both). You can only use catalogs on the platform on which they were created. The system options that were set when the catalog was created should also be set when the catalog is used. For example, if the ENCODING system option is not set to the same value as when the catalog was created, code points stored in the catalog might not be transcoded correctly.