synbackup utility

WTSupported in traditional Synergy on Windows
WNSupported in Synergy .NET on Windows
USupported on UNIX

 

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.

Note

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.

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 plagues 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 has four backup modes:

You can use synbackup in several different ways:

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

1. Put synbackup into a Pending state (synbackup ‑b) for a short period of time prior to performing a backup.
2. Freeze Synergy updates by setting the backup mode to On (synbackup ‑s) until the backup is complete.
3. 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.

Note

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]

‑c

Create the file DBLDIR: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 `

‑x

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

‑d

Delete the DBLDIR: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.

A file mapping of a physical file (DBLDIR: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 DBLDIR:synbackup.cfg does not exist.

Configuring the backup mode feature on Windows

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]

‑c

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

‑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

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.

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.

Configuring the backup mode feature on UNIX

1. Uncomment the SYNBACKUP=1 line in the distributed setsde script.
2. Run synbackup ‑c to initialize the shared memory segment.
Important

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

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