PREVIEW

Checks for errors that might occur during the migration of the DBEnvironment that would cause the migration to fail. PREVIEW checks for as many errors as it can before a migration, but it does not perform a "test migration." It is still possible for the migration to fail after a preview, but usually this would only occur if the DBEnvironment is corrupt.

Scope

SQLMigrate Only

SQLMigrate Syntax

PREVIEW 'DBEnvironmentName' { FORWARD [TO 'Version'BACKWARD TO'Version']} ;

Parameters

DBEnvironmentName: identifies the DBEnvironment to be previewed.
Version: indicates the version number to which you want to migrate your DBEnvironment. Version is optional in a forward preview. The default is to preview the DBEnvironment against the most recent version supported by SQLMigrate. Version must be indicated for a backward preview. Use the SHOW VERSIONS command to determine the value that may be entered as the version parameter to PREVIEW the migration of a DBEnvironment to the desired release of ALLBASE/SQL software.

Description

The amount of free pages left in the SYSTEM DBEFileSet is calculated. If migration cannot be accomplished because there is not enough space, an error is returned along with an estimate of the additional number of pages needed.
The PREVIEW BACKWARD command checks for database objects which contain functionality that is not supported under an old release. If they are detected, a warning message is issued that the database objects will be dropped during the migration process. You may want to save your table by issuing an ISQL UNLOAD command before migrating your DBEnvironment.
The PREVIEW command is not a read only operation. If the PREVIEW command fails it may leave the DBEnvironment in an inconsistent state. Should the PREVIEW command fail, the DBEnvironment backup must be restored before the DBEnvironment can be accessed.

Authorization

You must be the DBECreator or have SM capability to use the PREVIEW command.

Example 1

In the example below, a forward preview is shown. The warning is always given as a reminder to back up your DBEnvironment. The error indicates that there is not enough space for the migration to occur.

   SQLMIGRATE=> preview 'PartsDBE' forward to 'G';.



   PREVIEW BEGINNING (TUE, AUG 17, 1993, 10:12 AM)



   WARNING - Before continuing, please verify that a complete backup of

             the DBEnvironment exists. (DBWARN 20550)



   Do you want to continue (yes,[no]) ? yes



   ERROR - Insufficient space in the SYSTEM DBEFileset. (DBERR 22540)

     

   DBEFile(s) containing 38 pages need to be added to the SYSTEM 

   DBEFileset before attempting the migration.

     

   Use SQLMIGRATE to first CREATE a DBEFile, and then to ADD it to the

   SYSTEM DBEFileSet.  If you are concerned about the amount of additional 

   space being added, CREATE multiple small DBEFiles, rather than one large 

   one.  After the migration is complete, perform an UPDATE STATISTICS on 

   SYSTEM.TABLE.  Review SYSTEM.DBEFILE to determine the empty DBEFiles in 

   the SYSTEM DBEFileset, and remove them.  Remember to leave about 20% of 

   the pages free for the temporary processing needs of ALLBASE/SQL.



   PREVIEW FAILED with 1 ERROR(s) (TUE, AUG 17, 1993, 10:13 AM)



   An attempt to MIGRATE this DBEnvironment will fail, and leave the 

   DBEnvironment in an inconsistent state.  Please take corrective action

   before attempting the migration.



   SQLMIGRATE=>

At this point you will want to add space to the SYSTEM DBEFileSet. This procedure is shown here:

   SQLMIGRATE=> CREATE DBEFILE partsfile3 WITH PAGES = 40, NAME =`prtfile3';



   The DBEFile was SUCCESSFULLY CREATED in <PartsDBE>.



   SQLMIGRATE=> ADD DBEFILE partsfile3 TO DBEFILESET SYSTEM;



   The DBEFile was SUCCESSFULLY ADDED in <PartsDBE>.



   SQLMIGRATE=>

Issue the PREVIEW command again to make sure that no other errors will be encountered during the migration:

   SQLMIGRATE=> preview 'PartsDBE' forward to 'G';



   PREVIEW BEGINNING (TUE, AUG 17, 1993, 10:13 AM)



   WARNING - Before continuing, please verify that a complete backup of

             the DBEnvironment exists. (DBWARN 20550)



   Do you want to continue (yes,[no]) ? yes



   PREVIEW SUCCEEDED with 1 WARNING(s) (TUE, AUG 17, 1993, 10:13 AM)



   The proposed migration should be successful.



   SQLMIGRATE=>

Example 2

In the example below, a warning is issued that a particular table will be dropped because the column types were only supported under the current release of ALLBASE/SQL. This table was defined under the current release of ALLBASE/SQL and it took advantage of enhancements that exist only under the current release. Remember that the columns that are supported under the new release cannot be loaded into the old DBEnvironment. You should either omit them when the unload is performed or edit the unload file appropriately.

   SQLMIGRATE=> preview 'PartsDBE' backward to 'F';



   PREVIEW BEGINNING (TUE, AUG 17, 1993,  1:23 PM)



   WARNING - Before continuing, please verify that a complete backup of

             the DBEnvironment exists. (DBWARN 20550)



   Do you want to continue (yes,[no]) ? yes



   WARNING - Table PURCHDB.PARTS contains the following columns which are not 

             supported under the target version of ALLBASE/SQL (DBWARN 

             22530): 



             NONCASE             



             This table will be dropped during the migration.



             Please NOTE that any other tables in your DBEnvironment that have

             REFERENTIAL CONSTRAINTS on this table will also be dropped during 

             the migration.  Please verify that a complete backup of this 

             DBEnvironment exists to insure that table(s) are not lost.



   WARNING - View PURCHDB.PARTINFO is defined on a table or view that will be 

             dropped during the migration (DBWARN 22700).  This view will 

             also be dropped.  The SELECTSTRING from SYSTEM.VIEWDEF for this 

             view is: 



              SELECT PurchDB.SupplyPrice.PartNumber, PurchDB.Parts.PartName, 

             PurchDB.SupplyPrice.VendorNumber, PurchDB.Vendors.VendorName,   

             PurchDB.Supplyprice.VendPartNumber,                             

             PurchDB.SupplyPrice.UnitPrice, PurchDB.SupplyPrice.DiscountQty  

             FROM PurchDB.Parts, PurchDB.SupplyPrice, PurchDB.Vendors WHERE  

 		 PurchDB.SupplyPrice.PartNumber = PurchDB.Parts.PartNumber AND   

             PurchDB.SupplyPrice.VendorNumber = PurchDB.Vendors.VendorNumber;

   PREVIEW SUCCEEDED with 3 WARNING(s) (TUE, AUG 17, 1993,  1:23 PM)



   The proposed migration should be successful.



   SQLMIGRATE=>