Migration

Migrating a Library with Validation Tools

When you run PROC MIGRATE with validation tools, you generate Output Delivery System (ODS) reports that validate a successful migration.

The validation tools augment a basic COMPARE procedure by performing a smart compare between source and target libraries.

Start here

Determine whether you need simplest-case migration or Remote Library Services (RLS) migration. If you're not certain, use the PROC MIGRATE Calculator.
Choose one of the following three ways of using validation tools. This documentation provides downloads of the validation macros and example PROC MIGRATE templates that you customize for your environment.
If you have questions about the process, see Details about Migrating with Validation Tools.
Review the reports. If you have questions about the reports, see Results of Migrating with Validation Tools.

About mixed libraries

An engine assignment in the source LIBNAME statement is required if you have a mixed library, such as a library whose members were created in different releases of SAS (for example, SAS 6 and SAS 8). The engine assignment specifies which version members you want to migrate from the source library. You must repeat the process for each version your library contains.

Using Validation Tools with Simplest-Case Migration

These steps explain how to modify the migrate_template.sas tool to fit your site's needs. The migrate_template.sas example code is only appropriate for migrating on the same computer without the use of SAS/CONNECT or SAS/SHARE server. If you are using RLS with your migration, then see Using Validation Tools with RLS instead. If you're not sure whether these instructions are appropriate for your site, use the interactive PROC MIGRATE Calculator first.

To compile the macros, copy and paste the text in the migrate_macros.sas (.txt file) tool into an interactive SAS session and submit it.
Copy and paste the text in the migrate_template.sas (.txt file) example code into an interactive SAS session. Modify the example code to define the source library, the target library, and the library to contain ODS output data sets:
```
libname lib1 <engine> 'path to source library';
libname lib2  base    'path to target library';
libname ods           'path used by the tools';
```
The ODS library should be distinct from the source and target libraries. The optional engine assignment in the first LIBNAME statement is required if you have a mixed library (for example, a library that contains SAS 6 and SAS 8 members). The engine assignment in the first LIBNAME statement specifies which version members you want to migrate. In this case, you must repeat the process for each version your library contains.
Modify the PROC MIGRATE step in the example code with the appropriate options:
```
proc migrate in=lib1 out=lib2 <options>;
run;
```
For detailed information about the options, see the Options section for PROC MIGRATE.
Submit the code.

Using Validation Tools with Remote Library Services (RLS) from SAS 8 to SAS 9

These steps explain how to modify the migrate_RLStemplate.sas example code to fit your site's needs. The migrate_RLStemplate.sas example code is only appropriate for a migration that uses RLS. If you are not using RLS with your migration, then see Using Validation Tools with Simplest-Case Migration instead. If you're not sure whether these instructions are appropriate for your site, use the interactive PROC MIGRATE Calculator first.

Requirements

This code is submitted in a SAS 9 session, but you must have access to a SAS 8 SAS/CONNECT server. If your source library members were created under 32-bit SAS 8, then the SAS/CONNECT server must be running under 32-bit SAS 8. (You could also use SAS/SHARE, but the syntax would be different than the example code.)
The source library must be directly accessible by both the remote V8 and local SAS 9 sessions (for example, the source library is NFS mounted).
Make sure that you have an appropriate user ID and permissions for all physical locations.

Store the migrate_macros.sas (.txt file) program in a location that's accessible by the SAS 9 session.
Copy and paste the text in the migrate_RLStemplate.sas (.txt file) example code into an interactive SAS session and customize the following values in the first two sections of the program:
- three empty directories for the SAS 9 session
- one empty directory for the SAS 8 session
- a server logon script if you have one
- the server pathname
- the location of the existing source library.
Modify the PROC MIGRATE step in the example code with the appropriate options:
```
proc migrate in=lib1 out=lib2 <options>;
run;
```
For detailed information about the options, see the Options section for PROC MIGRATE.
Submit the code.
Note that if you have no catalogs in the source library, the SLIBREF= option and the CATLIB libref in the example are not necessary. They will produce a warning that the SLIBREF= is empty.

Using Validation Tools with Remote Library Services (RLS) from SAS 9 to SAS 9

These steps explain how to modify the migrate_RLStemplate9.sas example code to fit your site's needs. The migrate_RLStemplate9.sas example code is only appropriate for a migration that uses RLS, and only for a migration from one SAS 9 release to another SAS 9 release. If you are not using RLS with your migration, then see Using Validation Tools with Simplest-Case Migration instead. If you're not sure whether these instructions are appropriate for your site, use the interactive PROC MIGRATE Calculator first.

Requirements

This code is submitted in a SAS 9 session, and you must have access to a SAS 9 SAS/CONNECT server that is native to the source library. (The source library is the library that you are migrating from.) If your source library members were created under 32-bit SAS 9, then the SAS/CONNECT server must be running under 32-bit SAS 9. (You could also use SAS/SHARE, but the syntax would be different than the example code.)
The source library must be directly accessible by both the remote and local SAS 9 sessions (for example, the source library is NFS mounted).
Make sure that you have an appropriate user ID and permissions for all physical locations.

Store the migrate_macros.sas (.txt file) program in a location that's accessible by the local SAS 9 session.
Copy and paste the text in the migrate_RLStemplate9.sas (.txt file) example code into an interactive SAS session and customize the following values in the first two sections of the program:
- three empty directories for the target SAS 9 session
- one empty directory for the source SAS 9 session
- a server logon script if you have one
- the server pathname
- the location of the existing source library.
Modify the PROC MIGRATE step in the example code with the appropriate options:
```
proc migrate in=lib1 out=lib2 <options>;
run;
```
For detailed information about the options, see the Options section for PROC MIGRATE.
Submit the code.

Using the MOVE Option and Validation Tools

The MOVE option deletes the source library members after they have been migrated to the target library. This might be helpful if you're migrating to a location on the same computer, and you don't have enough space to duplicate the library. Be aware that the MOVE option significantly limits validation, because the validation tools cannot access members that are removed after migration. The %checkem macro cannot be used.

Follow these steps to use the MOVE option with validation tools:

To compile the macros, copy and paste the text in the migrate_macros.sas (.txt file) tool into an interactive SAS session and submit it.

Copy the following code into an interactive SAS session, edit the LIBNAME statements for your pathnames, and submit the code.

   libname lib1 <engine> 'path to source library';
   libname lib2  base    'path to target library';
   libname ods           'path used by the tools';

Submit the following code:

   %before;
   proc migrate in=lib1 out=lib2 move;
   run;
   %after;

Details about Migrating with Validation Tools

The migration of a SAS library is comprised of three phases:

Before you execute PROC MIGRATE, a snapshot or record of the contents of existing libraries is derived.
PROC MIGRATE is executed.
The migrated libraries are compared to the source libraries for validation.

These steps are contained in the migrate_template.sas tool provided by SAS, which you modify for your specific operating environment.

Because you are likely to have a large number of members in a source library, as well as having different member types, the validation process has been automated with the use of SAS macros within the validation tools.

The following sections explain how the validation tools work. If you need further information, see details about the validation macros.

Before Executing PROC MIGRATE

In order to validate the migration, you must document the members in the source library and the attributes of each member before the migration so you can compare the information after migration to the target library. To understand the reports that are produced with the validation, you must understand the attributes that are expected to change during migration. You will see that different engines are used for different libraries, such as V9 instead of V6. Also, encoding is a new attribute in SAS 9.

Unfortunately, knowing your data is not as simple as knowing what member types exist in a source library. You must consider the hidden complexities of each SAS data set, such as the following:

indexes
integrity constraints
password protection
permanent formats
variable lengths
SAS data set labels
data representation and encoding other than the default

SAS created validation macros to gather the details of the libraries for you. These macros are provided in the migrate_macros.sas tool and are wrapped in a single wrapper macro named %BEFORE. They are executed by the migrate_template.sas tool prior to the execution of PROC MIGRATE.

Executing PROC MIGRATE

After the migrate_template.sas tool runs the %BEFORE macro, the PROC MIGRATE step is executed. You modify the migrate_template.sas tool to include the PROC MIGRATE options that you want to use.

After Executing PROC MIGRATE

The wrapper macro %AFTER includes the macros that compare the source library to the target library. Additionally, the wrapper macro %CHECKEM calls the memtype comparison macros to check the members for final validation of the process. The memtypes that are checked are:

catalogs
SQL views
data files

Why Use Output Delivery System (ODS)?

The new migration process uses ODS for reporting the various steps in the process.

You need a listing of the source library to compare to the target library after the migration. The CONTENTS procedure prints a listing of the contents of a SAS library. You could compare the source library listing to the target library listing manually but this would be time consuming. Using ODS, you will see only a listing of the attributes that are different in the source and target libraries.

Example

Here is an example of the simplest form of the migrate_template.sas tool:


   libname lib1 <engine> 'source-library-pathname';
   libname lib2  base    'target-library-pathname';
   libname ods           'pathname used by the tools';

   %before;
   proc migrate in=lib1 out=lib2;
   run;
   %after;

   %checkem;

If the LIB1, LIB2, and ODS libraries have been defined correctly, and the migrate_macros.sas tool has been compiled in the same SAS session, the %BEFORE macro completes the following steps:

Creates a SAS data set in the ODS library that contains information about the members in the source library before PROC MIGRATE.
Creates global macro (flag) variables for each memtype.
Creates global macro variables that contains the name of each member in the source library before PROC MIGRATE.
Creates a global macro variable that indicates whether or not there are any integrity constraints in the source library before PROC MIGRATE.
If there are any indexes and/or integrity constraints in the source library, %BEFORE creates a SAS data set in the ODS library that describes the indexes, the integrity constraints, audit trails, or generation data sets in the source library before PROC MIGRATE.

The %AFTER macro completes the following steps:

Creates a SAS data set in the ODS library that contains information about the members in the target library after PROC MIGRATE.
If there are any indexes and/or integrity constraints in the source library, %AFTER creates a data file in the ODS library that describes the indexes and/or the integrity constraints in the target library after PROC MIGRATE.
Outputs a side-by-side comparison of the contents of the source library before the PROC MIGRATE with the contents of the target library after the PROC MIGRATE in the SAS output window.

The %CHECKEM macro does the following:

Checks the SAS data set attributes for differences between the source library catalogs and the target library catalogs.
Checks the SAS data set attributes for differences between any SQL views in the source library and the same SQL views in the target library.
Checks the source library and target library attributes for data files and data files with indexes, integrity constraints, audit trails and generations SAS data sets.
Outputs a side-by-side comparison of the source library and target library for each of the above checks.

Results of Migrating with Validation Tools

Results of the %AFTER Wrapper Macro

The %AFTER macro compares the contents of the source library before PROC MIGRATE with the contents of the target library after PROC MIGRATE by comparing the contents of the SAS data sets created in the ODS library and generating a report.

In the example report below, five members were present in the source library and were migrated successfully to the target library. The C_IND member was not migrated presumably because there was a problem during migration. The SQL_VIEW member is not migrated because it is not in the source library and exists only in the target library.

**Report: Contents of the Target Library after PROC MIGRATE (relative to source library)**
Obs	name	MemType	result
1	FORMATS	CATALOG	OK
2	TESTCAT	CATALOG	OK
3	C_IND	DATA	not MIGRATED
4	DATA_SET	DATA	OK
5	ITEMSTORE	ITEMSTOR	OK
6	DATA_STEP_VIEW	VIEW	OK
7	SQL_VIEW	VIEW	not in source library

Results of the %CHECKEM Wrapper Macro

The %CHECKEM macro produces memtype comparison output for only 3 memtypes:

catalogs
SQL views
data files with indexes, integrity constraints, generations, and audit trails

The %CHECKEM macro compares memtypes. It uses the macro variables created by the %BEFORE macro to output the following:

a side-by-side comparison of SAS data set attributes between the source and target libraries
a PROC COMPARE of SAS data set contents

The default behavior of the %CHECKEM macro is to output only those SAS data set attributes and any engine or operating environment data that are different in the source library and the target library.

The first %CHECKEM default output compares the SAS data set attributes and includes the name of the SAS data sets compared in each library.

  DATA1
  Number 2 of 12 SAS data sets in source library
  Differences in PROC CONTENTS header information
  Note: all other header information was the same
  Number 1 of 2 reports for this SAS data set (from
  checkdata macro)

  Obs     attribute     source     target

   1      Encoding      Default    wlatin1 Western
                                           (Windows)
   2      Engine        V8         V9

The second %CHECKEM default output uses PROC COMPARE to compare the SAS data set contents.

  DATA1
  Number 2 of 12 SAS data sets in source library
  PROC COMPARE of data
  Number 2 of 2 reports for this SAS data set (from
  checkdata macro)

  The COMPARE Procedure
  Comparison of LIB1.C_IND with LIB2.C_IND
  (Method=EXACT)

  Note: No unequal values were found. All values
  compared are exactly equal.

The default of %CHECKEM is to output only the SAS data set attributes and engine or operating environment data that are different in the source library and the target library. To output a comparison of all SAS data set attributes and engine or operating environment data, submit the following:

%checkdata(showall=yes);

The first %CHECKEM output with (showall=yes) compares the SAS data set attributes and includes the name of the SAS data sets compared in each library.

  DATA1
  Number 2 of 12 SAS data sets in source library
  Comparison of PROC CONTENTS header information
  Number 1 of 2 reports for this SAS data set (from
  checkdata macro)

  Obs     attribute             source     target

   1      compressed            No         No
   2      Data Representation   WINDOWS    WINDOWS
   3      Data Set Type
   4      Deleted Observations  0          0
   5      Encoding              Default    wlatin1  Western
                                                    (Windows)
   6      Engine                V8         V9
   7      Indexes               1          1
   8      Label
   9      Member Type           DATA       DATA
   10     Observation Length    32         32
   11     Observations          1          1
   12     Protection
   13     Sorted                No         No
   14     Variables             4          4

The second %CHECKEM output with (showall=yes) is exactly the same as the %CHECKEM default output:

  DATA1
  Number 2 of 12 SAS data sets in source library
  PROC COMPARE of data
  Number 2 of 2 reports for this SAS data set (from
  checkdata macro)

  The COMPARE Procedure
  Comparison of LIB1.C_IND with LIB2.C_IND
  (Method=EXACT)

  Note: No unequal values were found. All values
  compared are exactly equal.

FOCUS AREAS