The onsmsync utility

Use the onsmsync utility to synchronize the sysutils database and emergency boot file with the storage manager catalog.

If your storage manager is the OneDB® Primary Storage Manager, you can also use the export and import options of the onsmsync utility to export OneDB Primary Storage Manager backup objects to an external device and import objects from an external device to a device that is managed by the OneDB Primary Storage Manager. You cannot use the export and import options with other storage managers.

>>-onsmsync----------------------------------------------------->

>--+-+-----------------+--+-----+--+-----+--+---------------+--+-------------+-+-->
   | +- -g--generation-+  '- -s-'  '- -O-'  +- -f--filename-+  '- -cf--value-' |   
   | +- -t--timestamp--+                    | .---------.   |                  |   
   | '- -i--interval---'                    | V         |   |                  |   
   |                                        '---dbspace-+---'                  |   
   '- -b-----------------------------------------------------------------------'   

>--+-------------------------------+---------------------------><
   '-| Export and import options |-'   

Export and import options (to use only with the Primary Storage Manager)

|--+- -E-- -p--prefix--+-----------------+-+--------------------|
   |                   +- -g--generation-+ |   
   |                   +- -t--timestamp--+ |   
   |                   '- -l--log_ID-----' |   
   '- -I-- -p--prefix----------------------'

The following table lists all onsmsync command elements, except the elements you use to import and export backup generations. The command elements that you use for importing and exporting are listed in Elements for onsmsync export and import commands.

Table 1. Elements for onsmsync commands
Element Purpose Key considerations
-b Regenerates the emergency boot file (ixbar.servernum) and the sysutils database from each other. If the ixbar file is empty or does not exist, onsmsync -b re-creates the ixbar file and populates it from the sysutils tables.

If the ixbar file is not empty and contains object data, onsmsync -b updates the sysutils database and the ixbar file so that they are in sync.

If the ixbar file has entries and the sysutils database was rebuilt, but is empty because it does not contain data, onsmsync -b recreates the sysutils data from the ixbar file.

Do not use the -b element with the other onsmsync options.

The -b element does not synchronize with the storage manager.
dbspace Specifies the storage space or storage spaces to expire If you enter the name of more than one storage space, use a blank space to separate the names.
-f filename Specifies the path name of a file that contains a list of storage spaces to expire Use this option to avoid entering a long list of storage spaces. The file name can be any valid UNIX™ or Windows™ file name.
-g generation Specifies the number of versions of each level-0 backup to retain The latest generation of backups is retained and all earlier ones are expired.
-i interval Specifies the time interval for retaining backups. The utility:
  • Retains backups that were created after this interval.
  • Expires backups that were created before this interval and removes the backups if expired objects are also removed.

Backups older than interval are not expired if they are needed to restore from other backups after that interval. Use the ANSI or GLS format for the interval: YYYY-MM or DD HH:MM:SS
-O Overrides internal error checks and enforces expiration policy If used with the -t, -g, or -i option, expires all levels of a backup, even if some of them are needed to restore from a backup that occurred after the expiration date. The -O option does not affect logical-log expiration. See Expire all backups.
-s Skips synchronizing expired backups The object expiration is based on other arguments if the -s option is provided.
-t timestamp Expires all backups before a particular date and time Retains backups that completed after the specified timestamp. Backups that occurred before the timestamp are not expired if they are needed to restore from other backups that occurred after the timestamp.

Use the ANSI or GLS_DATETIME format for the timestamp.
-cf Specifies whether to expire the critical files.

When used with the -g, -i, or -t, deletes critical file backups from the OneDB Primary Storage Manager

 The critical files are the onconfig file, the sqlhosts file (on UNIX), the oncfg_servername.servernum file, and the ixbar.servernum file. Valid values are:
  • yes = Deletes backups of the critical files.
  • no = Does not delete backups of the critical files.
  • only = Deletes only the backups of critical files.
Table 2. Elements for onsmsync export and import commands
Element Purpose Key considerations
-E Exports a single backup generation to the OneDB Primary Storage Manager external pool Use this option only if you set up a OneDB Primary Storage Manager external pool.

If you export a backup generation, you must specify a prefix, which identifies the exported backup. The onsmsync utility creates a subdirectory that includes the prefix in the external pool, and deposits the exported objects in that directory.
-g generation Specifies the backup generation to export. The default value is the current backup.
-I Imports a single backup generation from the external OneDB Primary Storage Manager pool. If you import a backup generation from an external pool, you must specify the prefix for exported backup. The prefix identifies the backup generation that you want to import.
-l log_ID Exports the backup generation that includes a logical log ID.
-p prefix Specifies the prefix that you are assigning to a backup generation that you are exporting or are using to identify the backup that you want to import. When the onsmsync utility exports a backup generation, it uses the prefix as the name of the subdirectory in which it places the backup.
-t timestamp Specifies a backup generation that includes a particular date and time (used only for exporting). Use the ANSI or GLS_DATETIME format.

You might want to include the date and time when you roll out a new version of an application.

Usage

If no options are specified, the onsmsync command synchronizes the sysutils database and emergency boot file with the storage-manager catalog. The onsmsync utility compares the backups in the sysutils database and emergency boot file with the backups in the storage-manager catalog and then removes all backups that are not in the storage manager catalog from the sysutils database and emergency boot file.

Tip: To control whether the sysutils database maintains a history for expired backups and restores, use the BAR_HISTORY configuration parameter. For information, see BAR_HISTORY configuration parameter.

The order of the commands does not matter except that the storage-space names or file name must come last.

The order of the commands does not matter except:
  • The storage-space names or file name must come last.
  • When exporting or importing, the -E or -I option must be first. For example, specify onsmsync -E -g 2, not onsmsync -g 2 -E.
Prerequisites for importing and exporting backup generations on different computers:
  • You must have the same version of HCL OneDB on the source and target computers and the computers must use the same operating system.
  • You must set up the OneDB Primary Storage Manager and create an external pool on the source and target computers.

When you use the -E or -I options to export or import a backup generation, you must specify the prefix that identifies the subdirectory where the backup generation is placed.

If you use the -E or -I options to export or import a backup generation, you cannot use any onsmsync command options that are not related to the export or import operation. For example, you cannot export a backup generation and regenerate the emergency boot file at the same time.

The onsmsync -I command renames your current ixbar file and creates a new file hat contains only the information that is necessary to restore the imported backup

You can use the -cf option with the -g, -i, or -t option to delete critical file backups from the storage manager.

If you apply the -g option and the onsmsync utility list of objects contains only logical logs and no space backups, the log backups are not expired. In this situation, use the -t or -i option to expire logical log backups.

Examples

The following example expires backups that started before November 30, 2012: 
onsmsync -t "2012-11-30 00:00:00""
The following command exports the last backup generation to the directory call gen in the external pool:
onsmsync -E -p gen -g 1
The following command exports the fourth most recent backup generation to the directory called gen in the external pool:
onsmsync -E -p gen -g 4
The following command exports the current backup generation to the directory called gen in the external pool: 
onsmsync -E -p gen
The following command exports all backup objects in generation 2 to the directory called gen in the external pool:
onsmsync -E -p gen -g 2
The following command exports all backup objects that have a timestamp of 2012-12-31 12:00:00 to the directory called gen in the external pool:
onsmsync -E -p gen -t 2012-12-31 12:00:00
The following command imports all objects in the subdirectory that is identified by the prefix gen:
onsmsync -I -p gen
The following command imports all backup objects that were exporting using the prefix gen and the timestamp of 2012-12-31 12:00:00. Because the prefix identifies the backup generation, you do not specify a timestamp.
onsmsync -I -p gen

The following command deletes all but the last two generations of critical file backups:

onsmsync -g 2 -cf yes