synbackup utility

Today’s 24/7 customer environments require that backups must be able to occur without having to shut down applications. The synbackup utility provides a means for all cooperating processes to freeze I/O during a Synergy system backup.

A cooperating process is defined as any Synergy program (dbr, dbs, rsynd, isutl -r, fconvert, and any programs that use them) that is started after the backup mode feature is enabled. Therefore, make sure you start any other Synergy products (such as xfServer or xfODBC) after you configure the backup feature. See Configuring the backup mode feature on Windows and Configuring the backup mode feature on UNIX for configuration instructions.

For general information on backups and how synbackup fits into system resiliency planning, see Configuring for resiliency.

The SynergyVSSWriter service turns synbackup on automatically when a Windows system backup begins and turns it off when the backup is finished. See SynergyVSSWriter service for details.

We strongly recommend using SynergyVSSWriter when automating backup processes on Windows.

This topic includes the following:

How is synbackup used?
Synbackup on Windows
Synbackup on UNIX

How is synbackup used?

The primary use of synbackup is to ensure that ISAM files (each made up of two files) are correctly synchronized. The most common problem that can plague an ISAM file is index corruption, where the index file (.ism) and data file (.is1) are not in sync. Copying an ISAM file while it’s performing an update operation is almost certain to make a copy that’s out of sync. Synbackup can help prevent this problem.

Synbackup has four backup modes:

Pending. Backup is about to be performed. The isutl -r or fconvert utility will not begin operations on a file if this mode is set. All other cooperating processes are unaffected.
On. Backup can be performed. All I/O by cooperating processes is frozen, and the isutl -r or fconvert utility will not begin operations on a file if this mode is set.
Off. Backup cannot be performed. All cooperating processes behave normally.
Not Allowed. Backup cannot be performed. The isutl -r or fconvert utility sets this mode when it is in the process of creating a file. When the utility exits (regardless of whether it succeeds or fails), it resets the backup mode to Off. All other cooperating processes are unaffected.

You can use synbackup in several different ways:

You can use synbackup to block ISAM and relative file updates from an application that is completely unaware of the synbackup mechanism itself. By freezing updates with synbackup, update operations will be blocked until synbackup restores updates. You don’t need to add anything to your application to accomplish this. Using synbackup in this manner ensures your ISAM files are synchronized and backed up correctly.
The second use, which requires some application changes, is to use synbackup to warn of an impending stoppage of updates. Making some minor code changes allows your application to detect when synbackup has issued a Pending state. So, before starting a transaction that may span multiple files, the application can detect the Pending state and choose to wait until after updates have been restored. If the application doesn’t wait, the files linked to the transaction might not contain all the changes applied to the transaction. Using synbackup in this manner can ensure your transactions are preserved, provided enough time is given between the Pending state and the On state for users to complete a transaction.
Finally, in addition to the changes made in the second option above, you can make your application log when a user has started a transaction and when that transaction has been completed. In cooperation with other user processes, this information can be made available to the administrator performing the backup operation. Transactions started after the Pending state has been issued should wait. Transactions started before the Pending state are allowed to complete. Once all active transactions have been completed, synbackup can be used to freeze updates. Using synbackup in this manner ensures your transactions are preserved.

The following synbackup sequence of events is typical in a backup scenario:

Put synbackup into a Pending state (synbackup -b) for a short period of time prior to performing a backup.

Freeze Synergy updates by setting the backup mode to On (synbackup -s) until the backup is complete.

Unfreeze Synergy updates by setting the backup mode to Off (synbackup -x).

When the backup mode is Pending or On, DELETEs, STOREs, and WRITEs operations are frozen, and isutl -r and fconvert operations are not allowed. You can change the way your application handles the freezing of update operations using the %SYN_SETSTATE function. (See %SYN_SETSTATE and %SYN_GETSTATE.) The default behavior is to suspend application execution.

To reduce the stoppage time that an application may wait for a backup to occur, consider copying the data files to another location first, which is faster than actually backing them up to a tape device. Then, after restoring updates with synbackup, the backup to tape can be done on the copies.

To display usage information (or help) for synbackup, run it without any options.

Two synbackup modes of operation are supported. If the data files are on the same machine as the user applications, synbackup is administered from that machine. If the data is located on a data server, synbackup is administered from the server and any remote applications must use xfServer.

Synbackup cannot be run from a Synergy/DE Client installation. If it is, a “Backup feature not allowed across network drive” error will be generated. The backup mode feature also is not supported on systems running multiple versions of Synergy.

Synbackup on Windows

You must be a member of the Administrators or Backup operators group to run synbackup. Synbackup only works with data on a file server using xfServer or with local data accessed via clients using Terminal Services.

Synbackup has the following syntax:

synbackup [-c] [-b|-s|-x [-w seconds]] [-d] [-q] [-?|-h]

Options

-c

Create the file C:\ProgramData\Synergex\SynergyDE\dbl\synbackup.cfg. The backup mode is set to Off initially. (Only a member of the Administrators group can use this option.)

-b

Set backup mode to Pending, which means that synbackup will next be run with the -s option. Pending mode gives applications an opportunity to defer update operations until the pending backup is complete.

-s

Set backup mode to On, which freezes all requests for update operations.

-w seconds

Specify the maximum number of seconds to wait for an active isutl –r or fconvert to complete before setting the backup mode. A value of -1 tells synbackup to wait indefinitely until the backup can be performed. The -w option can only be specified in conjunction with -b or -s.

-x

Set backup mode to Off, which unfreezes any requests for update operations.

-d

Delete the C:\ProgramData\Synergex\SynergyDE\dbl\synbackup.cfg file (in other words, disable the backup mode feature). (Only a member of the Administrators group can use this option.)

-q

Display the current backup mode.

-? or -h

Display synbackup command line option help.

A file mapping of a physical file (C:\ProgramData\Synergex\SynergyDE\dbl\synbackup.cfg) is created that contains the backup mode (Pending, On, Off, or Not Allowed). Only cooperating processes that are local to that file are affected. The backup mode feature is disabled when C:\ProgramData\Synergex\SynergyDE\dbl\synbackup.cfg does not exist.

Configuring the backup mode feature on Windows

Initialize the shared memory by running the synbackup utility with the -c option.
This shared memory should be reinitialized on every system reboot. You can accomplish this by creating a scheduled task that is run on startup.

Synbackup on UNIX

Only a system administrator whose effective user ID is root can use synbackup to create or change the backup mode. Otherwise, an error is generated. Any user is allowed to display the current backup mode using the -q option.

Synbackup has the following syntax:

synbackup [-c] [-b|-s|-x [-w seconds]] [-d] [-q] [-?|-h]

Options

-c

Create the shared memory segment for all cooperating processes. The backup mode is set to Off initially.

-b

-s

Set backup mode to On, which freezes all requests for update operations.

-w seconds

-x

Set backup mode to Off, which unfreezes any requests for update operations.

-d

Disable synbackup by removing the synbackup.cfg file and releasing shared memory.

-q

Display the current backup mode as well as the number of current processes that are using synbackup.

-? or -h

Display synbackup command line option help.

The current backup mode (Pending, On, Off, or Not Allowed) is maintained in a shared memory segment on the system. The synbackup utility is used to initialize and maintain this shared memory segment, as well as to set the backup mode to Pending, On, or Off. The base address of this memory segment is stored in the file DBLDIR:synbackup.cfg. So that the runtime does not have to repeatedly open this file, it first checks the SYNBACKUP environment variable. If SYNBACKUP is set, the runtime opens the synbackup.cfg file to retrieve the base address. If SYNBACKUP is not set, the backup mode feature is disabled.

See Synergex KnowledgeBase article 2357 and Files_for_synbackup_for_UNIX in Synergy CodeExchange for more information and scripts to help you automate the process.

Configuring the backup mode feature on UNIX

Uncomment the SYNBACKUP=1 line in the distributed setsde script.

Run synbackup -c to initialize the shared memory segment.

This shared memory segment should be reinitialized on every system reboot. You can accomplish this using a /rc script.

Ensure that all processes wishing to cooperate source the setsde script so the uncommented SYNBACKUP line is honored. (This includes rsynd.)