SAND CDBMS Administration Guide
Virtual Mode Operations

Saving Changes in Virtual Mode: The KEEP CHANGE and APPLY Operations

When secondary virtual instances are shut down, the instance Delta File is deleted, destroying any changes made to that instance. Changes to the master virtual instance (the instance having the same name as the real database) can be preserved using the SHUTDOWN...KEEP CHANGE command and the -APPLY option of the nserv invocation.

SHUTDOWN...KEEP CHANGE

When shutting down the master virtual instance from an SQL session connected to the master virtual instance, the KEEP CHANGE argument can be included in the SHUTDOWN IMMEDIATE or SHUTDOWN DEFERRED command to write any changes made to that instance to the real database. Note that only the user DBA (or another user that has been granted DBA privileges) can execute this command.

The syntax of the command is as follows:

SHUTDOWN { IMMEDIATE | DEFERRED } KEEP CHANGE [ 'update-file-name' ]


'update-file-name'
An 'update-file-name' argument may be included, with or without a file path, to give a user-defined name to the Update File used for the KEEP CHANGE operation. Quotation marks must enclose the Update File path and name.

If an update file name is not provided, the Update File will be given the same name as the database, with the extension .Cxx (where xx corresponds to the number of the database checkpoint to which the changes will be applied).

Example:

SHUTDOWN DEFERRED KEEP CHANGE ;


The command in this example defers shutdown of the database instance until all other users have disconnected. Then, it converts the master instance Delta File into an Update File (which by default will have the same name as the database) and shuts down the nserv that is running the instance. Finally, it automatically applies the changes contained in the Update File to the real database.

The Update File

If the optional 'update file name' argument is included, the SHUTDOWN...KEEP CHANGE command copies the Delta File contents into an Update File with that name. A path specification can be included in the 'update-file-name' argument; if no path is specified, the Update File is saved in the directory specified by the DatabasePath parameter in the nucleus.ini section for the instance. After the Update File has been created, its contents are applied to the database automatically.

The file extension of the Update File indicates the last database checkpoint to which the changes are applied:
 

file-name.Ccheckpoint-number




The Update File is useful for performing incremental backups, since once a full backup has been performed, only this file will be required to recover changes made to the database. 

APPLY

Including the -APPLY keyword instructs nserv to write the changes contained in the specified Update File to the real database when starting the master virtual instance, thereby making these changes permanent. The -APPLY option can be used in the following cases:

• a KEEP CHANGE operation has created the Update File but failed to complete the application of the changes to the real database
• the Update File is being used to update multiple copies of the database in different locations.


To apply changes from an Update File, use the following syntax:

nserv connection-name instance-name -APPLY update-file-name


The APPLY keyword must be prefixed with a hyphen ( - ), and must be followed by the name of the Update File containing the changes to be applied to the database.

Note that if a KEEP CHANGE or -APPLY operation fails, a -APPLY must be executed (or re-executed) on the database to return it to a stable state. Until the changes in the Update File are successfully applied, the nserv program will not be able to start an instance of the database.

Important!
When an Update File created for a particular database is applied to a different database (for example, a copy made to another directory), it will overwrite the latter's file configuration, returning it to the original settings. Use care when performing the APPLY operation in these circumstances.