If you can access your format catalog from your current operating system, this note explains how to migrate it to another operating environment.
The most robust method available for migrating user-defined format libraries is the FORMAT procedure with the CNTLOUT= and CNTLIN= options. With this method, all the information that you need to re-create a format library is written out to a SAS data set. The SAS data set is called a control data set. The data set can be accessed from a shared drive or transferred to the receiving site as a binary file where the process is reversed. The format catalog is re-created by using PROC FORMAT and the CNTLIN= option.
When you use the CNTLOUT= option to create a transport file (see Example 1 below) or a SAS data set (.sas7bdat) (see Example 2 below), you must start where the catalog is native. The catalog must be on the system where the catalog was created. If you get the following error, it means that the catalog is foreign to your operating system:
ERROR: File FORMATS.CATALOG was created for a different operating system.
To determine which operating system created the catalog, run the SAS code in SAS Note 34443, "Determine the operating system and SAS® release in which a catalog was created."
The advantages of using PROC FORMAT to move format catalogs are as follows:
- The sending and receiving systems do not have to use the same character set. The formats are created anew by using the information that is stored in the control data set. Therefore, later uses of the formats will be done using a binary search.
- Your format catalog can be used in a different release or an earlier version of SAS.
- The target system can be running SAS in an entirely different operating system than the one in which the catalog was created.
The following example uses the XPORT engine to create a control data set in transport format. You can use this method to migrate a format catalog back to earlier releases of SAS across operating systems. If you use the XPORT transport format, you must ensure that the format catalog does not have a name greater than eight characters or use value labels greater than 200 characters. If this is not the case, use the code in Example 2 instead.
Example 1. Use PROC FORMAT with CNTLOUT= to create a transport file
/* Set up a SAS library reference named library */
libname library 'location-of-existing-formats catalog';
/* Set up a file reference for the transport file */
libname trans xport 'transport-file-name';
/* Write all the format entries in the format library to CNTLFMT data set and store in transport format */
proc format library=library cntlout=trans.cntlfmt;
Note: CNTLFMT can be any valid SAS data set name. As with any transport file in SAS, the file must be created with the appropriate DCB file attributes (SAS Note 22688) if the operating system is z/OS. Also, the file must be moved using a binary or image transfer when being moved from site to site.
After moving the XPORT transport file to the receiving site, the following code regenerates the format library from the transport file:
/* The SAS library reference points to an empty directory where you want to store the new format catalog */
libname library 'output-library-for-format-storage';
/* The trans fileref points to the transport file you created above and should include the extension if there is one */
libname trans xport 'transport-file-name-from-sending-site';
/* Read the transport file and write out a native format catalog to the library libref */
proc format library=library cntlin=trans.cntlfmt;
Note: CNTLFMT is the same name that was used with the CNTLOUT= option at data set creation time
Example 2. Use PROC FORMAT with CNTLOUT= to create a SAS data set
libname library 'location-of-existing-formats-catalog';
libname out 'path-to-directory';
proc format library=library cntlout=out.cntlfmt;
SAS appends the extension .sas7bdat to the output file. After you move the .sas7bdat file to the receiving site (be sure to specify a binary transfer), use the following code to regenerate the format library:
libname library 'output-library-for-format-storage';
libname in 'data-set-name-from-sending-site';
proc format library=library cntlin=in.cntlfmt;
Note: CNTLFMT is the same name that was used with the CNTLOUT= option at data set creation time.
When searching for a format or informat, SAS always searches in WORK.FORMATS first, and then LIBRARY.FORMATS, unless one of them appears in the FMTSEARCH= list. SAS searches the catalogs in the FMTSEARCH= list in the order in which they are listed until the format or informat is found. For more details about PROC FORMAT options, refer to the section about the FORMAT procedure in the Base SAS Procedures Guide.