sync_receive

Imports update packets

Applicability

Product Command type
MultiSite MultiSite command
Platform
UNIX
Linux
Windows

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 | –default } ] [ –o/rigin hostname ]
  • Print help about command options:
    sync_receive
    –h/elp

On Linux and the UNIX system, 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 DevOps Code ClearCase 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 storage 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 operations. If an administrator locks the VOB during operation 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 Linux and the UNIX system, create the file in the directory /var/adm/rational/clearcase/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 caused by collisions. 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 because of 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/rational/clearcase/log/sync_logs directory (Linux and the UNIX system) 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.

The Weekly Log Scrubbing job installed with DevOps Code ClearCase deletes log files in /var/adm/rational/clearcase/log/sync_logs (Linux and the UNIX system) or ccase-home-dir\var\log (Windows) that have the prefix send or recv and the suffix _log and are more than 14 days old.

Restrictions

Identities: You must have one of the following identities:
  • VOB owner
  • root (Linux and the UNIX system)
  • 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 about 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
–vob dev
–wo/rkdir directory
Writes temporary files to directory. directory must exist and be writable by the user who enters the sync_receive command. If you do not specify –workdir, the script uses GetTmpdir() to find a directory.
–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/rational/clearcase/log/sync_logs directory on Linux and the UNIX system 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/uietmode
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, the following parameters are passed in automatically. You can use –sclass, –data, and –actual on the command line. If you do not specify –sclass or –data, sync_receive scans the incoming bays of all defined storage classes and imports all packets. To import packets for the default storage class only, specify –sclass and –default.

–s/class { storage-class | –default }
Imports packets in the incoming bays associated with storage-class or packets in the default shipping bay. If storage-class does not have incoming bays or you do not specify –sclass, sync_receive imports packets from the storage bay for the default storage class. You can create and modify storage classes in the shipping.conf file on Linux and the UNIX system, 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

In these examples, the lines are broken for readability. You must enter each command on a single physical line.

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



    /opt/devops/code/clearcase/config/scheduler/tasks/sync_receive –sclass
    daily

  • Import a packet and apply it to all VOBs whose tags include the pattern lib.



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

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


    cp /opt/devops/code/clearcase/config/scheduler/tasks/sync_receive*


    /var/adm/rational/clearcase/scheduler/tasks

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



    RECEIPT-HANDLER daily /var/adm/rational/clearcase/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\DevOps\Code\ClearCase\config\scheduler\tasks
      \sync_receive.bat" c:\scripts

    2. Edit the script as appropriate.
    3. In the MultiSite Control Panel, select the daily class in the Storage Class list.
    4. Click Modify Class.
    5. In the Receipt Handler Path box, enter the path to the script. For example:

      c:\scripts\sync_receive.bat

    6. Click OK.

Files

On Linux and the UNIX system

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

On Windows

ccase-home-dir\var\log