sync_receive

Imports update packets

APPLICABILITY

SYNOPSIS

• Import update packets:

sync_receive [ -v·ob pattern ] [ -wo·rkdir directory ] [ -lo·gdir log-directory ]

[ -lockwait minutes ] [ -t·race ] [ -q·uiet mode ] [ -d·ata [ packet-file-pname | dir ] ]
[ -a·ctual shipping-order-pname ] [ -s·class storage-class ] [ -o·rigin hostname ]

• Print help on command options:

sync_receive -h·elp

On UNIX, sync_receive is located in ccase-home-dir/config/scheduler/tasks. On Windows, sync_receive is located in ccase-home-dir\config\scheduler\tasks.

DESCRIPTION

sync_receive imports update packets in the local host's incoming storage bays. You can run sync_receive from the command line, or run it with the schedule command (see the schedule reference page in the Command Reference). For information about using sync_receive as a receipt handler, see the shipping.conf and MultiSite Control Panel reference pages.

If files in the incoming shipping bays have names ending with .gz, sync_receive uncompresses the files, determines whether they are packets, and then imports the packets.

RETRYING SYNCHRONIZATION WHEN THE VOB IS LOCKED

By default, synchronization imports fail if the VOB is locked. To allow sync_receive to retry an import when it encounters a lock, use the -lockwait option, which specifies the amount of time (in minutes) for sync_receive to keep trying to write to the VOB. During that time, sync_receive retries the write operation every minute. If the time elapses and the VOB is still locked, sync_receive exits with an error.

The -lockwait option sets the CLEARCASE_VOBLOCKWAIT environment variable in the script's environment. If -lockwait is not used, sync_receive ignores CLEARCASE_VOBLOCKWAIT if it is set outside the script's environment.

NOTE: sync_receive waits only if it detects the lock before it starts processing oplogs. If an administrator locks the VOB during oplog processing, sync_receive exits with an error.

CONFIGURATION FILE

You can modify the behavior of the sync_receive script by creating a file named MSimport_export.conf and setting values in it. On UNIX, create the file in the directory /var/adm/atria/config. On Windows, create the file in the directory ccase-home-dir\var\config.

The file can include the following import settings:

disable_import_locking = 1

Disables use of the import lockfile, allowing multiple imports to a single replica to run simultaneously. Setting the value to 0 (default) enables use of the lockfile.

NOTE: By default, sync_receive fails if there is another sync_receive process importing a packet into the same replica. This failure prevents interference among import processes. Disabling import locking may cause import failures due to collisions. We recommend that you leave locking enabled unless there is a large amount of lockfile contention.

This setting and the -lockwait option are not related. This setting configures use of the lock created by the sync_receive process to prevent interference among import processes, and the -lockwait option handles ClearCase VOB locks.

proactive_receipt_handler = 1

Causes an active receipt handler to look for other packets that can be imported and attempt to import them. By default, a receipt handler imports only the packet for which it was invoked. Under high load conditions, or when packet have been split because of maximum size restrictions, packets may arrive before a preceding packet has been completely processed. Enabling proactive mode causes the receipt handler to import packets that may otherwise be stranded due to premature or out-of-order delivery.

TROUBLESHOOTING

To display informational messages, specify the -trace option on the command line.

To display all debugging print statements, set the TRACE_SUBSYS environment variable to the value sync_receive.

sync_receive creates a log file during execution. This log file is deleted unless sync_receive fails or you use -trace or TRACE_SUBSYS.

By default, the log files are stored in the /var/adm/atria/log/sync_logs directory (UNIX) or the ccase-home-dir\var\log directory (Windows). The name of a log file is based on the process ID of the sync_export_list command and the time at which you ran the command.

On UNIX, the Weekly Log Scrubbing job installed with ClearCase deletes send* and recv* log files in /var/adm/atria/log/sync_logs that are more than 14 days old.

RESTRICTIONS

Identities: You must have one of the following identities:

• VOB owner

• root (UNIX)

• Member of the ClearCase administrators group (Windows)

Locks: An error occurs if one or more of these objects are locked: VOB.

Mastership: No mastership restrictions.

OPTIONS AND ARGUMENTS

-h·elp

Prints help on command options.

-v·ob pattern

VOBs to which update packets are applied. By default, sync_receive applies packets to all VOBs listed in the packet. Specify pattern as a VOB-tag or as a string that can match multiple VOB names. You cannot include wildcard characters in pattern. For example:

-vob /vobs/dev	(apply packets to /vobs/dev and any VOB whose tag contains `/vobs/dev')
-vob dev	(apply packets to any VOB whose tag contains the string `dev')

-wo·rkdir directory

Writes temporary files to directory. directory must exist and be writable by the user who enters the sync_receive command.

-lo·gdir log-directory

Writes log file to log-directory. You must have write access to log-directory. By default, log files are stored in the /var/adm/atria/log/sync_logs directory on UNIX and the ccase-home-dir\var\log directory on Windows.

-lockwait minutes

Number of minutes for the script to keep retrying to write to a locked VOB.

-t·race

Lists command-line options you specified, displays commands as they are executed, displays a success or failure message, and forces sync_receive to keep its log file.

-q·uiet mode

Suppresses messages sent to STDOUT. mode can have the following values:

0	(default when sync_receive is used on the command line) Prints errors, warnings, and informational messages
1	(default when sync_receive is used as a receipt handler) Prints errors and warnings
2	Suppresses all messages

When sync_receive is invoked as a receipt handler, mode is set to 1.

When sync_receive is invoked as a receipt handler, the following parameters are passed in automatically. You can use -sclass, -data, and -actual from the command line.

-s·class storage-class

Imports packets in the incoming bays associated with storage-class. If storage-class does not have incoming bays or you do not specify -sclass, sync_receive imports packets from the shipping bay for the default storage class.You can create and modify storage classes in the shipping.conf file on UNIX or the MultiSite Control Panel on Windows.

-d·ata [ packet-file-pname | dir ]

Full pathname of an update packet or a storage bay. To import only a specific packet, use -data file. To import all packets in a bay, use -data dir. You can use -data with -vob to import packets to specific VOBs. This parameter is used only when the packet is destined for replicas on the current host.

-a·ctual shipping-order-pname

Location of the shipping order; used only when the packet is destined for another host.

If a packet is destined for both the local host and another host, both the -data and -actual parameters are used. The packet is imported at the replica on the local host, and then forwarded to its next destination.

NOTE: This option is not related to the -actual option for chepoch and lsepoch.

-o·rigin hostname

Originating host.

EXAMPLES

• Import packets in the incoming storage bays for the daily storage class.

/usr/atria/config/scheduler/tasks/sync_receive -sclass daily

• Import a specific packet and apply it to all VOBs whose tags include the pattern lib. The lines are broken for readability. You must enter the command on a single physical line.

"c:\Program Files\Rational\ClearCase\config\scheduler\tasks\sync_receive.bat" -vob lib -d
"c:\Program Files\Rational\ClearCase\var\shipping\daily\incoming\sync_orig_09-Dec-98.18.17.54_6587_1"

• On UNIX, specify sync_receive as the receipt handler for the daily storage class.

cp /usr/atria/config/scheduler/tasks/sync_receive* /var/adm/atria/scheduler/tasks

Edit the shipping.conf file and add a receipt handler entry:

RECEIPT-HANDLER daily /var/adm/atria/scheduler/tasks/sync_receive

• On Windows, specify sync_receive as the receipt handler for the daily storage class.

1. Copy the script into a directory outside the ClearCase installation area. For example:

copy "c:\Program Files\Rational\ClearCase\config\scheduler\tasks\sync_receive.bat" c:\scripts

1. Edit the script as appropriate.

2. In the MultiSite Control Panel, select the daily class in the Storage Class list.

3. Click Modify Class.

4. In the Receipt Handler Path box, enter the path to the script. For example:

c:\scripts\sync_receive.bat

5. Click OK.

FILES

UNIX

/var/adm/atria/log/sync_logs
/var/adm/atria/config/shipping.conf
ccase-home-dir/config/scheduler/multisite.schedule

Windows

ccase-home-dir\var\log

SEE ALSO

mkorder, MultiSite Control Panel, shipping.conf, shipping_server, sync_export_list, syncreplica